math_bmi_calculator

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

The description adds valuable context beyond annotations: 'Runs locally on the values you provide: read-only, non-destructive, contacts no external service, and is rate-limited (60 requests/minute for anonymous callers).' Annotations already declared readOnlyHint=true, destructiveHint=false, idempotentHint=true, but the description enriches this with specificity.

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 densely packed with useful information yet remains concise. It front-loads the core function, then details operations, usage guidelines, and returned data. Every sentence earns its place without redundancy.

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?

Given the tool's complexity (7 parameters, nested objects, three operations, and an output schema), the description covers all necessary details: operation variants, unit system handling, expected inputs for each mode, and an overview of the return values (BMI, category, interpretation, healthy weight range). The presence of an output schema doesn't require further description of return structure.

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 coverage is 100%, but the description adds meaning by explaining each parameter's role in different operations (e.g., 'Required for compute', 'Required only when operation is target-weight'). It clarifies that 'height' can be inches or an object with feet/inches, and describes the a/b objects for compare.

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 clearly states the tool computes BMI from height and weight in metric or imperial units, returns WHO category and healthy weight range, and lists three operations (compute, target-weight, compare). It differentiates from siblings by specifically mentioning when to use math_unit_converter or math_percentage_calculator.

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?

Explicitly says when to use this tool for body-composition math and provides clear alternatives ('use math_unit_converter for plain length or mass unit conversion, or math_percentage_calculator for generic percentages'). Also notes it runs locally, is read-only, non-destructive, and rate-limited.

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