quipu_overlay_write

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

Annotations already declare destructiveHint=true and openWorldHint=true, so the safety profile is covered. The description adds real value by clarifying that tombstoning 'masks the parent branch's fact in the composed view without touching the committed layer,' which bounds the blast radius. It does not disclose idempotency, whether re-asserting an existing triple errors, or the result of the write, which matters for a mutating tool with no output schema.

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?

Two sentences, no filler, with the core action front-loaded and the non-obvious tombstone semantics second. Every clause carries information the structured fields do not.

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?

All six parameters are schema-documented, so the input side is covered, and the op semantics are clarified. But with no output schema, the description should say what a successful write returns, and it omits preconditions (must the overlay exist? is the write transactional?) plus the meaning of the optional timestamp defaulting to now.

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%, so the baseline would be 3. The description exceeds it by explaining the semantics of the 'op' enum values — particularly that tombstone masks a parent-branch fact rather than deleting data — which the one-line enum description ('Overlay primitive to apply') does not convey. It also implies one triple per call, which the schema's flat shape alone does not make explicit.

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 and resource ('Write one overlay primitive ... a triple in an overlay graph') and enumerates the three operations, so it is immediately distinguishable from base-layer writers like quipu_retract or quipu_set. It stops short of naming a sibling tool explicitly, so the differentiation is implied by the word 'overlay' rather than spelled out.

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?

Usage is implied rather than stated: the agent can infer this is the tool for overlay-layer edits, and the tombstone sentence hints at when masking is appropriate. There is no explicit 'use X instead when Y' guidance — nothing says when to prefer quipu_overlay_compose, quipu_overlay_create, or base-layer quipu_retract, nor whether the overlay graph must already exist.

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