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

The description goes well beyond the annotations by disclosing that the operation overwrites status and acknowledgedAt in place, writes no journal entry, cannot be reconstructed by a rebuild, and that a repeat call restamps it. This is valuable destructive-behavior context that an agent could not infer from the annotations alone.

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 each serve a distinct purpose: main operation, id source and alternative routing, and side effects. It is front-loaded with the core function and contains no filler or redundant restatement of the tool 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?

The definition provides everything needed to invoke the tool correctly: the input id semantics, what operation is performed, how it differs from sibling tools, and the important destructive and non-reconstructible side effects. With the output schema present and the single parameter fully documented, no critical context is missing.

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 input schema already covers the id parameter fully at 100% coverage, including its provenance and the warning that it is a signal id rather than a decisionId. The description reinforces that provenance but does not add meaning that the schema does not already provide, so it stays at the baseline for high schema coverage.

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 action, 'Acknowledge one persisted review signal by id, closing it as open work,' and clearly identifies the resource and scope. It also names sibling tools that handle different operations on decisions, so the agent can distinguish it from shadowgraph_update_status and shadowgraph_supersede.

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?

It explicitly says when to use this tool: to acknowledge a persisted review signal by id and close it as open work. It also gives the alternative routing, 'use shadowgraph_update_status or shadowgraph_supersede to act on the decision,' which clearly communicates the boundary between acknowledging the signal and acting on the decision.

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 mark this as destructive and non-read-only; the description adds concrete behavioral details: overwrites existing files without warning, creates parent directories, and commits a revision. These are meaningful side effects beyond what annotations alone convey. It could mention permissions or failure cases, but the added context is strong.

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 compact sentences front-load the action, then add usage context, an alternative, and side effects. Every sentence earns its place with no filler or redundant restatement of the tool name. The structure is efficient and scannable.

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?

Given the low complexity—one required parameter, full schema coverage, destructive annotations, and an output schema—the description covers everything needed for correct invocation. It adds usage triggers, sibling differentiation, and key side effects. An agent can act on this definition confidently without further research.

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 input schema fully documents the single destination parameter at 100% coverage, including overwrite behavior, parent directory creation, and extension guidance. The description restates some of this but does not add new parameter-level meaning beyond the schema. Baseline 3 is appropriate given complete schema coverage.

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: 'Write a consistent snapshot of the whole store to a filesystem path on the server.' It clearly differentiates from shadowgraph_redact by noting that the alternative shares data without writing a file. The purpose is unambiguous and distinct from siblings.

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 when to use this tool: 'Take one before shadowgraph_purge or shadowgraph_restore.' It also identifies a relevant alternative, shadowgraph_redact, and explains the key difference. This gives direct routing guidance with no inference required.

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 discloses side effects beyond the annotations: reusing a key 'cannot double-count, but restamps the decision and commits a revision.' This clarifies non-idempotent behavior and the write/commit nature of the call, complementing the readOnly=false and idempotentHint=false 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?

Three dense sentences with no filler. The core purpose is front-loaded, alternatives are named, and the critical key-reuse caveat is stated clearly.

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 tool with 9 parameters, 100% schema coverage, and an output schema, the description provides the missing operational context: when to choose alternatives and what key reuse actually does. Nothing essential for selecting or invoking the tool is omitted.

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 is 3, but the description adds meaningful key semantics: reusing a key cannot double-count yet still restamps and commits a revision. This complements the schema's dedupe explanation, though it does not deeply elaborate other parameters.

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 opens with a specific verb and object: 'Apply one keyed piece of supporting or contradicting evidence to a decision's confidence.' It also names related siblings and clarifies this tool is for applying evidence, not for recording outcomes or facts.

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?

It gives explicit routing guidance: use shadowgraph_record_outcome once the decision has played out, and shadowgraph_record_fact for an observation that can reopen it. It also explains the key-reuse caveat, telling agents when a new key is required.

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?

With all annotations false, the description carries the burden of disclosure and largely meets it: 'Not a read: it evaluates reopen rules, can persist signals, and commits a revision' clearly communicates mutation and side effects. It could go further by specifying what a committed revision entails, but it is honest and materially informative.

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 sentences, each earning its place: purpose, sibling differentiation, and the critical non-read caveat. The structure front-loads the primary intent before alternatives and caveats.

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 description covers purpose, usage boundary, side effects, and sibling routing, and an output schema exists to handle return values. Minor gaps remain around what exactly a 'revision' is and how reopen rules behave, but these do not block correct invocation.

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 100% and every parameter already has a detailed description. The narrative description adds no parameter-specific semantic value, so the baseline 3 is appropriate.

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 opens with a specific verb and resource: 'Build one project's working set' and lists what that set contains. It then explicitly differentiates itself from shadowgraph_search, shadowgraph_retrieve, shadowgraph_recall, and shadowgraph_review, making sibling confusion unlikely.

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?

It states when to use this tool ('before a consequential task') and names concrete alternatives for single lookups, scoped memory reads, and evaluations. It also adds the crucial exclusion 'Not a read,' preventing misuse for read-only needs.

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, and non-destructive behavior; the description adds that entries are immutable audit evidence, append-only/never rewritten in place, and are complete post-operation snapshots in sequence. This gives the agent meaningful invariants beyond the safety flags.

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 sentences, each with a distinct job: define the resource, route to alternatives, and state immutability/read-only guarantee. Minor redundancy in 'Reads only' given the readOnly annotation, but no waste.

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?

Given a full input schema, an output schema, and annotations, the description covers what the journal is, how it is ordered, its read-only/immutable nature, and how it relates to the main sibling tools. An agent has everything needed to select and call 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?

All three parameters are fully documented in the schema, including defaults, bounds, and ordering guarantees, so the description does not need to add parameter-level detail and does not do so. Baseline 3 is appropriate.

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 opens with a specific verb ('Read') and resource ('append-oriented journal of complete post-operation snapshots'), and states the sequence ordering. It also distinguishes the tool from three siblings by assigning them distinct jobs (rebuild, validate, search).

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?

It names shadowgraph_rebuild, shadowgraph_validate, and shadowgraph_search with their distinct purposes, which lets an agent infer when journal is the raw-source read rather than those specialized operations. However, the guidance is implicit—it never says 'use X instead' or lists when not to use journal, so it falls just short of fully explicit routing.

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 mark the tool as non-read-only and non-idempotent, but the description adds crucial behavioral detail: every call mints a new relation id, repeats duplicate relationships, and there is no unlink mechanism. This goes well beyond the raw annotation flags.

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 dense sentences, each earning its place: purpose, alternatives, duplication behavior, and absence of an unlink tool. The most critical behavioral caveat is front-loaded and no words are wasted.

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 description covers existence requirements, duplication semantics, irreversibility, and how to read or supersede relationships. With an output schema present and annotations matching the behavior described, an agent has everything needed to invoke this tool 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 coverage is 100%, and each parameter is already well described in the schema. The description reinforces that both entities must exist and that the relation name is caller-chosen, but it does not add substantial parameter-level meaning beyond the 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?

The description states a specific verb and resource: 'Create one named, directed relationship between two entities that already exist.' This clearly distinguishes linking from reading, superseding, and deletion, and names related sibling tools without ambiguity.

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 explicitly routes the agent to shadowgraph_traverse for reading relationships and to shadowgraph_supersede for replacements, and explicitly warns that 'There is no unlink tool.' This gives clear when-to-use and when-not-to-use guidance relative to 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 indicate this is not read-only and not idempotent, but the description adds crucial nuance: it commits a revision even when a repeat at the same instant finds nothing to do, and it depends on the clock. This goes beyond the structured metadata and helps an agent predict side effects.

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 sentences carry all essential information with no repetition or filler. The core behavior is front-loaded, and the sibling comparisons are compact but informative.

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 a complete input schema and an output schema present, the description needs only to explain behavior and tool selection, which it does thoroughly. The note about non-idempotence and clock dependence closes the most likely agent confusion.

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 input schema has 100% coverage and already explains all three parameters in detail, including defaults and ephemeral semantics. The description does not add parameter-specific meaning beyond the schema, so the baseline of 3 applies.

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 action ('Run time-based maintenance') and breaks it into concrete steps: make decisions stale, expire due facts, evaluate reopen rules. It also names sibling tools and differentiates this one by what it does that they cannot. This leaves no ambiguity about the tool's role.

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 explicitly contrasts this tool with shadowgraph_review, shadowgraph_validate, and shadowgraph_update_status, stating what each alternative fails to do. It also clarifies that the tool writes and is clock-dependent, so an agent knows when to call it and what to expect.

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 mark this as destructive, but the description adds important context: the operation is irreversible without a backup, and modes behave differently (logical keeps a journal skeleton, hard drops entries leaving a declared gap). This goes beyond the annotation and fully informs the agent about consequences.

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 three sentences with no filler. It front-loads the core action and resource, then gives the required preview step, alternatives, irreversibility warning, and mode behavior in an efficient, scannable structure.

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 destructive tool with two parameters, an output schema, and full schema coverage, the description covers everything an agent needs: what is deleted, the prerequisite preview, relevant alternatives, irreversibility, and mode semantics. No critical information is missing.

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 schema already explains both parameters. The description adds a concise restatement of logical versus hard behavior, but this largely duplicates what the schema's mode enum and project descriptions already provide. Baseline 3 is appropriate.

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: 'Delete one project's decisions, attempts, memories, facts, relationships, events, and retry keys.' It also names sibling tools, distinguishing it from shadowgraph_redact and shadowgraph_backup, so an agent can select this tool confidently.

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 explicit usage guidance: run shadowgraph_purge_preview first, and notes that shadowgraph_redact is for sharing without deleting while shadowgraph_backup preserves a copy. It also warns about irreversibility without a backup, making the preconditions and alternatives clear.

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=true, idempotentHint=true, and destructiveHint=false. The description adds concrete behavioral context beyond this: 'no storage, journal, or signal change, and no file is written.' This reinforces the read-only nature with specific guarantees.

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, purposeful sentences. The primary purpose is stated first, followed by usage guidance and explicit read-only guarantees. Every sentence earns its place with no filler or repetition of schema details.

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 simple: one parameter, clear annotations, and an output schema present. The description covers purpose, usage timing, sibling relationship, and side-effect guarantees. Nothing an agent needs to invoke it correctly is missing.

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 input schema has 100% description coverage for its single 'project' parameter, so the schema already documents the requirement clearly. The description adds minimal semantic value beyond restating that it uses the 'same project name' as shadowgraph_purge, which is useful but not substantial.

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 uses a specific verb ('Count') and a clear resource ('what a purge of one project would remove'). It explicitly names the sibling it precedes (shadowgraph_purge), making the tool's purpose distinct and immediately identifiable.

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 explicitly says 'Run this before shadowgraph_purge,' providing a direct usage directive with the relevant alternative named. It also clarifies the relationship: preview first, then purge with the same project name.

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, and destructiveHint, but the description adds concrete context: 'the journal is untouched and the live graph is not replaced by the result.' This is especially useful because 'rebuild' could otherwise imply destructive replacement. No contradiction with annotations exists.

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 sentences, each earning its place: the main action, sibling differentiation, and read-only clarification are all included without redundancy. The most important information is front-loaded.

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 has an output schema, a single optional parameter that is fully documented, and annotations covering safety and idempotency. The description adds the necessary scoping and no-side-effect guarantees, so an agent has everything needed to call this tool 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 sole parameter, requireFullHistory, is fully documented in the schema with a clear explanation of true/false behavior and its return effect. The description itself adds no parameter-specific information, but with 100% schema coverage, the baseline of 3 is appropriate.

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 opens with a specific verb and resource: 'Replay this store's own journal into a projection and report whether the fold was complete.' It further distinguishes itself from shadowgraph_journal and shadowgraph_validate, so an agent can tell exactly which operation this tool performs.

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 names two sibling tools and contrasts them with this one: shadowgraph_journal reads entries, shadowgraph_validate diagnoses the live graph, while shadowgraph_rebuild replays the journal into a projection. This gives clear guidance on when to choose this tool versus 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 establish readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so 'Reads only' is redundant but harmless. The unique addition is 'Every response declares which signals were available, so absent ones are never renamed', a valuable behavioral guarantee about response transparency beyond the annotations. No contradiction with 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?

Three sentences with no filler; the core function is front-loaded, followed by sibling differentiation and a behavioral guarantee. Every sentence earns its place.

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 description covers operation, scope, safety, signal-availability behavior, and sibling routing, which is complete for a read-only tool with a rich input and output schema. The schema handles parameter details and return values, so nothing essential is missing.

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 100%, with detailed documentation for all 10 parameters, so the baseline is 3. The description adds high-level context about signal fusion but does not detail specific parameters beyond what the schema already provides.

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 leading verb 'Recall' plus the explicit fusion mechanism ('lexical, vector, graph-distance, and temporal ranks') identifies the operation precisely. It then contrasts with shadowgraph_search and shadowgraph_retrieve, making the function unmistakable and differentiating it from siblings.

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 explicitly names sibling tools and their distinguishing behaviors ('shadowgraph_search is plain content matching, shadowgraph_retrieve adds graph neighbours, shadowgraph_remember writes memory'), giving an agent clear routing criteria. The implication that recall is for when fused ranking is needed is sufficient guidance.

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?

Discloses side effects beyond the annotations: it appends both an attempt and a journal entry, and warns that without idempotencyKey a retry records a second entity. This complements idempotentHint=false by explaining the concrete consequence.

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 front-load the core purpose, then provide sibling routing and a behavioral caveat. Every clause earns its place with no repetition of schema content.

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 10-parameter write tool with full schema coverage and an output schema, the description supplies essential context: purpose, sibling differentiation, side effects, and idempotency behavior. Nothing necessary for correct invocation is missing.

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 100%, so the schema already documents all 10 parameters. The description does not add parameter details beyond what the schema provides, but it does not need to; the baseline of 3 is appropriate since the schema carries the burden.

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 ('Record one attempt and how it turned out') and explicitly distinguishes itself from shadowgraph_record_decision and shadowgraph_record_outcome. An agent can tell this tool apart from closely related siblings without opening their schemas.

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?

Names the exact sibling tools for adjacent cases ('Use shadowgraph_record_decision for the choice itself, shadowgraph_record_outcome for how one played out') and frames when this tool applies ('so the same approach is not blindly retried'). The guidance is explicit and actionable.

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 discloses the write behavior beyond the annotations: it 'appends a decision and a journal entry', says each call 'commits a revision', and flags the non-idempotent nature without idempotencyKey. This complements the sparse boolean annotations with actionable side-effect 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?

Two dense sentences earn their place: the first states the core action and content, the second routes to alternatives and reveals the side-effect/idempotency behavior. No filler and the most decision-relevant information is front-loaded.

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 13-parameter write tool, the combination of a fully documented schema, an explicit side-effect statement, and clear sibling routing leaves nothing essential missing. An output schema exists, so the description does not need to explain return values.

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 input schema already describes all 13 parameters with 100% coverage, so the baseline of 3 applies. The description lightly signals the important parameters (chosen option, assumptions, evidence, rejected alternatives, reopenWhen rules) but adds no meaning beyond the schema's own field descriptions.

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 ('Record') and exact resource ('one decision') and enumerates the content it captures: chosen option, assumptions, evidence, and rejected alternatives with reopenWhen rules. It also distinguishes itself from sibling tools by naming shadowgraph_record_attempt, shadowgraph_record_fact, and shadowgraph_remember and what each is for.

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?

It explicitly tells an agent when to pick this tool over closely related options ('Use shadowgraph_record_attempt for something tried, shadowgraph_record_fact for an observation, shadowgraph_remember for a note'). This is direct routing guidance rather than leaving the choice to inference.

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?

Beyond the annotations, the description discloses that a call supersedes the previous active fact while retaining history, that verification cannot be self-asserted, and that each call commits a revision. These are meaningful behavioral traits needed for safe invocation and are not redundant with readOnlyHint/idempotentHint/destructiveHint.

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 sentences, each earning its place: the core operation is front-loaded, followed by usage routing and key behavioral caveats. There is no filler or duplicated schema content.

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?

Given the rich 100%-covered input schema and existing output schema, the description covers what an agent needs for selection and invocation: what a fact is, when to use it, how it replaces prior facts, and the verification limitation. Remaining details live in the schema where they belong.

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 schema already documents all 12 parameters. The description adds high-level framing ('claimed provenance class', 'optional validity window') but no detail beyond what the schema's sourceClass and expiresAt descriptions already provide, so the baseline applies.

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?

Description states a specific action ('Record one observed fact') with resource scope ('as a project and key') and distinguishes itself from shadowgraph_remember by defining the fact-key use case that triggers reopenWhen rules. This lets an agent select it correctly among the many record_* siblings.

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?

It explicitly says when to use the tool ('Use for the fact keys reopenWhen rules name') and points to the alternative for non-observations ('shadowgraph_remember stores durable memory that is not an observation'). This is direct when/when-not guidance rather than leaving selection to inference.

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 discloses important non-obvious behavior: one outcome contribution per decision, re-recording replaces rather than stacks, restamps the observation time, and commits a revision. This goes well beyond the bare annotations and gives the agent a realistic model of side effects.

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 sentences, each earning its place: purpose, sibling differentiation, and replacement semantics. The most important and distinguishing information is front-loaded, with no redundant filler.

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-parameter tool with a fully documented schema and an output schema, the description covers the essential behavioral context: what the tool does, how it differs from related tools, and the non-idempotent replacement behavior. Nothing critical is missing for safe invocation.

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 input schema has 100% coverage with detailed descriptions for both decisionId and outcome, including how each status affects confidence and how sourceClass weights movement. The description adds only the general notion of evidence-weighted movement, which is a reasonable baseline since the schema carries the parameter detail.

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 action ('Record how a decision turned out') and the resulting effect ('move its confidence by an evidence-weighted amount'). It also explicitly differentiates itself from shadowgraph_confidence_evidence and shadowgraph_update_status, which helps an agent distinguish this tool from close siblings.

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 clear boundaries: shadowgraph_confidence_evidence is for evidence short of an outcome, shadowgraph_update_status is for lifecycle state changes, and this tool is for recording an outcome. It also notes that re-recording replaces prior recording, providing practical guidance for repeated use.

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?

Beyond the annotations already declaring readOnlyHint=true and idempotentHint=true, the description adds concrete behavioral guarantees: no file is written, and journal payloads are also redacted so secrets cannot survive in the audit trail. This is meaningful context that annotations alone do not provide.

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 compact, front-loaded with the core purpose, and every sentence adds value: purpose, sibling contrast, and behavioral guarantees. There is no filler or repetition of schema-only details.

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 2-parameter, no-required-parameter tool with an output schema, the description is complete: it states the operation, differentiates from destructive and backup siblings, and discloses the critical journal-redaction behavior. Nothing necessary for correct invocation is missing.

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 100%, so the schema already documents both parameters and the default pattern set. The description adds the general notion of 'secret-looking keys and values' but does not significantly extend the parameter semantics already present in the input 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?

The description uses a specific verb ('Return') and resource ('redacted copy of the store export'), and immediately differentiates itself from shadowgraph_backup and shadowgraph_purge. An agent can tell exactly what the tool does without opening the 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?

The description clearly positions the tool as a safe, non-writing alternative to shadowgraph_backup and shadowgraph_purge, and states that it reads only and writes no file. It does not explicitly enumerate all when-not-to-use scenarios, but the contrast with the two most relevant siblings provides clear routing guidance.

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?

Beyond the annotations (readOnly=false, destructive=false, idempotent=false), the description adds meaningful behavior: identical content is a NOOP, new content supersedes while keeping history, DELETE invalidates, and every call commits a revision. This clarifies the mutation model and confirms why the operation is neither idempotent nor genuinely destructive.

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 dense sentences carry distinct value: what the tool does, which siblings to use instead, and core behavioral semantics. The most important action is front-loaded, and no sentence is filler.

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 complex 15-parameter tool with a rich output schema and fully commented input schema, the description covers the essential selection and invocation information: single-memory vs batch plan, identity-tuple reconciliation, history preservation, and sibling routing. Remaining operational details live appropriately in the schema definitions.

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 input schema is exhaustively self-documenting with 100% description coverage, so the description does not need to repeat parameter details. It adds useful framing like 'by identity tuple' and the reconcile/supersede/NOOP behavior, but does not independently clarify individual parameters beyond the 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?

The description opens with a specific verb and resource: 'Add or reconcile one scoped memory, or apply an ADD/UPDATE/DELETE/NOOP plan.' It clearly distinguishes itself from sibling tools by directing decision memories to shadowgraph_record_decision, factual observations to shadowgraph_record_fact, and reads to shadowgraph_recall.

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 explicitly states when to use sibling alternatives ('Use shadowgraph_record_decision for a choice, shadowgraph_record_fact for an observation, shadowgraph_recall to read memory back'), giving an agent clear routing signals. It also clarifies the batch-plan mode versus single-memory mode as two valid ways to invoke this tool.

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 indicate readOnly, idempotent, and non-destructive, and the description adds useful behavior beyond that: the result always carries apply:false, and ambiguous cases are routed to manual_review. This clarifies what the tool actually returns and what it cannot do.

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, with the core purpose front-loaded and every sentence adding necessary operational detail. No filler or repetition beyond what serves the agent's decision-making.

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 description fully covers the operational context: when to call it, what it returns, that it never applies changes, and how ambiguity is handled. Since an output schema exists, return-value details do not need to be restated.

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 has zero parameters, so there is nothing for the description to clarify. Schema coverage is trivially complete, and the baseline for zero-parameter tools is 4.

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 uses a specific verb ('Return') and a specific resource ('the non-destructive repair plan implied by the current diagnostics'). It clearly distinguishes this from siblings like shadowgraph_validate and shadowgraph_redact by emphasizing that it only returns a plan and never applies changes.

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?

It explicitly states when to use the tool ('Use after shadowgraph_validate') and explains that the caller must execute the plan with ordinary tools because no apply tool exists. It does not spell out explicit when-not-to-use conditions, but the guidance is unambiguous enough for correct selection.

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 flag destructive behavior, but the description adds meaningful detail: every record and journal entry is replaced, a strictly greater revision is installed, and a failure is rolled back. This goes well beyond what the annotations alone communicate.

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 dense sentences carry the core action, the sibling differentiation, the destructive consequences, and the rollback guarantee. There is no filler or repetition; every sentence contributes essential 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?

For a destructive, single-parameter restore operation, the description covers what it does, when to use it, what it destroys, how it relates to backup/purge, and failure behavior. The output schema exists and annotations cover the remaining concerns, so nothing needed for safe invocation is missing.

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?

Although the schema already documents the source path thoroughly, the description adds the accepted backup formats ('JSON or SQLite') and the rest of the schema reinforces required backend compatibility. With only one required parameter and full schema coverage, the parameter meaning is exceptionally clear.

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 opens with a specific verb and resource: 'Replace the entire live store with the contents of a JSON or SQLite backup.' It also distinguishes itself from close siblings by noting that shadowgraph_purge removes one project and shadowgraph_backup creates the snapshot this tool reads.

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?

It explicitly states this is 'Recovery only, never a merge,' which tells an agent when to choose it and when not to. It also names the relevant alternatives and what they do, making the tool's role in the workflow clear.

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=true, idempotentHint=true, and destructiveHint=false, so the safety profile is known without description. The description adds genuinely useful behavior beyond that: results include one-hop neighbours and 'a neighbour can appear with no content match of its own', which is non-obvious and affects how an agent interprets results. It does not contradict any 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?

Four short sentences, all informative, with the core operation front-loaded before the sibling comparison. The 'Reads only' sentence and the neighbour-without-match note each add a distinct fact; there is no filler or repetition of schema content.

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 read-only, idempotent, 7-parameter tool with an output schema, the description is complete: it defines the core behavior, distinguishes it from four relevant alternatives, and flags the non-obvious neighbour behavior. Return-value format is covered by the existing output schema, so nothing an agent needs to select or invoke it correctly is missing.

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 100% and every parameter (kind, limit, query, offset, status, project, minConfidence) has its own detailed schema description. The tool description therefore does not need to compensate for undocumented parameters, and the baseline of 3 applies. It does add a small cross-reference by saying the query matches 'exactly as in shadowgraph_search', but the schema already carries the semantics.

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 opens with a specific verb-resource pair: 'Retrieve records matching a content query together with their one-hop graph neighbours', which precisely identifies the tool's function and its unique feature. It also names four sibling tools and states what they do instead, making the differentiation immediate and unambiguous.

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 names the sibling alternatives (shadowgraph_search, shadowgraph_recall, shadowgraph_traverse, shadowgraph_context) and contrasts what each returns or does, so an agent knows when to pick this tool over each one. The phrase 'shadowgraph_search returns matches only' provides a concrete when-not signal, and 'shadowgraph_traverse walks from a known id' covers the main other entry point.

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 begins with 'List,' it transparently discloses the write behavior: 'Persists one signal per newly due decision, deduped by decision and reason; a repeat commits a revision.' It also adds a return-format note, which is useful since no output schema exists. These details go well beyond the sparse 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?

The description is dense but well-organized: core purpose first, then sibling differentiation, then side-effect and return behavior. Every sentence adds distinct value without fluff or repetition of the schema.

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?

Despite the absence of an output schema, the description covers the essential behavioral context: what the tool lists, when signals persist, how deduplication works, what a repeat does, what it returns, and how it relates to sibling tools. An agent has enough to decide whether to invoke it and what to expect.

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 input schema already describes all three parameters with 100% coverage, so the baseline is 3. The description does not add parameter-specific semantics, but the schema's descriptions are sufficient, including the ephemeral nature of changedFacts and the override behavior of facts.

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 opens with a specific verb and resource: 'List decisions whose rejected alternatives are due again, from reopenWhen rules over stored facts.' It clearly identifies the tool's core function and distinguishes it from shadowgraph_review_signals by noting that sibling reads persisted signals while this one lists newly due decisions.

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 names relevant siblings and their roles ('shadowgraph_review_signals reads persisted ones, shadowgraph_ack_review closes one, shadowgraph_maintain ages first'), giving an agent a clear map of alternatives. However, it stops short of an explicit 'use this when / use that instead' conditional, leaving some inference to the 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?

Annotations already carry readOnlyHint, idempotentHint, and destructiveHint, and the description adds meaningful behavior beyond those: acknowledged signals are 'retained rather than deleted', and the tool returns a 'bare JSON array, not paginated'. These details affect how the agent interprets results and avoids assuming pagination or destructive cleanup.

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 front-loads the core action and filters, then uses parenthetical-style sibling differentiation and behavioral notes. Every sentence adds distinct value: listing, alternative routing, safety, retention semantics, and return shape. There is no redundant filler.

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 simple two-optional-parameter read tool with no output schema, the description covers everything an agent needs: what it lists, how to filter, how it differs from related tools, safety, retention behavior, and the exact return shape. The lack of an output schema is compensated by the explicit 'bare JSON array, not paginated' statement.

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 100%, with each parameter already documented in the input schema. The description's mention of narrowing 'to a project or to open or acknowledged ones' paraphrases the schema rather than adding new semantic meaning, so the baseline score of 3 applies.

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 opens with the specific verb 'List' and the resource 'review signals', then immediately clarifies the optional filters (project, open/acknowledged). It distinguishes itself from the closely named shadowgraph_review and shadowgraph_ack_review by describing what those tools do differently, so an agent can confidently identify which tool fits.

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 explicitly contrasts this tool with shadowgraph_review ('re-evaluates reopen rules and can create signals') and shadowgraph_ack_review ('closes one'), making the alternative selection criteria clear. It also states 'Reads only', which tells the agent this is the safe inspection tool among the review-related siblings.

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, openWorldHint, idempotentHint, and destructiveHint. The description adds non-obvious behavioral context: 'Schema keys never match, and a filter is never a content match' — an important guardrail for interpreting parameters. It could go further by noting pagination behavior, but the schema covers that.

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 sentences, each carrying information. The purpose is front-loaded, sibling distinctions are compact, and the read-only and filter semantics are stated in one concise clause. No filler or repetition beyond a harmless 'Reads only' echo of the annotation.

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?

Given a full input schema, output schema, and read-only/idempotent annotations, the description provides the missing high-level context: what counts as a match, how filters behave, and how this tool differs from the nearest alternatives. It is sufficient for an agent to select and invoke the tool 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 100%, so the baseline is 3. The description adds cross-cutting meaning beyond individual parameter descriptions, especially the rule that structured filters are never content matches and that all query terms must appear in declared content fields. This helps an agent avoid misusing kind, status, sourceClass, and minConfidence.

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 opens with a specific verb and resource: 'Find decisions, attempts, and facts whose declared content fields contain every query term.' It also distinguishes itself from siblings by naming shadowgraph_retrieve, shadowgraph_recall, shadowgraph_context, and shadowgraph_traverse with their respective behaviors.

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 explicitly contrasts this tool with four sibling tools: retrieve adds one-hop neighbours, recall fuses ranks over scoped memory, context builds a working set, and traverse walks from an id. It also states 'Reads only,' helping an agent choose it over mutating 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 cover read-only, open-world, idempotent, and destructive hints. The description adds meaningful context beyond those flags: nothing is deleted, repeats return the same result but still commit a revision, and superseded decisions are excluded from current context. This is especially useful because idempotentHint is false yet the call appears repeatable.

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 sentences, each carrying distinct information: the operation, sibling differentiation, persistence behavior, and repeat semantics. The main purpose is front-loaded, and there is no redundant wording.

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-parameter operation with a fully described schema and an output schema, the description covers all essential behavioral aspects: what it does, constraints, side effects, and repeat behavior. No missing information would prevent correct invocation.

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 parameter descriptions are already detailed, stating which decision is replaced and which one replaces it, including validity constraints. The description adds little beyond the schema because the schema already conveys the semantic relationship and project-scope requirement.

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 ('Mark') and resource ('decision superseded by a replacement') with a project-scope constraint. It names sibling tools that handle other cases, so an agent can distinguish this operation without opening other definitions.

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 routes ordinary lifecycle moves to shadowgraph_update_status and other relationships to shadowgraph_link, clarifying when to choose this tool. It also notes the same-project requirement and the non-deletion behavior, giving the agent clear selection criteria.

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, and destructiveHint, and the description adds a meaningful behavioral boundary: memory outside the requested project and scope stays hidden. This goes beyond the annotations and clarifies the privacy/visibility model.

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 tightly written sentences with no filler. The purpose is front-loaded, followed by sibling routing, then the read-only and scope-boundary behavior. Every sentence earns its place.

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 a rich output schema and strong annotations, the description covers what is needed for selection and invocation: prerequisites, alternative tools, and the scope-privacy boundary. Minor gaps like result shape are already addressed by the output schema.

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 100%, and each parameter already has detailed semantic documentation. The description only adds context for the starting id; depth, scope, relation, and direction semantics are fully handled by the schema, so baseline 3 is appropriate.

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?

Description states a specific action and resource: walking relationships outward from one entity id and returning what is reached. It also distinguishes itself from siblings by directing the agent to shadowgraph_search or shadowgraph_recall for finding ids and noting shadowgraph_retrieve's content-plus-neighbors behavior.

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?

Provides clear routing guidance: find ids first with shadowgraph_search or shadowgraph_recall, and use shadowgraph_retrieve when content search plus neighbors is needed. It does not exhaustively state when not to use the tool, but the context is strong enough for correct selection.

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 adds meaningful non-obvious behavior beyond the annotations: stale and superseded are system-owned and rejected, and setting the current state 'writes nothing but still commits a revision.' This clarifies side effects and edge-case behavior. It does not contradict the annotations, and the annotations already signal a mutating operation.

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 cover the core action, sibling differentiation, and two important behavioral caveats. The main purpose is front-loaded, and every sentence adds value without redundancy.

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-parameter tool with a fully documented schema and an output schema present, the description covers the operation, alternatives, restrictions, and the subtle current-state behavior. Nothing essential for correct invocation is missing.

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 100%, and the status parameter's legal-move matrix is fully documented in the schema. The description adds general operational context but does not need to restate parameter details. Baseline 3 is appropriate because the schema carries the parameter-semantics burden.

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 opens with a specific verb and resource: 'Move one decision to another lifecycle state.' It also differentiates this tool from close siblings by noting what shadowgraph_supersede, shadowgraph_maintain, and shadowgraph_record_outcome do, making the tool's purpose unmistakable.

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 useful context for choosing among related tools by contrasting update_status with supersede, maintain, and record_outcome. It also states constraints such as stale and superseded being system-owned. It does not explicitly spell out a 'use X when...' rule, but the alternatives are clearly named and their roles distinguished.

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, and destructiveHint, so the read-only nature is covered. The description adds valuable behavior beyond annotations: it reports by severity, never modifies storage, names legacy data instead of guess-repairing, and reports newer-schema data without downgrading it. No contradiction with 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?

Three sentences with no filler; the primary purpose and read-only behavior are front-loaded, then sibling distinctions and legacy-data handling are stated economically. Every sentence earns its place.

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 no parameters, an output schema available, and strong annotations, the description covers all necessary guidance: what it reports, that it is read-only, how it relates to sibling tools, and how it handles legacy and newer-schema data. Nothing important is missing.

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 has zero parameters and the schema is an empty object, so there are no parameter semantics for the description to clarify. Baseline 4 applies because parameter explanation is not needed.

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: 'Report graph integrity diagnostics by severity.' It also differentiates itself from shadowgraph_repair_plan and shadowgraph_rebuild by describing what those tools do versus this one, so an agent can distinguish them.

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 clearly identifies the tool's diagnostic role and contrasts it with shadowgraph_repair_plan (what a fix would involve) and shadowgraph_rebuild (tests journal reproduction). It does not explicitly state 'use when' or list exclusions beyond those two, but the context is clear enough for selection.

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