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

Beyond the annotations, the description discloses free/no-key access, the 1:50 scale, the returned project id and purchase_url, the checker's behavior when openings are omitted, and the coordinate system. These are material behavioral facts that an agent needs to invoke the tool correctly and interpret results.

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 efficiently structured: it front-loads cost, purpose, and return values, then covers the two parameter modes and key constraints in a few short sentences. No sentence is filler; even the coordinate note earns its place because it directly affects how rectangles and opening centers are interpreted.

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 creation tool with six parameters and no output schema, the description covers the required call shape, parameter alternatives, coordinate semantics, measurement bounds, return values, and checker side effects. There is no critical missing context an agent would need to make a correct first call.

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 100%, but the description adds crucial meaning not inferable from property names alone: the never-both rule for the two room-shape modes, the x-right/y-down coordinate origin at the top-left corner, the global side range of 0.3–200 m, and the requirement to send openings in this same call. This goes well beyond the schema's per-property descriptions.

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 states a specific action ('Creates a new plan at scale 1:50') and explicitly names the return values (project id and purchase_url). This clearly distinguishes it from sibling tools like check_plan or show_plan, which operate on existing plans rather than creating one.

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?

It gives strong operational guidance: use either width_m/depth_m or rectangles, never both, and always include openings in the same call or the door-swing check is skipped. It does not explicitly name alternative tools or give a when-not-to-use comparison, so it misses the strongest form of usage direction.

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