Project Map context - current code structure plus brain decisions

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

Annotations already provide idempotentHint=true and destructiveHint=false, so the read-only safety profile is covered. The description adds valuable non-obvious behavioral details beyond annotations: KLYPIX never installs or runs Graphify, never copies graph nodes into brain.klypix, degrade-to-brain-only fallback, project-root confinement, and that deep_history may cold-load a local model. A 5 would require more detail about output shape or failure modes; a 4 fits.

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 dense but organized: purpose first, then key behaviors, fallback, constraints, and the deep_history caveat. Each sentence adds real value. It loses one point because some deep_history detail is repeated from the schema description, but overall it is efficiently front-loaded.

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 8 parameters, 100% schema coverage, annotations for idempotency/destructiveness, and no output schema, the description covers the critical missing context: what the combined context contains, source fallback behavior, project-root safety rules, model-loading performance trap, and graceful degradation. An agent has enough to invoke it correctly without surprises.

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 every parameter is already well-documented in the schema. The description reinforces deep_history's tradeoff and the root-escape restriction, but it does not need to add full param semantics because the schema carries that weight. Baseline 3 is appropriate.

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 states a specific verb ('queries') and a clear resource ('combined read-only context' from project graph plus KLYPIX brain cards). It distinguishes itself from the many brain/canvas siblings by describing its provider-neutral graph source and correction-aware brain cards. An agent can understand exactly what this tool returns and how it differs from related read tools.

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 explicit when-to-use guidance for deep_history ('only when superseded history is genuinely needed') and explains the default avoids loading the local embedding model. It also states boundary conditions: source-file anchors are accepted only inside the project root, and missing graph artifacts degrade cleanly to brain-only context. This is concrete and actionable.

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