find_tool

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Even beyond the readOnly, openWorld, idempotent, and destructive annotations, the description discloses deduplication behavior, the exact/semantic/keyword match categories, inclusion of generated-only disabled tools, safety-flag provenance, and compact-by-default responses. This is substantial behavioral transparency and does not conflict with any annotation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the most important instructions ('Call this first'), followed by the dispatch contract, match behavior, filters, and parameter documentation. Despite its length, the content is dense with useful detail and parallel in structure, making it well organized for an 8-parameter discovery tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 8 parameters, multiple filter dimensions, sibling routing, and a rich output schema, the description is complete: it covers when to call it, what the results contain, how matches are labeled, how to control schema verbosity, and how to dispatch the selected tool. Nothing critical is left to inference.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, but the Args section fully compensates. It defines all 8 parameters, giving query example usage, top_k range and default, include_schema trade-offs, platform/server examples, capability values, origin values, and operation_id meaning. The description therefore adds crucial semantics that the schema alone entirely lacks.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description begins with a specific action ('Find tools by query') and explains the search mechanism ('semantic search + tool-name keyword match'). It distinguishes itself from the sibling invoke tools by stating that the returned `name` is the value to pass to invoke_read_tool or invoke_tool, so the purpose is unmistakably a discovery tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description is prescriptive: 'Call this first when you need an action.' It also tells the agent when to use include_schema ('only when you need the full JSON schema'), when to keep responses compact, and how to route a discovered tool to the correct sibling. It also explains the conditions under which filters should be applied.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.