recall

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It transparently states that ranking blends text match with recency-weighted activation, that archived nodes are excluded by default, and that each result includes an explanation for why it surfaced. These are non-obvious behaviors that an agent needs to know. It does not mention edge cases like empty results or performance characteristics, but for a retrieval tool the disclosed behaviors are significant and adequately cover the essential operational aspects.

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 two sentences long, front-loads the primary action, and every clause adds meaningful information: the ranking mechanism, the archive exclusion condition, and the explanation feature. There is no fluff or repetition of schema details. The structure efficiently communicates the tool's behavior without unnecessary length.

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?

Given the tool's moderate complexity (3 params, 1 required) and that an output schema exists, the description covers the essential aspects an agent needs: what the query is, how ranking works, the cold-node handling, and that results include explanations. It does not need to describe return structure since the output schema handles that. The description is complete for the task—there are no critical gaps that would prevent correct invocation.

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 compensate for undocumented parameters. It explicitly explains the meaning of 'k' (the number of nodes to retrieve), 'include_cold' (a flag to include archived nodes), and 'query' (the search input). This goes beyond the minimal schema definitions and adds value, particularly clarifying that k controls result count and include_cold toggles archive inclusion. The description effectively fills the gap left by the schema's lack of parameter descriptions.

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 clear verb and resource: 'Retrieve the k most relevant nodes for a query.' It immediately distinguishes the tool as a query-based retrieval mechanism, and the mention of ranking blend (text + recency) and exclusion of archived nodes sets it apart from siblings like 'neighbors' (graph traversal) or 'remember' (storage). The description clearly communicates a distinct purpose without relying on the tool name alone.

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 provides contextual usage details: it explains the archiving behavior and the include_cold flag, which tells the agent when to set include_cold=True. However, it does not explicitly compare this tool to alternatives (e.g., when to use 'neighbors' or 'review_queue' instead) nor state any exclusions or prerequisites. The usage context is implied through the retrieval scenario, but there is no explicit 'use this when X, otherwise use Y' guidance.

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