upload_workbook

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

No annotations are provided, so the description carries the full burden. It discloses the key side effect (publishing/storing to Tableau Cloud), the state-change semantics (overwrite existing workbook with same name), and credential sourcing behavior (env_path takes priority over process env vars). This is rich behavioral context beyond structured data.

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?

Well front-loaded with the core purpose first, then routing guidance, then Args and Returns. It is somewhat long, but every section (guidelines, args, returns) earns its place given the 0% schema coverage and no annotations. Slightly verbose but appropriately structured.

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 annotations, 0% schema coverage, and no output schema, the description provides everything: publishing side effect, credential handling, parameter docs, and even the return shape. Nothing an agent needs to call this correctly 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 compensate fully. It documents all 5 parameters with meaning: twb_path format (.twb/.twbx), data_path acceptable file types, name default (filename stem), overwrite behavior, and env_path precedence over environment variables. This fully compensates for the schema gap.

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?

States a specific verb+resource ('Publish a .twb/.twbx to Tableau Cloud') with explicit outcome ('for openability or screenshots'). It directly distinguishes itself from validate_workbook_api, a sibling tool, by naming the exact conditions under which each is preferred.

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?

Provides explicit when-to-use guidance: 'Prefer validate_workbook_api ... because it does not publish or store the workbook' followed by the exact conditions selecting upload_workbook (published workbook_id, visual screenshot, TWBX packaging validation, publish/openability evidence). This is precisely the when/when-not/alternative structure.

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