list_risk_criteria

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

Annotations already declare readOnlyHint and idempotentHint, so safety is covered; the description goes well beyond them by disclosing a hidden behavioral fact — writes to these fields are silently overwritten by a business rule — which prevents a wasted or misleading write attempt. That is exactly the kind of non-obvious context only the description can supply.

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 core purpose and the row/ordering detail are front-loaded, and the trailing cautionary clause carries real information. It is dense but the em-dash parenthetical is long enough to slightly strain readability; still, every clause 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?

Single optional enum parameter, no nested objects, no output schema, read-only annotations — and the description covers what is returned (five ordered rows per scale type) plus the critical caveat about writability. Nothing needed to call or interpret 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 'type' parameter is already documented with an enum in the schema. The description's '5 rows per type' adds mild context about result shape per filter value but does not explain format or defaults beyond the schema, so 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?

The description names a specific verb and resource ('List the Impact/Likelihood/Score scale (sn_risk_criteria)') and adds concrete structure the agent can rely on: five rows per type, ordered. It is unmistakably distinct from list_risks, get_risk, or list_risk_statements.

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 states the intended purpose explicitly — reference only, to interpret a Risk's calculated values — and names the alternatives it should not be paired with ('NOT settable via create_risk/update_risk'), with the reason (business rule recalculates regardless of client input). That is a complete when-to-use / when-not-to-use / alternative routing instruction.

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