Tool usage guidance for agents

This document is for tool authors and host projects. It explains how to describe tools so that AI agents (MCP clients) understand how to use them.

What the agent sees

When the agent calls tools/list, it receives for each tool:

  • name – Tool identifier (e.g. PREFIX__methodName if a prefix is configured)
  • description – Text from rpc_methods.description
  • inputSchema – JSON Schema for arguments (from parameter types / params_types)

The agent has no other built-in context. So usage instructions must be in the description (or in a resource the agent can fetch).

Writing descriptions so agents know how to use the tool

Put usage guidance in the description field in rpc_methods (e.g. in a migration that inserts or updates the row). Include:

  1. What the tool does in one sentence.
  2. Query parameter: If there is a query (or similar) argument, say what to put in it – e.g. "Space- or comma-separated terms (e.g. keywords, tags). The agent should pass the terms the user asked for."
  3. Filters: If there is a filters (or similar) object, list supported keys and meaning – e.g. "Optional. Keys: range filters, status, location id, date range, limit, offset."
  4. Response shape: Briefly say what the tool returns – e.g. "Returns items (array of matches, each with an id, relevance or score, and optional match details) and total (total count). Use limit and offset for pagination."

That way the agent knows how to form the query from the user's request, when to use filters, and how to interpret the result.

Example: search-style tool

For a tool that searches entities by terms (e.g. skills, tags, keywords):

  • Query: Tell the agent that query is a string of search terms, ideally space- or comma-separated, and that it should extract those terms from the user's question (e.g. "find X with A and B" → query: "a b").
  • Filters: Document optional filter keys (e.g. range filters, location, status, date range) so the agent can pass them when the user adds constraints.
  • Response: State that the tool returns a list of matches (items) and a total count (total), and that limit / offset control the page size and offset.

Example description text for such a tool (to store in rpc_methods.description):

Search by terms (e.g. skills, keywords). Query: space- or comma-separated terms; the agent should pass the terms the user asked for. Filters (optional object): document your supported keys (e.g. range, status, location id, date range); use limit and offset for pagination. Returns items (array of matches with id, relevance/score, and optional match details) and total count.

With a description like this, the agent can correctly map the user’s intent to query and filters and interpret the response.