find_bored_bosses

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

The description states 'read-only and diagnostic,' consistent with the readOnlyHint annotation, and adds valuable behavioral context beyond the annotation: the tool reports target-selection/edit evidence, is not proof of a requested target, and lists what it will output. No annotation contradiction exists.

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 dense but every clause earns its place: the first sentence defines the tool's result and the specific evidence items, and the second sentence gives usage timing, scope, and a crucial caveat. It is front-loaded with the main action and contains no redundant filler.

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 diagnostic tool with an output schema, the description covers purpose, usage timing, output contents, and caveats, which is largely complete. The main gap is the lack of guidance around the object_name parameter and how the tool selects the target, leaving a small but relevant invocation ambiguity.

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?

The only parameter, object_name, has 0% schema description coverage and the description never mentions it. An agent receives no guidance on what object_name refers to, whether it is optional given its default '', or how it affects the search. The parameter name is somewhat self-explanatory, which prevents a 1, but the description fails to compensate for the low schema coverage.

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 verb and resource ('Find candidate bored bosses') and enumerates the exact evidence reported, including bore opening location, axes, diameter/depth, cap faces, and construction advice. It also distinguishes this tool from generic boss-finding via 'whatever its outer profile' and from final proof via 'not proof of the requested target.'

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 explicitly says to use this tool 'before lengthening any boss that carries a bore' and notes it is 'read-only and diagnostic, not proof of the requested target,' giving clear context and a limitation. It does not name alternative sibling tools, so the guidance is strong but not maximally explicit about when NOT to use it in favor of another tool.

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