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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds substantial behavioral context: it is 'free, never gated,' ranks by keyword overlap, returns up to `limit` results, specifies the result shape `{name, purpose, toolset}`, and explicitly states that no tool is renamed or hidden by the search. It even provides design rationale tied to a past failure mode.

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 longer than average but highly information-dense, beginning with the core purpose and flowing through usage, return format, and caveats. The R1 reference adds useful rationale but is slightly verbose; still, nearly every sentence contributes to correct usage.

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?

Despite having no schema-level descriptions and three parameters, the description fully covers query semantics, limit behavior, output format, toolset names, and the scope of the search. With an output schema present and annotations covering safety/idempotency, nothing an agent needs to correctly call this tool is missing.

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 carries the burden of explaining parameters. It does so for `query` ('keyword or short phrase... matches rank by keyword overlap') and `limit` ('returns up to limit (default 10, max 50)'). However, `caller_id` is not explained, leaving one of three parameters undocumented.

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 opens with a precise statement: 'Keyword search over the full Crank tool catalog (progressive disclosure).' It names the specific resource (the Crank tool catalog), the operation (keyword search), and clearly frames the tool as a discovery aid, which distinguishes it from the many actual trading/operation siblings.

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 explains exactly when to use this tool: when a discovering agent does not want to load the full catalog into context, and directs the user to alternatives for deeper information: 'call the tool itself, or get_trading_workflow, for the full picture.' It also clarifies what it is not for: 'purely a discovery aid,' and that no tool is renamed or hidden.

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