nbc_stair

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

The annotation block contains only a title, so the description carries the full burden of behavioral disclosure and adds little. It mentions a specific validation rule (2R+T [600,650]) and 'fallback geometry', but does not disclose whether the tool creates geometry, mutates the drawing, requires a running CAD session, or what happens on validation failure. The behavioral consequences of invoking this tool are largely opaque.

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 short and arguably front-loaded with the domain word 'Stair', but it is not a model of conciseness because it compresses too much cryptic context into a parenthetical: 'YQArch ltj / fallback geometry' is unexplained and likely meaningless to an agent without domain-specific training. The sentence is compact but spends characters on jargon while omitting more useful operational information.

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?

Although an output schema exists, the input contract remains nearly empty: operation is an undocumented string, data is an arbitrary object, and no examples or value constraints are provided. The description does not say what inputs are expected, what operations are supported, or what 'fallback geometry' means in practice. This is incomplete for a tool with an opaque required parameter and an open data object.

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 0% and the description does not name or explain any of the three parameters. The required 'operation' parameter is completely unspecified with no enums or examples, 'data' is an open object with no shape guidance, and 'include_screenshot' is only inferable from its name. The description's tread/riser hint suggests what data might contain, but it does not meaningfully compensate for the total absence of parameter documentation.

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 identifies the stair domain and a validation rule (2R+T in [600,650]), so it is not a tautology and does distinguish the stair resource from wall/opening/entity siblings. However, it lacks an explicit verb stating what the tool actually does—create, validate, modify, or query. 'Stair (YQArch ltj / fallback geometry)' is cryptic and the only action word, 'validated', is subordinate rather than the main predicate.

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?

No guidance is given about when to use this tool versus alternatives such as nbc_entity, nbc_generate, or nbc_wall. The tool name and 'Stair' hint at the intended domain, but the description does not state conditions, exclusions, or how to choose between this and sibling tools. An agent must infer usage entirely from the name.

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