calculate_concrete_stairs

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

No annotations are provided, so the description must convey behavioral traits. It states the tool uses Blondel's formula, which gives insight into the calculation method, but does not disclose whether the tool is read-only, idempotent, or has side effects. For a calculation tool, the lack of explicit safety guarantees is acceptable, but more detail (e.g., 'returns results only, no changes') would improve transparency.

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 concise: two sentences, no filler. The first sentence states the core purpose and method, and the second provides a useful cross-reference to related tools. Every word 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?

Given the complexity (4 parameters, output schema present), the description is fairly complete. It covers the purpose, method, and related tools. The absence of output details is mitigated by the output schema. A mention of the expected output format or examples could enhance completeness, but it is adequate for a calculation tool.

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%, with each parameter well-described (e.g., 'Total stair height to climb in meters'). The description adds context by stating the tool calculates 'dimensions, volume and materials', implying the output includes these, and mentions Blondel's formula, which is a meaningful addition. This justifies a score above the baseline of 3.

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 calculates concrete stair dimensions, volume, and materials using Blondel's formula. It specifies the resource (concrete stairs) and the verb (calculate), and distinguishes from siblings by referencing list_bundles for related calculators, though explicit differentiation from 'calculate_staircase' is lacking. Overall, it is specific and unambiguous.

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?

The description implies usage when needing concrete stair calculations (using Blondel's formula) and points to list_bundles for related construction calculators. However, it does not provide explicit when-to-use or when-not-to-use guidance, nor does it mention alternatives (e.g., 'calculate_staircase' for general stair calculations).

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