open_workbook

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

The description goes beyond the annotations by disclosing a key side effect: 'replaces whatever workbook the session currently holds, discarding unsaved changes.' It also provides actionable behavioral context about base64's enormous context cost, which is not captured in the annotations.

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?

Every sentence earns its place. The description is front-loaded with the primary concept, then covers alternatives, timing, and parameter selection in a compact but complete way. No filler.

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?

Given the tool's stateful behavior and optional parameter combinations, the description fully covers the essential usage context: what the tool does, when not to call it, why the current workbook is replaced, and the preferred data-passing method. No output schema is needed for this simple initialization tool.

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?

The schema description coverage is 100%, so a baseline score of 3 applies. The description additionally clarifies when to use path over xlsx_base64 and explains why, enriching parameter semantics without repeating the schema verbatim.

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 clearly states the tool's verb and resource: 'Start the workbook you will work in.' It further distinguishes its role by explaining fresh empty workbook vs loading an existing .xlsx, which is distinct from sibling tools like create_sheet or save_workbook.

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?

Explicit guidance is given for when to call ('once at the start, not between steps'), when not to call it ('you do NOT have to call it at all'), and which parameter to prefer ('Prefer path over xlsx_base64'). This is exemplary for helping an agent decide usage.

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