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

The description declares "Idempotent on artifact_id", but the annotations set idempotentHint: false, which per MCP semantics means repeated identical calls have additional effect. That is a direct conflict on the single most retry-relevant property of a write tool. The remaining context (parent hashes may be external roots, no genesis index consumed) is genuinely useful, but the contradiction dominates.

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?

Three short sentences, front-loaded with the operation, then the parent-hash semantics, then the side-effect constraint. No filler or restatement of the name.

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?

An output schema exists, so return values need no explanation, but for a six-parameter provenance-graph write with zero schema coverage the description leaves key mechanics unstated: valid relation values, what metadata_digest is a digest of, and what happens on a duplicate artifact_id with differing parents. Adequate as a sketch, not sufficient to call confidently.

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 must carry all six parameters and it covers only part of two: artifact_id (idempotency key) and parent_hashes (registered artifact or external root). relation's allowed values (default "derived_from"), metadata_digest, and producer_agent_id are entirely undocumented anywhere.

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 ("Register a content-addressed artifact") plus its destination ("a separate provenance DAG"), which separates it from the read-side siblings like get_artifact and verify_artifact. Differentiation from register_genesis is only hinted at via the genesis-index clause, so the distinction still leans on domain jargon an agent must already know.

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?

There is no explicit "use this when..." statement; usage is implied by the operation itself. The clause "does not consume a genesis index" implicitly routes genesis creation to register_genesis, but the agent must infer that, and no prerequisites or exclusions are stated.

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