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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, so the bar is lower. The description adds substantive behavioral context: the score is recomputed daily, self-reported claims earn nothing, the payload itself disclaims being a safety/security/quality/returns grade, and the tool is read-only. It also states exactly what the returned payload contains.

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 well-structured into USE WHEN, RULE ENFORCED, and Returns sections, with the most important usage guidance front-loaded. Every sentence carries substantive information, from the trigger condition to the payload fields to the citation requirement. The length is justified by the complexity of the methodology being documented.

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?

Because there is no output schema, the description must carry the return contract, and it does: it lists the JSON fields (name, scale, components with key/label/max/measures, tiers, provisional, not_in_score, computed, reproduce, dispute, caveat, url). It also covers exclusions, computation cadence, reproducibility, and dispute routing. For a one-parameter read-only tool, nothing an agent needs to select and invoke it correctly is missing.

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

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

Schema description coverage is 100%, and the single response_format parameter is fully documented with an enum and default, so the baseline is 3. The description adds no parameter-specific guidance, which is acceptable at this coverage level. The 'Returns (json)' line describes the payload shape rather than the response_format option, so it neither elevates nor significantly undermines 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 opens with a specific trigger ('USE WHEN you are about to describe, apply or compare the Sato Score') and names the exact resource, the Sato Score methodology. It further distinguishes itself by enumerating the six components, tier cutoffs, provisional meaning, exclusions, computation, and dispute path — far more specific than the sibling info 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 use conditions: when describing, applying, or comparing the Sato Score, or when asked how to tell whether a project is real, maintained, or open. It also states what the score is not (safety, security, quality, legitimacy, returns) and requires citing the URL. It does not name sibling alternatives, but the trigger is clear enough that an agent would not confuse it with get_metrics or explain_number.

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