Grove Documentation

Tool Declarations

[Preview] -- Tool declarations are part of the agent system currently in development.

Tools bridge agents to your domain logic. A tool declaration defines the input contract, output contract, and the operation to perform -- typically wrapping a Grove action, query, or external service call.

Prerequisites: Agent Declarations. What you'll learn: How to declare tools that agents can invoke.

Tool Declaration

tool lookup_order {
  description "Look up an order by ID and return its current status"

  input {
    order_id: Id
  }

  output {
    order_id: Id
    status: String
    items: List<OrderItem>
    total: Decimal
  }

  data result {
    query orders.get_by_id {
      id: input.order_id
    }
  }

  apply {
    return {
      order_id: result.id,
      status: result.status,
      items: result.items,
      total: result.total
    }
  }
}

Fields

FieldRequiredDescription
descriptionYesHuman-readable description (used by the LLM to decide when to use the tool)
inputYesInput fields with types
outputNoOutput fields with types (if the tool returns data)
dataNoData blocks for fetching/invoking operations
applyNoTransform logic for the result

Wrapping Actions

Tools can invoke Grove actions directly:

tool process_return {
  description "Process a return for an order item"

  input {
    order_id: Id
    item_id: Id
    reason: String
  }

  output {
    return_id: Id
    status: String
  }

  data result {
    invoke returns.create {
      order_id: input.order_id
      item_id: input.item_id
      reason: input.reason
    }
  }

  apply {
    return {
      return_id: result.id,
      status: "initiated"
    }
  }
}

Wrapping External Services

Tools can also call external services:

tool search_products {
  description "Search the product catalog by keyword"

  input {
    query: String
    max_results: Int = 10
  }

  output {
    products: List<ProductSummary>
  }

  data results {
    fetch catalog.search {
      q: input.query
      limit: input.max_results
    }
  }

  apply {
    return { products: results.items }
  }
}

See Also