Council of AI GSPC

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

With no annotations present, the description carries the full behavioral burden and does so thoroughly. It discloses the paid nature, the 402 challenge flow, preview behavior, NOT_DEPLOYED behavior, the uncheckability of watermarks without public detectors, and the point-in-time scope. This goes well beyond a generic call description.

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, with the critical PAID status and payment flow front-loaded. Every sentence contributes behavioral or semantic detail rather than padding. It loses a point for a slightly awkward run-on opening that mixes the endpoint, the pack definition, and evidence components into one long sentence.

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 having no output schema and no annotations, the description explains the return contents, the free preview return, the 402 failure mode, the NOT_DEPLOYED failure mode, and the boundaries of interpretation. For a complex paid measurement tool with five parameters, this is unusually complete and leaves little ambiguity about expected behavior.

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 already covers all five parameters with 100% description coverage, establishing a baseline of 3. The description adds meaningful context on top: x_payment comes from signing against accepts[] from the prior 402, preview=true returns the same measurement unsigned, and manifest_b64 relates to a detached C2PA manifest store. This enriched context helps an agent select and format parameters correctly.

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 the tool returns an 'Article 50 marking-evidence pack' that measures whether a machine-readable mark is detectable in supplied bytes, and lists the evidence components. It names the exact endpoint and distinguishes its scope from a conformity or compliance opinion. However, the phrasing is more noun-like than an explicit verb+resource statement, and it does not directly differentiate itself from sibling evidence tools like rwa_evidence.

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 explains the payment workflow: it is paid via x402 or invoice, preview=true is free, omitting x_payment yields the 402 challenge, and an undeployed route returns NOT_DEPLOYED. It also states strong when-not conditions: the result is point-in-time detection and 'never a conformity opinion' or compliance statement. It does not, however, name sibling tools or say when to prefer this over them.

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It explains that data is live from the API, never cached or presented as live, that the two counts are never summed or swapped, and that a fetch failure yields a distinct UNREACHABLE state. This is unusually rich and explicit.

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 front-loaded with the core purpose, and each sentence conveys necessary semantic, failure, or freshness information. There is no filler; every clause supports correct invocation and interpretation.

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 output schema or annotations, the description fully compensates by covering return values, label meanings, freshness dates, and error behavior. An agent has enough information to invoke this tool and interpret its result without ambiguity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, and the empty input schema with additionalProperties: false fully documents this. The description adds no parameter-level detail because none is needed; the 0-parameter baseline of 4 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?

Clearly identifies the resource ('Live GSPC board totals'), the source endpoint, and the exact return values (slot count, measured count, as_of dates). The detailed slot/measurement distinction and UNREACHABLE state make the tool's role unambiguous relative to the sibling list.

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 this tool is for live measured board totals, but it never explicitly states when to prefer it over siblings or when not to use it. The only indirect exclusion is 'never certify,' leaving the agent to infer usage from the resource 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?

With no annotations provided, the description carries the full burden and does so thoroughly: it discloses the paid nature, conditional 402/challenge response, resurfacing of existing measurement cards, and the guarantee that payment never mints a MEASURED cell. This goes well beyond the basic mutating behavior implied by 'commission'.

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 efficient, leading with the most important fact (PAID x402) and then covering purpose, conditional behavior, exclusions, and verification in a few sentences. Every sentence carries information needed to invoke the tool correctly.

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 paid, no-output-schema tool, the description supplies the full call pattern: omit x_payment to receive the 402 challenge, and include it to commission. It also clarifies edge-case semantics around fresh_run and measurement, leaving no critical gap for an agent to guess.

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 of 3 applies; the schema already documents subject, axis, and x_payment. The description adds behavioral context about challenge retrieval and preview, but does not add meaningful parameter-level semantics beyond what the input schema states.

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 and resource: commission one signed card-v0 receipt for a subject via a specific endpoint. It also explicitly distinguishes itself from certification and verification, so an agent can tell it apart from sibling tools like verify_card.

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 clearly explains the x402 payment flow, including what happens when x_payment is omitted, and states exclusions ('never a rank, a grade or a certificate') and that verification stays free. It does not name a specific sibling tool to switch to, but the context is clear enough for tool 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?

With no annotations, the description carries the full behavioral burden and does meaningful work: it explains that an unmeasured axis is a first-class answer, never an error and never a zero, and that an axis row is never a certification. This prevents likely misinterpretations. It does not discuss errors, auth, or rate limits, but the core behavioral quirks of this tool are disclosed.

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, each earning its place: the first defines the returned object and source URL, the second clarifies the unmeasured-axis semantic, and the third rules out certification. It is front-loaded with the most important information and contains 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?

For a simple single-parameter getter with no output schema, the description is largely complete: it names the source, lists the returned fields, and explains the key special case (unmeasured axes). The unknown-name behavior lives in the schema description, which is acceptable. Minor gaps include no explicit response envelope and no relationship to sibling tools, but these are not critical for 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%, so the schema already fully documents the single required 'axis' parameter, including case-insensitivity and the unknown-name fallback. The main description adds nothing about the parameter itself, only about the shape and semantics of the returned row, so 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 clearly identifies the resource ('one axis row from the live GSPC board') and lists the fields returned, making the tool's purpose understandable. However, it is a noun phrase rather than an explicit verbed statement like 'Retrieves...', and it does not directly contrast with sibling tools such as get_card or board_totals.

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

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

The description gives no explicit guidance on when to use get_axis versus alternatives like get_card, board_totals, or verify_inclusion. It implies usage by describing the output, but it never states a selection condition, exclusions, or when another sibling would be more appropriate.

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 no annotations, the description carries the behavioral burden. It discloses the GET method, endpoint, the effect that UNMEASURED cells stay visible, and the three possible result states. It does not mention auth or rate limits, but for a public read operation the disclosed behavior is solid.

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 dense sentences front-load the core operation and result states, with no filler. Every sentence contributes information needed to invoke or interpret the tool.

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

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

For a one-parameter read with no output schema, the description covers input format, endpoint, and return classification. The only notable gap is that '{sha16}' in the URL template is not explicitly defined as a truncation or prefix of the provided sha256 hash.

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 the sha256 parameter. The description adds the 64-hex constraint and the URL template, but it does not significantly expand on 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 names the HTTP verb and resource precisely ('GET one public-root card-v0 leaf by sha256'), gives the exact endpoint template, and explicitly distinguishes itself from a GSPC measurement-card. This is enough for an agent to separate it from sibling tools like list_cards and verify_card.

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 intended use is implied: fetch a single card leaf and classify it as VALID, INVALID, or UNCHECKABLE. However, there is no explicit statement of when to choose this tool over alternatives such as verify_card, verify_inclusion, or list_cards, nor any when-not conditions beyond the brief 'Not a GSPC measurement-card' note.

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 no annotations provided, the description carries the full behavioral burden and does so well. It discloses permissionless access, enumerates the three possible result states (VALID, UNREACHABLE, UNCHECKABLE), and adds a meaningful non-obvious fact: the result is never a certificate.

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 with the core action and URL. Each sentence adds distinct value, though 'UNMEASURED notes' and 'GSPC' are used without explanation, slightly reducing accessibility.

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 parameterless GET tool with no output schema and no annotations, the description is remarkably complete: it gives the endpoint, returned fields, possible states, and a critical exclusion. An agent has enough information to invoke the tool and interpret its result without further documentation.

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 no parameter semantics to document. The description instead clarifies the fixed endpoint and return shape, which fully compensates for the empty schema. This matches the baseline for a parameterless tool.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb (GET), a specific resource (https://councilof.ai/root.json), and lists the exact returned fields (merkle_root, card_count, as_of, UNMEASURED notes). It also clarifies what this tool is not ('Separate from GSPC' and 'Never a certificate'), helping distinguish it from related concepts.

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 purpose clear—fetch the permissionless public-root—so when to use it is implied. However, it does not explicitly state when to prefer this tool over alternatives or mention any sibling tools by name; 'Separate from GSPC' hints at distinction but does not provide concrete 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?

With no annotations provided, the description carries the full disclosure burden and handles it well: it explicitly says the two counts are 'never reconciled', that the tool 'shows the disagreement rather than picking one', and that the limit only affects listed rows. It does not discuss auth, rate limits, or errors, but those are not critical for a read-style listing tool and no contradiction 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?

The description is compact and every sentence earns its place, especially the crucial no-reconciliation detail and the filter behavior. The first sentence is dense and parenthetical-heavy, making it slightly harder to parse than a cleaner front-loaded statement, which prevents a 5.

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

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

For a two-parameter tool with no output schema, the description tells the agent what the output contains (two labelled counts, recent rows), how filters shape the listing, and what happens when counts diverge. It does not specify the exact response shape or error cases, but those are not necessary for the agent to invoke and interpret 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%, and the schema already documents axis case-insensitivity, limit bounds, the default, and the fact that counts are always reported in full. The description merely names the two filters, adding no new semantic 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 identifies a specific resource (the signed-card index and card store endpoint) and explains that the tool reports two labelled counts plus optional recent rows. It does not open with a verb and relies on the name for the listing action, and it does not explicitly differentiate from siblings like get_card or verify_card, so it is not a 5.

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

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

The description gives clear context: use this tool to see the index-declared count versus the store-reported count without reconciliation, and to list recent rows with optional filters. It even states what happens when the counts disagree, but it never names alternatives or says when not to use it, so it falls short of explicit 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?

No annotations are provided, so the description carries the full burden. It discloses the paid nature, the preview=true free behavior, the ≤200 leaf cap, the response contents, the signed manifest card, the 402 challenge semantics, and explicitly denies claiming a settlement-receipt stream. This is rich behavioral disclosure beyond parameter names.

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 front-loaded with the most important fact (paid/402). Every sentence adds information; however it is somewhat lengthy and could be trimmed, but it remains efficient given the complexity of the payment flow and disclaimer.

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 financial/paid API with no output schema, the description is remarkably complete: it explains what is returned, the limit, the free alternatives, the payment handshake, and what the tool does not do. An agent can invoke this tool correctly without needing additional context.

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 four parameters. The description adds useful context by explaining preview=true's free return fields and how x_payment relates to the prior 402's accepts[], but it does not need to compensate for missing schema coverage. It earns a baseline 3 with slight added value.

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+resource: it retrieves a historical batch of measurement receipts from the councilof.ai API. It clearly differentiates from siblings by naming free alternatives (/root.json, /cards/, /api/proof?sha=) and the absence of a settlement-receipt stream, so an agent can tell it apart from the narrower verification/list 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 explicit when-to-use context: use for historical assembly across a date window, and explicitly says free recent leaves are available via listed endpoints. It also warns when not to use it: no settlement-receipt stream exists and /api/receipts/latest is unpublished, preventing misuse. It also explains the 402 payment challenge flow.

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 no annotations provided, the description carries the full burden and does so thoroughly. It discloses the payment flow, signed/unsigned states, hashing of fetches, deterministic snapshots at fetched_at, the three-way toml check behavior, and the NOT_DEPLOYED edge case.

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?

Information is front-loaded with the PAID qualifier and core purpose, and every sentence contributes meaningful detail. However, the content is packed into dense run-on sentences that could be easier to scan with structured bullets.

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?

Adequately complete for a complex paid tool with no output schema: it names the endpoint, the returned state components, free alternatives, payment behavior, preview behavior, and edge-case outputs. An agent has what it needs to call it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already documents asset, preview, and x_payment. The description mostly restates these semantics rather than adding new parameter-level detail, though it does reinforce the payment challenge flow.

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 exactly what the tool produces: a per-request signed evidence card of one XRPL asset's deterministic on-ledger state, and names the concrete endpoint. The emphasis on evidence of state versus verification/inclusion makes it distinguishable from sibling tools like verify_card 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?

Provides clear operational guidance: preview=true is free, omitting x_payment triggers the 402 challenge, and the tool is explicitly not a rating, guarantee, or conformity mark. It does not name sibling alternatives explicitly, but the paid/evidence-card context strongly implies when this tool applies.

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 no annotations provided, the description carries the full burden, and it delivers: it discloses the verification algorithm, the pinned key source, why self-carried keys are treated as INVALID, the exact three-verdict model, and the distinction between 'could not check' and 'forged'. This is far more transparent than a typical one-line tool description.

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 longer than average but every sentence earns its place: rule link, key ownership, signing caveat, verdict set, input formats, and certification exclusion. It is front-loaded with the core action and resource, and the additional detail is dense rather than padded.

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 no annotations and no output schema, the description is unusually complete: it defines the input forms, the acceptance rule, the exact verdicts, and the failure semantics. The only minor gap is that it does not specify the exact output envelope or field names for the verdict result, though the verdict vocabulary itself is clear.

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% for the single parameter, so the baseline is 3. The description adds meaningful semantics: the card must be signed, a self-provided key is not sufficient, and the input can be a JSON object, JSON string, or councilof.ai/csoai.org URL. It reinforces the schema without introducing conflicts.

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: 'Verify a signed gspc.measurement-card' under a published rule. It goes further by naming the exact mechanism (recompute id, check Ed25519 signature under the pinned key), which distinguishes it from siblings like 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?

The description gives clear context for when this tool is appropriate: verifying a signed measurement-card under a specific published rule. It explicitly excludes certifications ('Never a certification'), but it does not name sibling alternatives or state when not to use it beyond that single exclusion.

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 no annotations provided, the description carries the full burden of disclosing behavior, and it does so thoroughly. It names the HTTP endpoint, defines the three possible outcomes, flags the unreachable-endpoint case, and explicitly warns against overclaiming Ed25519 or grading, which are important behavioral caveats.

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 packed sentences convey the endpoint, input, output states, and important exclusions with no filler. The most important action and endpoint are front-loaded, and every sentence adds distinct value.

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 simple one-parameter schema, no output schema, and no annotations, the description is fully self-sufficient. It covers what the tool does, how it behaves on unreachable endpoints, what it does not verify, and what the possible return states are, which is all an agent needs to invoke it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, and the single parameter sha256 is already documented as a 64-char hex digest. The description reinforces that this value is checked against the merkle proof endpoint, but it does not add substantial meaning beyond what the schema already states.

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 ('Check'), a specific resource (sha256 against the live public-root merkle), and the exact retrieval path (GET /api/proof?sha=). It also enumerates the three distinct result states, making the tool's function unmistakable and distinct from siblings like get_root or verify_card.

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 indicates what this tool is for and what it is not for: it only checks merkle inclusion, never produces a grade, and does not assert Ed25519 validity unless separately checked. It provides useful when-not-to-use guidance, though it does not explicitly name alternative sibling tools.

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