gc_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, and it does well. It discloses distinct behavioral traits: superseded facts are EXCLUDED by default, each fact may include a superseded_by field, the fallback to deep-memory only occurs if local results are absent and the backend is available, and mode behavior is spelled out (pure BM25 debug for full, HS-imports for deep). Missing are details on pagination, exact cost boundaries, or error behavior, but the coverage is strong given no annotations.

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 efficiently structured and front-loads the core purpose and key differentiator (instant, zero cost). Sentences earn their place: the FTS5/BM25 note, the fallback behavior, the exclusion default, and the audit use case are all substantive and non-redundant. It's slightly longer than minimal but every clause adds value.

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 search tool with 6 parameters and no output schema, the description covers the essential behavioral context: result ranking, bank attribution, supersession handling, backend fallback modes, and audit use cases. Without an output schema, the description notably compensates by describing what returns look like (ranked facts, superseded_by field, match scores). Slightly more could be said about interaction with gc_banks or timeout/cost expectations, but it's largely complete.

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 100%, so all 6 parameters are documented in the schema itself. The description adds marginal value beyond the schema by elaborating on the hindsight fallback semantics and the include_superseded superseded_by field, but these largely mirror what the schema already declares. Baseline 3 is appropriate since the schema does the heavy lifting.

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 verb+resource ("Search the memory bank for facts") and immediately distinguishes this from siblings by highlighting performance characteristics (FTS5/BM25, instant, zero cost) and the deep-memory fallback. It covers ranking, attribution, and match scores, giving a complete picture of what the tool does and its unique value among the gc_* memory/search family.

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 explicitly explains when to use include_superseded (historical audits) and when not to (default current truth only). It also distinguishes the local fast path from the expensive deep-memory fallback, giving clear guidance on when the tool is cheap vs expensive. The mode parameter is explained across linear/deep/full semantics, giving the agent clear selection criteria.

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