Step 6: sanity-check rare events against base rates

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered elsewhere. The description adds workflow context (step 6, standalone mode) but says nothing about what output is produced, why idempotentHint is false, or what happens when supplied prevalence/sensitivity values are inconsistent — gaps that matter for a calculation tool.

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 compact sentences, front-loaded with the workflow position and the eligibility condition; the usage exclusion is placed last where it belongs. The middle sentence is telegraphic ('Give prevalence, sensitivity, specificity (0–1), or file + condition_column + test_column') but still parseable.

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, non-destructive calculation tool with no output schema and no required parameters, the description states both the computed quantity and the input options, plus the escape hatch to skip_step. It has no structured output contract to lean on, and the confirmation_token gating is only covered by the schema, but nothing essential to making a correct call 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 only 14%, so the description must carry the load — and it largely does, defining prevalence/sensitivity/specificity as 0–1 quantities and test_column/condition_column as 0/1 indicator columns, plus the two alternative call shapes. It does not explain whether the two modes can be mixed or which combinations are valid, which is why this is a 4 rather than a 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?

The description names a specific computation (what share of positive flags is real, i.e. PPV) for a defined class of problems (rare events: fraud, defects, diagnoses, churn), and ties itself to workflow position step 6. It is distinguishable from siblings, though the phrasing 'sanity-check' in the title is looser than the body text.

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 both when to use (rare-event questions, or standalone during exploration) and when not to (non-rare-event questions → use skip_step 6), naming the alternative tool explicitly. It also tells the agent which of two input modes to supply.

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