Workbooks Share Workbook Cross Org

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

Annotations declare a non-read-only, open-world, non-destructive operation, and the description usefully adds side-effect detail the annotations do not carry: it can copy input table data and send an email with a custom message. That is real added value, but it omits what the sharing actually confers (access level), whether it is reversible, or what permissions the caller needs for cross-org sharing.

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?

Two short sentences, purpose first and payload second, with essentially no filler. The line-broken field list is slightly ragged but still scannable and earns its space.

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?

An output schema exists, so return values need not be described, and the description covers both top-level parameters plus the body's key fields. For a cross-org mutation tool with a fully undocumented nested body, though, it should say more about what gets shared and what access is granted before calling.

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% and the body is an open object with additionalProperties, so the description carries the full burden. It does name the required orgSlugs and the four optional fields, which is far better than the schema alone. But it gives no type, format, or meaning for those fields (e.g. what shareDatasets includes, or the expected slug shape), so the compensation is only partial.

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 gives a specific verb and resource ('Share a workbook') plus a scope qualifier ('with other Sigma organizations') that separates it from the many internal-sharing siblings such as workbooks_grant_workbook_access and workbooks_copy_workbook_to_member. It never names those alternatives explicitly, so differentiation is implied by scope rather than stated.

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 cross-org scope hints at when this tool applies rather than an in-org grant, but there is no explicit when-to-use/when-not statement, no prerequisites, and no pointer to the sibling tools that handle internal sharing. Usage must be inferred from the phrase 'other Sigma organizations'.

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