Add Worksheet

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

Annotations provide no safety hints, so the description carries the burden. It usefully discloses insertion behavior ('1-based tab position to insert before'), target scope ('open workbook'), and return shape, but it does not cover error behavior, duplicate-name handling, or whether changes persist.

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 key action is front-loaded, and the Args/Returns sections are tight and scannable. The only minor inefficiency is repeating parameter names that also appear in the schema, but since the schema lacks descriptions this repetition is justified.

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 simple three-optional-parameter mutation with no output schema or annotations, the description covers how to call it and what it returns. It is slightly short on side-effect/error context, but nothing essential for a basic call is missing.

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%, so the description must document the parameters, and it does: workbook name/path defaulting to active, name defaulting to Excel's generated name, and index as a 1-based before-position. Each parameter's meaning is fully explained beyond the bare schema.

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?

Opening sentence 'Add a new worksheet to an open workbook' uses a specific action and resource, and the sibling list contains no other add-worksheet tool, so there is no ambiguity with activate/rename/delete worksheet operations.

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 gives no guidance on when to choose this tool over alternatives or any prerequisites beyond 'open workbook'. It does not mention exclusions or conditions; the practical usage rules are left to inference from sibling names.

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