find_tool

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

With no annotations, the description carries the full burden. It discloses that it returns matching sections including signatures, enum values, return keys, and error codes. It also mentions it works with Fusion closed, implying no dependency on Fusion state. It doesn't mention side effects because it's a read-only search, which is fine. It could benefit from noting any rate limits or auth, but not essential.

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 concise and well-structured: first sentence states the action and target, second lists return contents, third gives usage scenarios. No fluff, each sentence earns its place.

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?

The tool is moderately complex with no output schema, so the description should explain returns, which it does. It covers the main use cases and constraints (works with Fusion closed). It's not exhaustive but sufficient for an agent to understand what the tool does and when to use it. Missing details like query syntax or limit behavior slightly reduce completeness.

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%, so the description must explain the parameters, but it doesn't. It doesn't describe what 'query' should contain or how 'limit' behaves beyond the schema's default. The description only mentions 'by intent or symptom' but doesn't provide examples or clarify the query format. This is a significant gap given the coverage.

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 clearly states the tool searches the server's tool reference (tools.md) by intent or symptom. It names the specific resource and action, and distinguishes it from sibling search tools like find_api, find_pattern, and find_gotcha by focusing on how to call tools and interpret errors.

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?

It explicitly says when to use: to look up how to call a tool instead of guessing arguments, and to check error codes. It also notes it works with Fusion closed, which is a useful context. It doesn't explicitly mention alternatives, but the 'instead of guessing' gives clear use case.

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