agent-provenance

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so 'Read-only' in the description is largely redundant. The one genuinely new behavioral fact is 'free' (no cost/quota impact), plus the 'call it first' sequencing advice.

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 short sentences, front-loaded with the verb and the enumerated output, followed by the cost and ordering hint. Nothing is padding.

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 shape need not be spelled out, and the description already names the key fields it yields. For a no-arg, read-only meta tool, an agent has everything needed to invoke it correctly.

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?

The tool takes zero parameters, so there is nothing for the description to disambiguate beyond confirming it needs no arguments. Baseline for a 0-param tool.

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 ('Describe') and resource ('this agent') and enumerates exactly what is returned: name, version, purpose, supported actions, and their inputs. No sibling tool does self-description, so an agent can distinguish it immediately from the artifact/certificate 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?

Explicitly says 'call it first to learn how to use this server', which is a concrete usage trigger and ordering instruction. It lacks a when-not condition or named alternative, but no sibling is a plausible substitute for self-description.

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

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

Annotations already declare readOnly/idempotent/non-destructive and closed-world, so the safety profile is covered. The description adds nothing beyond that — no not-found behavior, no error conditions, no statement that it returns the registered artifact record rather than the artifact content.

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?

A single front-loaded sentence with no padding. Brevity is appropriate, though at this length it's arguably under-specified rather than optimally tight.

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?

Output schema and annotations cover return shape and safety, so the burden is light for a simple getter. Still missing the identifier format and lookup-failure semantics, which an agent needs to invoke it correctly.

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 supply parameter meaning, yet it only restates the identifier name. It doesn't indicate the expected format (UUID, path, name) or where an artifact_id comes from.

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 ('Fetch one registered artifact') scoped to a single record. The word 'one' implicitly separates it from list_artifacts, though no sibling is named explicitly.

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?

No guidance on when to choose this over list_artifacts or recall, and no mention of what happens when the artifact isn't found. The single-item scope is the only implied usage signal.

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

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

The annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so safety behavior is covered. The description adds useful context by saying the response includes genesis certificate plus recall/quarantine status, but it does not discuss permissions, error behavior, or freshness of the status data.

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 a single, front-loaded sentence with no redundant or filler language. It communicates the retrieved resource and the two key status components efficiently.

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?

This is a low-complexity getter with one required parameter, rich annotations, and an output schema, so the description does not need to explain return structure in detail. It is nearly complete for invocation, though it leaves the relationship to verify_certificate and the meaning of agent_id unstated.

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 schema provides only the parameter name agent_id with no explanatory text. The description implies that the tool operates on an agent, but it never defines the agent_id format, source, or constraints, so it only partially compensates for the missing schema documentation.

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 gives a clear verb-and-resource pair: 'Fetch' an agent's 'genesis certificate' plus 'recall/quarantine status'. It is understandable without opening the schema, but it does not explicitly distinguish itself from the sibling tool verify_certificate, which is the main ambiguity an agent might face.

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 states what the tool retrieves but gives no explicit when-to-use guidance, no prerequisites, and no alternatives. It does not tell the agent when to choose get_certificate versus verify_certificate, recall, or describe_agent.

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

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

The description presents lineage as a retrieval operation ('Full ancestry and descendants'), but annotations declare readOnlyHint=false. This directly conflicts with the notion that the tool only reads existing lineage data, and the description does no work to explain any mutation, side effect, or permission requirement that would justify the annotation.

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 a single front-loaded sentence with no wasted text. It immediately states the scope of the result and the accompanying generation number.

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?

The tool is structurally simple and has an output schema, so the description need not explain return values. However, the missing usage guidance and the unexplained mismatch with readOnlyHint=false leave important context gaps for an agent deciding whether and how to invoke it.

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?

The only parameter is agent_id, and schema description coverage is 0%. The description adds no meaning about what the identifier represents, accepted formats, or how to obtain it, leaving the agent with less semantic clarity than the simple parameter name might suggest.

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 gives a specific verb/resource pair: it retrieves an agent's ancestry, descendants, and generation number. This is clear enough to understand the tool's core function, but it does not distinguish it from siblings such as describe_agent or recall, which may also surface relationship or historical data.

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 guidance on when to use this tool instead of alternatives like describe_agent, recall, or verify_artifact. The description states what the tool returns but does not mention prerequisites, exclusions, or the conditions under which an agent should call it.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds only that filtering is optional; it says nothing about result size, ordering, or pagination that would go beyond the annotations.

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?

A single front-loaded sentence with zero waste. It is terse to the point of omitting any routing or return-behavior specifics, which caps it slightly below a 5.

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?

With an output schema present and rich annotations, the description needn't explain return values, and only one optional parameter exists. However, for an enumeration tool it omits whether the list is exhaustive, ordered, or paginated, leaving a gap an agent would want filled.

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 carries the burden, and it does clarify that producer_agent_id acts as an optional filter. Beyond that the parameter's expected ID format and behavior when omitted (returns all artifacts) are left implicit, so it adds only modest value over the bare schema.

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?

Names a specific verb (List) and resource (artifacts) and adds the filter capability, so an agent can tell this apart from get_artifact on the read-vs-enumerate axis. It doesn't explicitly differentiate from siblings like list_records or lineage, keeping it at 4 rather than 5.

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 phrase 'optionally filtered by producer agent' describes a capability, not a condition for when to use this tool versus get_artifact or list_records. No when-to-use or when-not-to-use guidance is provided.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds only that filtering is optional and what epoch 0 means; it says nothing about result ordering, completeness, or pagination behavior.

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?

A single front-loaded sentence with no filler; the optional-filter note and the epoch hint come in the right order. It is not padded, though it is arguably over-compressed for an undocumented domain concept.

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 not be described, and annotations carry the safety profile. Still, with 0% schema coverage the definition leaves the core concept 'genesis record' and the epoch domain unexplained, which is a meaningful gap for selecting this over list_artifacts.

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 compensate for the single epoch parameter. It explains one value (0 = founding cohort) and that the parameter is optional, but leaves the valid range and the meaning of other epochs undefined.

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 (list) and resource (genesis records), which is more informative than the bare tool name list_records. However, it does not distinguish this from the sibling list_artifacts or explain how genesis records relate to register_genesis, so an agent must infer the boundary.

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?

'optionally by epoch' implies the filtering condition, and '(0 = founding cohort)' hints at a use case, but there is no explicit when-to-use guidance or mention of alternatives such as list_artifacts or lineage.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, so the safety profile is covered. The description adds genuinely new behavior: recall flags rather than deletes, quarantines the whole transitive descendant subtree, and returns the exact set of quarantined agents. It stops short of stating reversibility, required authorization, or whether already-quarantined descendants are reported.

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 tight sentences, zero filler, with the cascade scope and the returned report front-loaded in that order.

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-value detail is not required, and the safety annotations cover mutation risk. What is missing is material for a destructive cascade operation: the undefined 'reason' parameter, required permissions, and whether quarantine can be lifted.

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 carries the full burden for two parameters and documents neither. 'agent_id' is only obliquely implied by 'an agent', and the 'reason' parameter is never mentioned at all, leaving its purpose and format unknown.

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 (recall/flag) and resource (an agent), plus the crucial scope detail that it cascades to every transitive descendant. 'Recall' is an unusual term, but the description defines it immediately and no sibling tool (describe_agent, lineage, verify_*) does anything similar, so it is unambiguously distinguishable.

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?

Explains the effect but not when to reach for this over alternatives, what prerequisites exist (permissions, agent state), or when recall is inappropriate. An agent has to infer the trigger condition from the destructive consequence alone.

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

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.

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

Although the description carries rich behavioral detail (monotone index, content addressing, quarantine inheritance), it asserts 'Idempotent — an agent is born once' while the annotations declare idempotentHint=false. That is a direct conflict with a structured hint, which outweighs the otherwise valuable context.

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?

Four short, densely packed sentences with the core action front-loaded and no filler. The telegraphic phrasing of 'Idempotent — an agent is born once' is efficient, though it is exactly where the contradiction with annotations arises.

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 not be explained, and the quarantine and epoch semantics are covered. But the meaning and expected format of artifact_hash are absent, and the idempotency claim conflicts with the annotation, leaving the agent with an unresolved behavioral question before calling.

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 parameter meaning. It explains parent_id's lineage role and implicitly covers agent_id, but artifact_hash (with its empty-string default) is never mentioned, leaving a third of the parameters 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?

The description states a specific verb and resource ('Register an agent's birth') and immediately says what is produced: a content-addressed genesis certificate with a monotone index. It is clearly distinct from siblings such as register_artifact, get_certificate, and lineage.

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 implies usage through constraint statements (epoch 0 = founding cohort; children of recalled/quarantined parents are quarantined at birth), but it never says when to choose this tool over siblings such as register_artifact or lineage, and it names no alternatives.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so safety is covered. The description adds real value by disclosing the mechanism — hash is recomputed and compared to the DAG ledger as source of truth — but says nothing about what a mismatch yields or any cost of recomputation (output schema covers return shape).

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?

A single front-loaded sentence with zero filler; the operation and its comparison target come before anything else. Nothing could be trimmed without losing information.

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?

The output schema means return values need not be explained, and annotations cover the safety profile. However, for a tool taking an undocumented nested artifact object, the description leaves the most failure-prone part — the expected input shape — entirely unaddressed.

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?

There is one parameter and schema description coverage is 0%; the artifact is a free-form nested object with additionalProperties=true, so the schema provides no field guidance. The description does not say what the artifact object must contain (id, hash, path, version) to be verifiable, leaving the agent to guess.

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?

Specific verb+resource: 'recompute an artifact record hash and verify it against the DAG ledger' tells the agent exactly what operation occurs. It is distinguishable from siblings like get_artifact and register_artifact by the verification action, though it never names those siblings explicitly.

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 only implied: the word 'verify' suggests checking integrity against the ledger, but there is no statement of when to prefer this over get_artifact (fetch) or verify_certificate (a different verification target), nor any prerequisites or failure conditions.

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

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

Annotations already declare the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description's job is to add context. It does so by explaining that verification recomputes a content hash and checks the ledger, which clarifies this is an integrity check rather than a simple lookup; it does not describe failure behavior, but the output schema covers return values.

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 a single front-loaded sentence with no wasted words. It states the action and mechanism immediately, which is appropriately sized for a one-parameter tool.

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?

The output schema removes the need to explain return values, and the annotations cover safety semantics. However, the missing parameter shape details and lack of sibling differentiation leave meaningful gaps for an agent deciding how to invoke this correctly.

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?

There is one required parameter ('certificate'), but schema description coverage is 0% and the schema defines it only as a generic object with additionalProperties. The description implies the certificate contains content whose hash is recomputed, but it never states the expected object shape or whether it should be the object returned by get_certificate/register_artifact.

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?

Uses a specific verb and resource ('verify a certificate') and adds mechanism detail ('recompute its content hash and check the ledger'). It does not explicitly distinguish itself from the closely named sibling verify_artifact, so it falls short of a 5.

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 no explicit guidance on when to call this versus get_certificate or verify_artifact. The use case is only implied by the verb 'verify', and there are no prerequisites or exclusions stated.

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