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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, but the description adds meaningful behavioral detail beyond that: the tool 'never mutates any state and returns no rules or enforcement data,' and it specifies the empty-input behavior ('When both inputs are omitted or empty, both match lists are empty'). It also clarifies that paths are not glob-evaluatedable, which is valuable non-obvious 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?

Three sentences deliver the core purpose, key exclusions, safety behavior, and empty-input edge case with no redundancy. The main function is front-loaded and 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?

For a read-only, two-optional-parameter tool with a rich output schema and complete parameter descriptions, the description fully covers what an agent needs: purpose, safety, exclusions, and boundary behavior. The presence of an output schema means return-value details do not need to be repeated in the description.

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 well-described in the schema (paths as opaque retrieval context, context as opaque strings with case-insensitive substring matching). The description adds the empty-input result behavior and reinforces the non-glob semantics, but it does not substantially add parameter-level meaning beyond the schema. 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: 'Return proposals and canonical decisions whose scope hints or context scope overlap the supplied context/paths.' It clearly differentiates this from typed-rule applicability by explicitly noting it is 'retrieval/context applicability only' and not ADR-020. This distinguishes it from the 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 gives clear context and exclusions: it is for retrieval/context applicability, not typed-rule applicability, and paths are never glob-evaluated. It also clarifies that no rules or enforcement data are returned. However, it does not explicitly name sibling alternatives for when to use them instead, so it lacks the full when-to-use vs alternative 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description reinforces this with 'Read only: this tool never mutates any state,' and adds behavioral context by specifying possible return record_type values, including 'not_found'. This goes beyond the annotations without contradicting them.

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 terse, front-loaded sentences cover the core action, return values, read-only behavior, and the key alternative. Every sentence earns its place and no filler exists.

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 single-parameter tool with an output schema and comprehensive annotations, the description covers everything an agent needs: what it does, what it returns, that it is safe, and when to use a sibling instead. There are no meaningful gaps.

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 single parameter record_id is fully described as 'Stable proposal id or canonical decision id to retrieve exactly.' The description adds little beyond saying 'stable id,' so it does not meaningfully improve on the schema. 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: 'Read one record by stable id.' It also explicitly lists possible record_type values, which clarifies exactly what the tool returns. This clearly distinguishes it from siblings like decision.search and decision.propose.

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 an explicit usage condition: use this tool when you already have a stable id, and use decision.search when you do not. This directly routes the agent to the correct sibling tool, leaving no ambiguity.

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 include idempotentHint=true and destructiveHint=false, but the description adds substantial non-obvious behavior: the proposal is non-authoritative, has status 'proposed', is never enforceable, and exists only in the index until separate Mneme human authority (D2C) acts. It also reiterates idempotency in a concrete way tied to source/version/content, going beyond the bare 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 front-loaded with the core action and then delivers key caveats in order. It is slightly repetitive ('non-authoritative proposal' vs. 'grants NO authority... never enforceable'), but every sentence earns its place and flows logically.

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 single-parameter tool with complete schema coverage, an output schema, and annotations covering idempotency and non-destructiveness, the description fills the main gaps: authority semantics, status effect, and the batch alternative. Nothing an agent needs to select and 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 the nested schema already documents provenance, idempotent identity via source_version, and field constraints. The tool description adds no parameter-specific detail beyond restating that a single candidate is submitted; the idempotency note is already reflected in the schema. Baseline 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 verb ('Submit') and resource ('one candidate architectural decision') and immediately distinguishes itself from the sibling by noting the proposal enters the index as a non-authoritative proposal. It names the batch alternative later, making it easy to tell apart from propose_batch even before reading 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?

The description explicitly directs the agent to 'Use decision.propose_batch when submitting multiple candidates,' which is a clear when-to-use vs. alternative condition. It also explains what this tool does NOT do (never enforceable, cannot become canonical via this MCP), preventing off-label use for authoritative decisions.

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 provide idempotentHint, readOnlyHint, destructiveHint, and openWorldHint, but the description adds meaningful behavioral context beyond those: each candidate gets its own proposal identity, enters with status 'proposed', remains independently reviewable, and batch submission grants no authority. This directly addresses the most likely misconception about batch semantics. 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 with no filler; the core action is front-loaded and the critical caveat about non-authoritative batch semantics is stated clearly. Every sentence adds necessary decision-making information, and the alternative tool is mentioned compactly.

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, combined with a complete input schema and an output schema, gives an agent everything needed to invoke the tool correctly. It explains the key behavioral contract, distinguishes from the sibling tool, and the schema covers parameters and output ordering. 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%, so the schema already fully documents candidates and shared_provenance, including provenance precedence. The tool description does not add parameter-level meaning beyond the schema, so the baseline score 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?

States a specific verb and resource: 'Submit multiple candidate architectural decisions from one producer output.' It also clarifies the key semantic, that each candidate becomes an independent non-authoritative 'proposed' proposal, and distinguishes itself from decision.propose by explicitly directing single-candidate use there. This is a clear, unambiguous purpose that separates 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?

Explicitly names the alternative decision.propose for a single candidate, giving a clear when/when-not boundary. It also explains the intended context ('from one producer output') and warns that batch submission has no acceptance authority, so an agent knows when this tool is appropriate and when to use the single-proposal sibling instead.

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 provide readOnlyHint, idempotentHint, and destructiveHint, and the description adds non-redundant behavioral detail: deterministic results, no merging of result domains, no enforcement meaning for search rank, and AND semantics for combined filters. No statement contradicts 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?

The description is compact, front-loaded with the core search behavior, and every sentence adds actionable information. There is no filler or repetition of the title/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?

For a multi-domain search tool with six optional filters, the description covers identity, scope, result separation, read-only safety, filter semantics, rank behavior, and routing to the stable-id alternative. The presence of an output schema covers return-structure details that would otherwise be 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%, but the description still adds important parameter behavior beyond the schema: 'all applicable filters combine with AND semantics' and 'proposal-only filters do not exclude canonical results, and vice versa.' This materially changes how an agent should interpret the optional filters.

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 names a specific operation (deterministic text/exact-metadata search) over two clearly defined record domains, proposals and canonical decisions, and explicitly notes they are returned in separate lists and never merged. This disambiguates the tool from siblings like decision.get and decision.propose.

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 an explicit routing rule: 'Use decision.get when you already have a stable id.' The read-only statement and filter-scoping semantics also imply when this tool is appropriate and clarify what it does not do.

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, which lowers the burden. The description adds valuable non-obvious behavior: unresolved ids 'stay type-unknown' and canonical rule-lineage failures 'fail closed as protocol errors and are never returned as partial traces.' This is behavior an agent could not predict from annotations or schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact and front-loaded: the first sentence states the core purpose, the second covers behavioral guarantees and result types, and the third gives usage routing. Every sentence earns its place with no filler or redundant fluff.

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 full output schema, rich annotations, and a single well-documented parameter, the description provides all necessary operational context: when to call, what ids are valid, what failure behavior looks like, and safety guarantees. Nothing needed 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 baseline is 3. The schema already documents that record_id is a stable proposal id or canonical decision id and that unknown ids produce trace_not_found. The description reinforces this but does not add meaningfully new parameter-level semantics beyond what the schema 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 description states a specific verb and resource: 'Return the deterministic lineage actually known for a proposal id or canonical decision id.' It explicitly distinguishes the tool from decision.get by naming it, and clarifies the scope of what is returned (lineage, not the record alone). The result_type detail further removes 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 gives direct, explicit routing guidance: 'Use decision.get for the record alone; use decision.trace when you need provenance, acceptance, rule, or declared-evidence lineage.' This tells an agent exactly when to choose this tool over a sibling, 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.