report_gaps

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

With no annotations present, the description carries the full burden and does: it declares read-only ('proposes nothing and changes nothing'), explains the miss-count field, and decodes awaiting_review as a case where re-writing would duplicate existing work. That last point is exactly the kind of non-obvious behavior an agent would otherwise get wrong.

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?

Front-loaded with the core idea, then the usage cue, then the caveat. Slightly sprawling across five sentences, but every sentence after the first adds a distinct decision the agent must make.

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?

No output schema exists, and the description covers the entry shape well enough (miss count, awaiting_review flag) for a read-only tool. The remaining hole is the undocumented min_count threshold, which is the one thing an agent must set to get useful results.

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?

The single parameter min_count has 0% schema description coverage and is never mentioned by name in the description. The phrase 'Each entry carries a miss count' gestures at the concept, but nothing states that min_count is the threshold that filters entries, nor what the default of 2 implies.

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 opening line is evocative rather than literal, but combined with 'Each entry carries a miss count' and the awaiting_review explanation, it's clear this reports repeatedly-failed searches. It explicitly positions itself next to retrieve_context, so an agent can distinguish the two.

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?

Explicit timing ('call at the START of a session'), an explicit pairing ('next to retrieve_context'), and a concrete decision rule: if your upcoming work appears here, write log_session at the end. It also warns when NOT to act on a gap (awaiting_review) and what to do instead.

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