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

Annotations already declare readOnly, idempotent, and non-destructive, but the description adds substantial context beyond them: the error contract (never raises a protocol error, returns {"error": ...}), and the guarantee that correcting input makes retry safe. This is exactly the kind of behavioral disclosure annotations cannot carry.

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 and the free/cheap framing are front-loaded, and each paragraph (what it does, example I/O, when to use, when not to, error behavior) earns its place. Minor deduction for the marketing-ish "FREE" and the awkward mid-sentence line break in the second paragraph.

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 a two-object-diff tool with an output schema, the description covers the remaining ambiguity – input shape, output shape, error handling, retry safety, and the boundary with graph_upsert. An agent has everything needed to call it correctly on the first try.

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 coverage is 100% and both params are documented as "earlier" and "later" graph documents, so the baseline is 3. The description adds value with a concrete typical input example ({"before": {...}, "after": {...}}) and names the graph concepts the documents contain (entities, observations, relations), which the schema leaves opaque.

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?

States a specific verb and resource: "Say exactly what changed between two versions of a memory," and immediately differentiates from the merge use case by naming graph_upsert. An agent can distinguish it from graph_at_time, graph_search, and graph_upsert without opening any schema.

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?

Gives concrete when-to-use contexts (after an upsert to record what a session learned; between two agents to compare knowledge) and an explicit when-not-to-use with the correct alternative ("Not for merging the two - feed the differences back through graph_upsert"). Nothing is left to inference.

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