set_workbook_properties

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

The annotations only provide readOnlyHint=false, so the description carries the burden of disclosing behavior. It details partial read-only behavior with no parameters, the staleness consequence of manual calc mode, auto-backup, atomic verified save, and refusal while the workbook is open in Excel. This goes well beyond the formal annotations and gives an agent concrete expectations of side effects and safeguards.

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 efficient; every clause adds operational knowledge. It is front-loaded with the main purpose, then gives mode behavior, a warning, safety guarantees, and an error condition, all in a compact form. There is no filler or redundant wording.

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 mutation tool with no output schema and minimal annotations, the description covers the essential operation semantics, read-only reporting mode, side effects, persistence guarantees, and the open-in-Excel refusal. Missing details are limited to advanced parameter meanings (allow_loss, verify_com) and any explicit return-value description, but the overall context is sufficiently rich for an agent to select and invoke the tool correctly in most scenarios.

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?

With 0% schema description coverage, the description compensates substantially by naming the property parameters, listing calc_mode enum values, and explaining the meaning of iterative_calc, max_iter iterations, and max_change. It also ties backup to auto-backup behavior. However, some parameters like allow_loss and verify_com are not explained, and path is only implicit, so the coverage is strong but incomplete for a 15-parameter tool.

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 uses a specific verb ('Set') and clearly identifies the resource: core document properties (title, author, subject, keywords, category, comments) and calc settings. It lists exact property families and calc settings, and distinguishes this workbook-level tool from siblings like set_cell or set_formula by focusing on metadata and calculation configuration.

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 clear context for when to use the tool: when needing to change workbook properties or calc settings, and notes the read-only reporting mode when no parameters are passed. However, it does not explicitly name alternative tools or state when not to use it, relying on the purpose statement rather than direct exclusions.

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