nest_digest

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, covering the safety profile. The description adds contextual behavior: it suppresses person names, date timeline, and source filenames (explaining why: they are content, not structure), and it notes the full digest is local-CLI only. No contradiction with 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 front-loaded with the core purpose, then explains what is suppressed and why, and ends with the scope limitation. It is concise, with no filler, and every sentence earns its place. It could be slightly tighter but is well-structured.

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?

The description explains the output content well (category breakdown, clusters, secret kinds, file-reading method) but omits any explanation of the input parameters (app_id, db_path) and does not state preconditions (e.g., must have a seeded Nest DB). Since there is no output schema, the description also doesn't specify the exact structure of the Markdown. These gaps make it incomplete for a tool with 0% schema parameter coverage.

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 bears the full burden of explaining parameters. It never mentions app_id or db_path, what they mean, or how they are used. An agent would have to infer that 'app_id' identifies a Nest DB, but no explicit semantics are provided. This is a critical gap for a tool with two parameters.

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 a specific verb ('map'), resource ('seeded Nest DB'), and output format ('one-page Markdown'), and scopes it to 'the WALLED view'. It also contrasts with the 'full unwalled digest' which is explicitly a local-CLI affordance, so an agent can distinguish this tool from any potential alternative that might return the full dataset.

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 gives clear context that this is the MCP-accessible digest (the full unwalled digest is never returned over MCP), effectively excluding that alternative. However, it does not explicitly name sibling tools like nest_scan or nest_status or state conditions for when to pick this over them, so it stops short of explicit when/when-not guidance.

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