explain_finding

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 disclose the important edge case: a code with no written recipe returns only the rule link and signals that fact, and nothing is invented beyond the written content. It omits auth, rate-limit, and pagination behavior, but the degradation contract is the disclosure an agent most needs here.

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?

Two sentences, front-loaded with what the tool returns before the empty-recipe caveat. Dense but each clause adds information; the closing hedge 'nothing is described beyond what is written' slightly repeats the no-recipe clause but usefully bounds expectations.

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?

There is no output schema and no annotations, so the description must describe the return shape itself, and it does: recipe, rule link, optional tool fix path, and the partial-result case. Given a simple two-parameter lookup, this is complete enough 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 description coverage is 100%, so both the 'code' example and the enumerated producing-tool keys are already documented in the schema. The description adds only marginal meaning by tying the 'tool' parameter to the returned fix path, which is the baseline expectation when the schema does the heavy lifting.

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 resource precisely — the fix recipe, rule link, and optional producing-tool fix path for a notice code — so an agent knows it is a lookup keyed on a validator/scorecard code. It distinguishes itself somewhat from retrieval siblings like get_scorecard and get_evidence_packet by specifying the fix-recipe payload, though it never states the action verb outright.

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?

Usage is implied: you supply a notice code to learn how to fix it, and optionally a producing tool to get that tool's fix path. There is no explicit when-to-use vs. when-not, and no sibling is named as the alternative, so an agent must infer the trigger condition from the code parameter alone.

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