Council of AI GSPC (free)

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

Annotations already cover safety (readOnly, idempotent, non-destructive, openWorld), so the bar is lower, and the description adds genuinely new behavioral context: slots and measurements are never summed or swapped, and an unfetchable board yields a distinct UNREACHABLE state with no cached number ever shown as live. That failure-mode disclosure is the kind of detail annotations cannot express.

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 first sentence front-loads purpose and source well, but the body is a long chain of em-dash-appended clauses that mixes return-value definition, parameter selection, and a mission statement ('We measure, never certify'), which borders on redundant given the output schema exists. It is readable but heavier than the single-parameter, output-schema-backed tool needs.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, return values need not be spelled out, yet the description covers the semantic pitfalls (slot vs. measurement, never summed) and the error state, which are the pieces structured fields cannot carry. Only the routing among sibling evidence tools is left unexplained.

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 enum parameter is fully documented in the schema, so baseline 3 applies. The description's detail="full" clause largely restates the schema ('count_grammar, per-family counts, measured_on block') rather than adding format or cost 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 states a specific resource (live GSPC board totals) with a concrete verb-equivalent (fetch/return) and enumerates exactly what comes back: slot count, measured count, separation line, and as_of dates. It does not, however, differentiate itself from the many sibling evidence/trust tools (measurement_index, get_axis, get_card), leaving the agent to infer the distinction.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is only implied: the tool is the way to read board totals, and the description tells the agent to pass detail="full" for the long-form grammar and per-family counts, which is a useful selection cue. But there is no explicit when-to-use vs. siblings or when-not to use it, so guidance stays at the implied level.

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 read-only and idempotent, and the description adds rich behavioral context: unmeasured axes are valid first-class responses, not errors or zeros; unknown names return a list of board names; and responses come from a live board URL. There is no contradiction with 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 front-loaded with the core operation and packs useful detail into three sentences. It is slightly dense in the middle, where the row fields follow the axis-id clause, but every part 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 one-parameter read-only tool with an output schema and strong annotations, the description covers lookup behavior, edge cases such as unmeasured axes and unknown names, and the data source. Nothing an agent needs to correctly invoke it 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% coverage for the sole parameter, including case-insensitivity and the unknown-name fallback. The description reinforces exact board spelling and the fields returned, but it does not materially change the parameter's meaning 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 description opens with a concrete action and resource: returns one axis row from the live GSPC board. It lists the row's fields and clarifies that it is a single-axis lookup, not a board-level or card-level operation. The 'Never a certification' line further sharpens the tool's purpose.

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 establishes that this is a single-axis lookup by exact board id, but it does not name sibling alternatives or explicitly state when to choose this over board_totals, list_cards, or get_card. The 'Never a certification' line gives one negative boundary, so usage guidance is implied rather than explicit.

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=false. The description adds valuable behavioral context: the three states (VALID, INVALID, UNCHECKABLE), the visible UNMEASURED cells, and the source URL. 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?

The description is compact, front-loaded with the action and resource, and every sentence contributes: the URL, the states, and the exclusion of GSPC measurement cards. No filler or 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?

An output schema exists, so return values need not be described. The description covers the states, the URL, and the card type, and the annotations handle safety. It is sufficiently complete for a single-card fetch, though it could briefly mention alternatives (addressed in usage guidelines).

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 documents the parameter (64-char hex SHA-256) with 100% coverage, so the description repeats that. It adds the URL pattern and confirms the purpose, but no new semantic meaning beyond the schema. Baseline 3 is appropriate given 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 verb (GET), a precise resource (card-v0 leaf), and the exact identifier (sha256 hex). It also distinguishes itself from a sibling class ('Not a GSPC measurement-card'), making its purpose 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 implies usage for fetching a specific public-root card by hash and clarifies it is not a GSPC measurement-card, but it does not explicitly contrast with other siblings like verify_card or get_root. There is no 'use this when' or 'instead of' guidance, leaving some ambiguity for an agent choosing among related tools.

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 readOnlyHint and idempotentHint annotations, the description discloses operational states (VALID, UNREACHABLE, UNCHECKABLE), clarifies that it never returns a certificate, and notes the permissionless nature. This adds meaningful behavioral context about failure modes and output 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?

The description is three sentences with no filler. The main action and URL are front-loaded, followed by return fields and states. Every sentence earns its place and the text is highly efficient.

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 zero-parameter GET tool with an output schema (as indicated), the description covers the endpoint, return fields, and state behavior. The term 'UNMEASURED notes' is cryptic and could be clarified, and usage guidance is minimal, but overall the tool is simple enough that this is sufficient.

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 the description need not elaborate on parameter semantics. The baseline for no-parameter tools is 4, and the description correctly omits any irrelevant 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 clearly states the tool fetches the permissionless public Merkle root from a specific URL, lists the exact return fields (merkle_root, card_count, as_of, UNMEASURED notes), and distinguishes it from GSPC and from being a certificate. The verb 'GET' plus resource and expected output make the purpose 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 notes 'Separate from GSPC' which hints at a distinction, but it does not explicitly state when to use this tool over its siblings (e.g., get_axis, verify_inclusion). No alternative tools are named and no conditions for selection are given, leaving usage inference largely 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 establish read-only, idempotent, non-destructive behavior, so the description's added value is the countable behavioral nuance: it shows disagreement rather than picking one, and the counts are 'reported next to' each other rather than merged. It also discloses that filters only affect rows, not the two full counts, which is useful beyond the 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 front-loaded with the resource URL and the core comparison behavior, and every sentence contributes meaning. The first sentence is somewhat dense with nested clauses, but that density is justified by the nuanced behavior it must convey.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present and full parameter schema coverage, the description needn't explain return values or parameter syntax. It adequately covers the tool's distinguishing behavior, the never-reconcile boundary, and the filter behavior, leaving no major gap for invocation decisions.

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 input schema already documents both axis and limit. The description merely restates them as 'Optional filters return recent rows: axis, limit' and adds no new parameter-level detail 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 names the resource ('published signed-card index'), the verb ('list'), and a highly specific behavior: reporting the declared n_cards, the actual row count, and the card-store endpoint count side by side without reconciling them. This is far more than a restatement of the title and clearly separates it from generic card-listing tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives a clear context for use by explaining that the tool intentionally reports two counts from two surfaces and 'never reconciles' them, so an agent knows it should not be used when a single reconciled answer is needed. However, it does not explicitly name sibling alternatives or say 'use X when Y', so it stops short of full 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?

Annotations already mark the tool read-only, open-world, idempotent, and non-destructive. The description adds substantial behavioral context beyond that: host details are withheld by design, partial rounds or cap changes are disclosed, it is measurement rather than certification, and the three possible states are defined. This is exactly the kind of transparency that helps an agent set expectations.

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, leading with method, resource, and URL before moving to the counts. Every sentence earns its place: scope, privacy caveat, disclosure caveat, epistemic caveat, and state definitions are all conveyed 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 zero-parameter read-only tool with rich annotations and an output schema, the description covers all essential context: what is counted, how states are classified, what caveats exist, and what limits apply. Nothing needed to call it correctly or interpret its result 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, so there is nothing for the description to explain beyond the baseline. Schema coverage is effectively 100% and the empty parameter object is self-explanatory.

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 verb ('GET'), a specific resource (the latest MCP handshake trust snapshot), and gives the exact URL. It then enumerates what the snapshot contains, so an agent knows unambiguously what this tool does and can tell it apart from related census-style 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 makes the tool's context clear: use it when you need internet-facing MCP handshake trust counts by doctrineches. However, it never explicitly says when to use this tool versus alternatives like x402_trust, nor does it state any exclusions or fallback conditions.

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

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

The description goes well beyond the readOnly/idempotent annotations by disclosing concrete behaviors: re-verifying the board signature against pinned did:web:csoai.org#board-attestation-1, never calling PENDING attested, and defining NOT_PUBLISHED and UNREACHABLE fallback states. This gives an agent accurate expectations for the operation's result semantics. No contradiction with the readOnlyHint=true annotation.

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

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

The description is a single dense run-on sentence with a long colon-delimited enumeration, making it structurally unwieldy despite containing no wasted words. Front-loading the verb and resource is good, but the content would be more digestible as shorter sentences or bullet points.

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 presence of an output schema that presumably defines return fields, the description covers the source URL, the read scope, verification behavior, semantic limitations, and edge-case states. An agent has enough information to decide whether to call this tool and what to expect, with nothing substantial 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 schema coverage is trivially 100%, so the baseline of 4 applies. The description adds context about the fixed source URL and the verification performed, which substitutes for parameter-level guidance since no parameters exist to document.

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: 'Read the latest signed measurement-capsule index published at https://councilof.ai/measurement-capsules/latest.json'. It enumerates the precise contents read (index root, batch fields, board signature re-verification, anchor states), which clearly distinguishes it from sibling verification tools that target individual capsules or cards.

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 provides strong contextual scope, such as 'States only: measurement, not endorsement; no verdict, score or ranking' and the NOT_PUBLISHED/UNREACHABLE conditions, which help an agent infer when the tool is appropriate. However, it never names sibling tools or explicit when-to-use/when-not-to-use conditions like 'use verify_capsule instead for a single capsule'. Usage is implied by scope rather than stated directly.

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 readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description goes beyond these by specifying concrete behaviors: an unmeasured endpoint returns NOT_MEASURED with an empty list, never an error and never a clean bill; there is no verdict, score, or ranking; and the shard key is a sha256 of the normalized URL. This materially enriches the safety and expectation profile.

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 logically organized: core purpose first, then capsule contents, retrieval mechanics, empty-result semantics, and a closing non-endorsement caveat. Every clause carries substantive value, though the length and technical density could be hard to parse at a glance for a simpler agent.

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 one simple parameter, a rich output schema, and annotations covering safety and world-openness, the description supplies all remaining decision-relevant context: empty-list vs NOT_MEASURED behavior, the inclusion verification pointer, and the per-batch origin of capsules. Nothing critical 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 schema documents endpoint_url with a clear example, and coverage is 100%. The description adds meaningful usage context—normalization via sha256 and single-endpoint scoping—which helps the agent understand how the parameter drives the lookup, even though the format is already well-specified.

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 reading operation: 'every published measurement capsule about ONE endpoint URL across all batches' and 'Read from a static per-endpoint shard'. It clearly differentiates this tool from aggregate-focused siblings like board_totals and from verification-only tools like verify_capsule, so an agent can tell what unique value this tool provides without opening 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 opening 'Trust per server, not totals' signals when to prefer this over aggregate views, and the mention of verify_capsule re-deriving inclusion points to the verification alternative. It does not explicitly list when-not-to-use or name an exclusion, but the context is clear enough for an agent to choose sensibly.

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 read-only, idempotent, and non-destructive, and the description adds substantial detail beyond that: recomputing capsule_id, picking the schema rule, finding the published batch, recomputing the root, and returning an audit path. It also discloses all possible output states and the semantic limit that verification is proof of publication, not endorsement. 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?

The description is dense and information-rich rather than padded, front-loading the core action and input requirement. The caveat about measurement vs endorsement adds value; the enumerated output states are slightly redundant with the output schema but still useful in a single glance.

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, read-only tool with an output schema, the description is fully sufficient. It covers the input format, the verification algorithm, all result states, cost, and semantic limitations, leaving no critical operational knowledge 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 schema covers the single parameter 100%, providing a baseline of 3. The description adds meaningful nuance by explaining that JSON text is preferred for byte-exactness and that number lexemes are preserved, which helps the agent choose the correct input form.

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, 'Verify one measurement capsule', and then defines the exact domain and schema ('csoai.measurement-capsule/0.2'). This distinguishes it clearly from sibling tools like verify_card and verify_inclusion, and it does not merely restate the title.

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 input guidance: pass capsule_json as byte-exact JSON text or an object. It also explains what verification proves and what it does not prove. However, it does not explicitly contrast this tool with siblings such as verify_inclusion, so the when-to-use-vs-alternative guidance is implicit rather than explicit.

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?

Goes well beyond the readOnly/idempotent/destructive annotations by disclosing the pinned-key trust model, why inline keys are INVALID, why DID references outside the pinned set are UNCHECKABLE, and the explicit three-verdict (never two) contract. Also flags 'never a certification' and that URLs are fetched (consistent with openWorldHint).

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?

Dense but front-loaded: the action and rule come first, then the key-pinning rationale, verdicts, and accepted inputs. A few clauses are long, but each carries decision-relevant information rather than 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?

Output schema exists, so return details need not be restated, and the description still explains what pinned_key in the result means and what the verdicts imply. Complete for a single-parameter verification tool with a nuanced trust model.

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?

Only one parameter with 100% schema coverage, and the description reinforces it by naming the three accepted forms (object, JSON string, councilof.ai/csoai.org URL). The URL-fetch behavior adds practical meaning beyond the schema's anyOf.

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 (verify) and resource (a signed gspc.measurement-card) and describes exactly what it recomputes and checks. It is clearly distinct from siblings like verify_capsule and verify_inclusion.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explains the verification rule, the accepted input forms, and the three-verdict semantics, which gives strong context for when the tool applies. It does not explicitly route the agent away from sibling verifiers (verify_capsule, verify_inclusion), so sibling selection is left 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?

Annotations already provide readOnly, idempotent, and non-destructive hints, and the description adds substantial behavior beyond those: the exact HTTP GET mechanism, the three-state output contract (VALID, INVALID, UNCHECKABLE), the failure mode for an unreachable endpoint, and limitations around Ed25519. This is rich, non-redundant 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?

Three sentences, each carrying unique information: the action and endpoint, the allowed return states, and the explicit non-claims. The most important information is front-loaded, and there is no 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?

With a single well-documented parameter, complete annotations, and an output schema, the description still covers the essential behavioral details an agent needs: the endpoint, the three possible outcomes, and the failure mode. Nothing required 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?

The input schema already fully documents the only parameter as a '64-char hex digest', so schema-description coverage is 100%. The description does not add parameter-level 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 verb and resource: 'Check a sha256 against the live public-root merkle via GET /api/proof?sha='. It also distinguishes itself from sibling tools by explicitly excluding Ed25519 claims and grading, making its scope 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 clear exclusions: it does not claim Ed25519 and is never a grade, which tells an agent when not to use it. However, it does not name an alternative sibling tool or state a positive 'use this when...' condition, so it stops 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?

The description adds meaningful behavioral context beyond the annotations: host details are withheld, counts are doctrine-only, and a 402 is explicitly not delivery. These caveats clarify both scope and limitations in a way the schema and annotations alone would not convey.

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 entire definition is a single dense sentence that front-loads the operation and resource, then packs essential caveats into semicolon-separated clauses. Every phrase earns its place; 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 zero-parameter read-only snapshot with an output schema, the description is fully adequate. The annotations cover safety and idempotence, and the description covers semantic limitations. Nothing needed to call this tool 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 tool has zero parameters and 100% schema coverage, so the description has no parameter burden. The baseline of 4 applies; the description appropriately makes clear this is a no-input snapshot call.

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 clearly identifies a specific verb ('GET'), a specific resource ('x402 catalog trust snapshot'), and the exact data being returned (counts of correct 402 challenges vs phantom resources). It is distinct from sibling tools like mcp_trust by focusing on x402 catalog counts, not general trust or individual records.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies when to use this tool: when you need aggregate x402 catalog trust counts by doctrine. It also warns 'measurement, never certification,' suggesting it should not be used for certification decisions. However, it does not explicitly name alternatives or state exclusion conditions, leaving some inference required.

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