assert_spec

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

With no annotations, the description carries the full burden and does disclose return behavior: failures expose 'actual', 'expected' and a 'fix' tool, and bad checks or missing objects are reported as 'error' while the rest still run. It does not state read-only vs mutating semantics, but the per-check reporting detail is substantive beyond structured fields.

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?

Dense but front-loaded: the one-call purpose and expectation-ordering advice come first, then the check catalogue. Length is justified by the mini-language it documents, though the type list could be tighter.

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?

No output schema and no annotations, yet the description explains both inputs (the check DSL) and outputs (pass/fail with actual/expected/fix, or error with partial execution). An agent has enough to construct a call and interpret the result.

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 0% and the single 'checks' array is opaque in the schema, so the description must compensate entirely — and it does, enumerating eleven check types with their fields (size, position, ratio, gap, contact, symmetry, inside, on_ground, clean, budget, connected). This is far more than the schema provides.

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 opening sentence states a specific verb and resource ('run all checks in one call, get pass or fail'), so the agent knows this is a batch assertion runner. It does not explicitly name which sibling it supersedes (run_spec, check_mesh, check_symmetry), leaving the agent to infer the distinction from the sibling list alone.

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?

'State your expectations before you look at the result, then fix only the failures' gives workflow guidance about ordering, and 'run all checks in one call' implies batch use. However there is no explicit when-to-use versus run_spec or the individual check_* tools, and no exclusions stated.

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