Make Drawing Page

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

Annotations include readOnlyHint=false and destructiveHint=false, but these are not contradictory (since creating a page is a mutating but non-destructive action). The description adds minimal behavior: it creates a page, uses a default template, and allows an optional template path. It does not disclose what happens to existing pages, whether the created page becomes active, or how it connects to the document context. Given the annotations are not rich, the description carries the burden; it provides some context but lacks deeper behavioral details.

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 concise, one sentence for the main purpose and one for the template parameter. Information is front-loaded with the core action and default. However, the description could be slightly more structured by separating the parameter explanation, but it is efficient and without fluff.

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?

This is a creation tool with no output schema, no required parameters, and two optional parameters. The description does not explain the context: when to create a drawing page (e.g., before adding views or dimensions), how it integrates with the document (which document is used?), or what the result is (e.g., page object? becomes active?). The sibling list includes many drawing tools, and the description does not help the agent understand how this tool fits into a typical workflow. Given its simplicity, the description is incomplete for effective use.

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%, meaning the description must explain the parameters. It does mention 'template: optional absolute path to a .svg template' which clarifies the template parameter beyond the schema's generic string type. However, it does not describe the 'name' parameter at all—its purpose is implicit (page name) but not stated. With two parameters and zero schema descriptions, this is a significant gap; the description only partially compensates.

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 clear action ('Create a TechDraw page') with a specific resource, and adds the default template detail ('A4 landscape template by default'). It distinguishes itself from related drawing siblings like add_projection_group or export_drawing by focusing on page creation, though it doesn't explicitly name alternatives. The purpose is clear and not a tautology.

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 provides no guidance on when to use this tool versus alternatives—for example, when to use add_projection_group or export_drawing. It does not explain prerequisites such as having an active document or a body to draw, nor exclusion cases (e.g., when a custom template is needed vs default). The only hint is the optional template parameter, but no explicit scenario is given.

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