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

Annotations only declare readOnlyHint and openWorldHint, but the description adds that a call has a real cost ('costs a fraction of what a wasted call... costs you'), implying this is a metered/paid operation the agent should not spam. It further discloses the semantic meaning of low vs. unknown scores, which is behavioral interpretation not captured by any structured field.

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 the core action and the return payload, then edge-case guidance, which is good ordering. It runs slightly long and includes mild persuasive framing ('weigh the call accordingly', cost justification) that repeats the risk argument, costing it a point on tightness.

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 tool with an output schema and readOnly/openWorld annotations, the description covers purpose, when to invoke, result interpretation, and the unknown-service edge case. Nothing needed to invoke or correctly interpret the tool is missing, and return values need not be re-explained beyond the interpretation it provides.

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 service_did parameter already documents the accepted URL/domain/DID formats and that they resolve identically. The description adds no format or constraint detail beyond that, so the schema does the work and 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?

States a specific verb and resource ('check what other agents measured about a service') and immediately scopes the resource as someone else's ratings, which implicitly separates it from submit_rating (writing) and list_services (enumeration). It also names the concrete return shape (0-1 score, confidence, rating count, per-dimension breakdown), so an agent knows exactly what comes back.

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?

Explicit on when to use: before calling an unknown service, before paying, before handing over anything irreversible, and specifically after receiving a 402 Payment Required. It also gives the non-obvious unknown-service case ('unverified rather than safe'), which is exactly the guidance an agent needs to interpret results correctly.

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

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

Annotations already cover the safety profile (readOnlyHint=true, openWorldHint=true), so the bar is lower. The description still adds real interpretive context: results are pre-filtered to rated services, default ordering is by trust score, and it explains how to read score/rating-count together; it does not cover pagination or rate limits, but those are minor.

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, front-loaded with what the tool returns, then why to use it, then how to interpret the filters. Every sentence carries distinct information and none restates the schema.

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

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

With an output schema present, annotations covering safety, and 100% schema coverage on four optional parameters, the description only needs to supply usage intent and interpretation — both of which it does. Nothing an agent needs 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?

Schema description coverage is 100%, so the baseline is 3, and the description genuinely adds meaning beyond the schema by explaining the min_score + min_ratings interaction ('a high score backed by one rating is an opinion, the same score backed by many is evidence'). It doesn't add anything for limit or sort_by, keeping it below 5.

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 scope ('sorted by trust score, with their per-dimension breakdown'), which clearly separates it from a single-service lookup. It stops short of naming the siblings (check_reputation, submit_rating) to make the contrast explicit, so it reads as clear but not sibling-differentiating.

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 concrete when-to-use conditions: choosing a service others have already measured, and finding an alternative when a candidate scores badly. It also warns to combine min_score with min_ratings so a lone high rating isn't mistaken for evidence. No explicit 'when not to use' or named alternative tool, so it falls just short of the top band.

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.