inspect_design

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

With no annotations at all, the description carries the full burden, and it does disclose real behavioral facts: channels are opt-in (so defaults are not the full set), results are written to a manifest.json bundle (an output/side-effect location), there is a 3-per-month free quota versus unlimited Pro, and one channel is Pro-gated. What is missing is whether this writes files to disk as a side effect and how the tier is enforced, but the quota and bundle behavior are genuinely useful context.

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 first sentence is front-loaded with the tool's capabilities and the second and third carry the operationally relevant tier constraints. The closing pricing URL is somewhat promotional and carries agent/tool tracking parameters, but it does encode real tier gating, so it is not pure waste. Overall tight and well ordered.

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 4-parameter tool with no annotations and no output schema, the description does the important work: it explains what the returned artifacts are, where they land (manifest.json bundle), and the tier limits that constrain invocation. The remaining gaps are the unexplained bundle_dir/product_type parameters and the unspecified default channel set, which is a modest shortfall rather than a failure.

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 only 50%, and the 'channels' parameter has an untyped item schema ({}) with no enum, so the schema cannot tell the agent what values are legal. The description partially compensates by naming the analyzable outputs (previews, cross-sections, measurements, verdict), which likely map to channel values, and by noting channels are 'opt-in'. It adds nothing for bundle_dir or product_type, both of which appear with only a default value and no meaning.

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 pair ('render and analyze') and resource ('3D mesh'), then enumerates the concrete outputs: shaded previews, cross-section slices, measurements (volume, watertightness, dimensions), and a print-readiness verdict. That is far more informative than a tautology. However, it never distinguishes itself from heavily overlapping siblings such as inspect_mesh_view, analyze_mesh_geometry, cross_section_view, or mesh_quality_scorecard, so an agent cannot tell from the text alone which of these to pick.

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?

There is no when-to-use / when-not-to-use guidance and no named alternative. The only routing signal is the tier gate ('print-readiness verdict (Pro+)' and 'Free tier: 3 inspections/month'), which tells the agent about eligibility but not about tool selection versus the many sibling mesh-inspection tools. Usage must be entirely inferred.

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