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

Annotations only mark this as a read-only, open-world call; the description goes well beyond that by explaining the 0–1 score, the confidence level, the per-dimension breakdown, how to interpret a low score, and the critical caveat that an unknown service means 'unverified' rather than 'safe'. That interpretation guidance is exactly what an agent needs and cannot get from 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?

Reasonably long but front-loaded with purpose, returns, and interpretation in that order. The cost-framing sentence is persuasive rather than strictly definitional, but it does inform the agent's decision threshold, so it mostly 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 check with a full output schema, the description covers everything needed: what is returned, how to read each element, the unknown-service case, and the concrete 402 follow-up path. No gaps remain for correct invocation or interpretation.

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 already 100%, so the baseline is 3, but the description adds real value: it explains the 402-driven workflow for pay_to (comparing the 402 payTo against the registry's observed payee) and confirms service_did format-agnostic resolution, which goes beyond the schema text.

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 ('Check what other agents measured about a service') and immediately frames the decision it supports. It is clearly distinguishable from the write-side sibling submit_rating and the enumeration sibling list_services without opening any schema.

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

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

Gives strong triggering conditions: run it before calling an unfamiliar service, especially before paying or handing over anything irreversible, and specifically after a 402 Payment Required. It does not explicitly name when to skip it or cite the sibling tools as alternatives, so it falls short of the full when/when-not/alternatives bar.

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 and openWorldHint=true, so safety is covered. The description still adds real behavior: results are ordered by trust score, include a per-dimension breakdown, return a total matching the filters, and are paged with offset. It stops short of noting auth needs, rate limits, or how many dimensions appear, which keeps it below a 5.

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?

Front-loaded with purpose, then usage, then filter semantics, then pagination – a logical progression where each sentence carries a distinct instruction. The 'opinion vs evidence' framing is slightly expansive but still earns its place as filter rationale.

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

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

An output schema exists, so return values need no explanation, and the description still supplies the total-count/paging behavior an agent needs. With six optional parameters and the filtering strategy explained, an agent has everything required to call this correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes beyond the schema by explaining the min_score/min_ratings interplay (score without rating volume is an opinion) and the precise meaning of x402=true (paid endpoints whose payee/price terms the registry records). That is genuine semantic added value over the field-level descriptions.

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

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

States a specific verb and resource ('List services that have been rated'), plus the ordering ('sorted by trust score') and the payload shape ('per-dimension breakdown'). This clearly separates it from check_reputation (single-service lookup) and submit_rating (a write), so an agent can route without opening any schema.

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

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

Explicitly names two use cases (pick an already-measured service; find an alternative when a candidate scores badly) and gives operational advice on combining min_score with min_ratings. It also states exactly when to set x402=true. Nothing about 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 declare this is a non-read-only, non-idempotent, open-world write; the description adds genuinely new context beyond them — that ratings persist under a stable installation identity and are read back on future encounters, and that receipt-backed ratings carry 'full weight.' It omits whether duplicate submissions overwrite prior ratings, which matters given idempotentHint=false, but the added context is substantial.

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 instruction is front-loaded with the concrete action first, and the receipt rule lands last where it is actionable. Some middle sentences are persuasive rhetoric ('This is not a donation to a commons,' 'you will meet it again with no memory of it') that restates the same persistence point twice rather than adding operational detail.

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 no explanation, and the schema fully documents all seven parameters. For a write tool this rich, the description covers what to submit, when to submit it, and the receipt path, leaving nothing essential an agent 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 description coverage is 100%, so the baseline is 3, but the description meaningfully enriches several params: status_code/latency/schema_valid are framed as 'metrics you already have from the call,' and receipt is explained via its source header (X-Trust-Receipt) and its effect ('carries full weight'). It does not touch response_size_bytes or quality_score, so a small gap remains.

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 opening sentence states a specific verb ('Report') and resource (the outcome of a service call), and enumerates the exact data to supply: status code, latency, response-shape match. It implicitly distinguishes itself from check_reputation by framing submission as writing to the cache that is later read back. It never names a sibling outright, so it stops short of the top score.

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 clear triggering context ('after you called a service') and an explicit inclusion rule ('Report the good ones too: a score is only useful if failure and success are both in it'), plus a conditional instruction for the receipt header. It does not name an alternative tool or a when-not-to-use condition beyond refuting the 'donation to a commons' misconception.

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