project_diagrams

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

Annotations declare destructiveHint=true and readOnlyHint=false, so the safety profile is already carried. The description nonetheless adds genuinely non-obvious behavioral facts: the render/acknowledge separation ("Rendering never acknowledges code accuracy"), hash-bound acknowledgment semantics, the path confinement rule, and the disclosure default for metadata export. The notable gap is that it never explains which action is destructive or what data can be lost.

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 purpose is front-loaded in the first sentence and every later sentence carries constraints, but the long comma-spliced action list ("Check/validate... render... list... produce... or acknowledge...") is dense and hard to parse, mixing action enumeration with the rules that apply to those actions.

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 an 11-parameter, seven-action, destructive tool with no output schema, the description covers a lot of ground but omits the info action entirely, never maps the enum values to their parameters, and leaves the destructive behavior and its scope unspecified.

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% across 11 parameters, so the description must compensate. It does add implicit meaning for several ("project manifest" → manifest, "Git base" → base, "changed paths" → changedFiles, "exact hashes" → sourceHash/referenceHash, "optional managed docs" → writeDocs), but leaves ids, limit, and cursor entirely unexplained, so compensation is only partial.

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 sentence gives a specific verb+resource ("Maintain repository diagrams using a project manifest") and the following clauses enumerate the seven action verbs, which separates it from the drawing-level siblings (create_drawing, edit_drawing, check_drawing) by operating at the manifest/repository scope. However, the multi-action nature means the agent still cannot tell which behavior maps to which enum value, and the "info" action is never described at all.

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 action listing implies usage ("Check/validate freshness", "list affected drawings from changed paths/Git base") and gives constraints ("Paths stay inside the manifest directory", rendering never acknowledges accuracy), but there is no explicit statement of when to prefer this tool over siblings like check_drawing or preview_drawing, nor any when-not guidance.

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