audit

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

With no annotations provided, the description carries the full behavioral burden and does so exceptionally well. It discloses return shapes for every mode (wrapped objects, never a bare array), empty result conventions, truncation flags, per-mode default caps and max limits, the fact that archived is not a complete listing, conflict exclusions (pairs linked by contradicts, resolved, resolved_by, or supersedes), the additive nature of resolution connectors, and the candidate-only nature for conflicts and kind_coverage. It also warns against autonomous actions ('never auto-revise', 'present to user; never archive autonomously').

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 long and dense, but it is a complex five-mode tool and every section carries operational importance. It is front-loaded with the purpose and core return-shape rule, then organises details by mode. A slight credit deduction for the wall-of-text approach: bullet points or section headers would improve scannability in a high-temperature model, but the density is supportable and not repetitive.

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?

Though there is no output schema, the description enumerates every mode's return fields, empty-result shapes, and truncation flags, which fully compensates for the missing structured output definition. It also covers edge conditions (archived cap), policy constraints (never archive autonomously), and practical actions (raise limit, use recall for full content). For a tool of this complexity, an agent has everything needed to invoke it correctly and interpret the response.

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 schema already has 100% coverage with descriptions for all 7 parameters, but the tool description adds substantial meaning beyond the schema. It explains the depth-2 BFS neighbourhood scope of memory_id, clarifies that memory_id is ignored for non-stale modes, elaborates the archived cap semantics, explains the digest collapse behavior for each mode, gives per-mode default limits, and details the conflicts edge exclusions. These are not merely restated schema defaults — they enrich the agent's understanding of parameter behavior and interaction.

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 specific, actionable statement — 'Inspect the health of knowledge in a domain across five modes' — which clearly names the operation (inspect), the resource (knowledge), and the scope (domain). It then enumerates all five modes (stale, orphans, archived, conflicts, kind_coverage), each with a precise purpose, which distinguishes it from sibling tools like recall, search, and history. The clarity allows an agent to identify this as a scanning/health-audit tool rather than a retrieval or mutation tool.

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 explicit guidance in several places: for archived it says 'Use when search returns nothing but you expect content to exist,' and it repeatedly commands 'when results_truncated is true, you MUST raise limit and call again' and 'never archive autonomously.' It gives contextual direction for each mode (e.g., scope to a domain for focused maintenance passes, supply tags to scope to a workstream). It does not name specific sibling alternatives for all modes, but the use case for each mode is clear enough that an agent can decide when to call audit versus other tools.

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