Add Bearing

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

The description goes well beyond the annotations by detailing error conditions ('Raises ValueError if the designation is unknown... or if outer_diameter <= bore'), the return payload with field meanings (handle, designation, orderable, catalog), and the semantic distinction between an orderable designation and a raw dimensional envelope. It also clarifies that seal variants do not change geometry but are part of the orderable identity, which is non-obvious behavior. No contradiction with the readOnlyHint=false annotation.

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 front-loaded with the core purpose and geometry, then organizes the two specification modes, seal semantics, and error/return behavior in a logical flow. While it is long (about 300 words), each section carries necessary semantic detail and no filler. It could be more scannable with bullets, but the paragraph structure is coherent.

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 has no output schema and the annotations are minimal, the description compensates by explaining the full return contract: the returned handle prefix, the None designation for explicit-dimension envelopes, and the orderable/catalog semantics. It also covers coordinate orientation, placement, and error cases. The only missing context is the 'name' parameter, which is a minor defaulted field.

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?

With 0% schema coverage, the description must explain all parameters and largely does: bore, outer_diameter, width, designation, seals, and placement each receive explicit meaning and application (e.g., 'bore: inner-bore diameter mm (sizes the shaft)'). It even provides a known-designation list and an example mapping. The only omitted parameter is 'name', which is a generic defaulted string, so the gap is minor.

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 opens with a specific verb and resource: 'Add a deep-groove ball bearing as an assembly *envelope* solid'. It clarifies the geometric nature (annular ring, axis along +Z, balls/races not modeled) and distinguishes it from other mechanical component adders like add_gear or add_pulley. The mention of the coordinator's sizing needs further specifies its role.

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 states the intended use case: 'the fit envelope a coordinator needs to size the shaft, the housing bore, and the shoulder spacing.' It also explains the two mutually exclusive input modes (designation vs explicit dims) and when explicit values override table values. However, it does not name sibling alternatives or explicitly say when not to use this tool.

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