generate_soap_dish

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 real behavior: a free-tier cap of 3/month, Pro unlimited, automatic mesh decimation for the stage, an inline MCP Apps viewer with a browser fallback link, and that the PNG is a floor not the full output. It omits generation latency, failure modes, and whether the result is persisted as a design.

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 core purpose is front-loaded well and the quota line is efficient. However, the final 'INLINE 3D STAGE' paragraph restates the stage/viewer point already made in sentence two, and the pricing URL with tracking parameters adds bulk that serves billing rather than tool selection.

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 14-parameter generator with no annotations and no output schema, the description covers the experience (stage, preview, quota) but not the mechanics: what the call actually returns (design id, mesh, PNG path, 3MF?), whether output persists, and what the geometric parameters do. Adequate to start a call, not adequate to use it well.

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 nominally 100%, but the schema descriptions are only default values ('Default: 65.0.'), so no real semantics exist anywhere. The description adds only 'optional bottom branding', which loosely maps to decoration/photo_mask; the other 13 parameters (depth, ridge_count, spout dimensions, include_step, material) get no explanation of effect or valid ranges.

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 first sentence gives a specific verb and resource plus differentiating attributes: 'Generate a draining soap dish with optional bottom branding.' That distinguishes it from the many other generate_* siblings (coaster, ashtray, pen cup) without ambiguity, and it names the render surface the result lands on.

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 'MAKE DOORS' block names design_session and compile_scad as alternatives, but the routing is muddled: it says design_session is not installed here and that 'compile_scad IS the make → preview → iterate loop', which reads as an instruction to use a different tool rather than a condition for choosing this one. It never says when to pick this generator over compile_scad or over the sibling generate_* product tools.

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