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

Annotations indicate readOnlyHint=false and idempotentHint=true. The description adds context beyond these: it states that hiding/showing is a display preference, that workspace scope affects all members and requires admin, and that hidden:false works even while hidden. This fully discloses side effects and permissions, complementing the annotations without contradiction.

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 three sentences, front-loaded with the primary action and scope. Every sentence adds value: the first states the action, the second clarifies non-effects, and the third covers scoping, roles, and reversal. No fluff or repetition.

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?

The tool has four parameters, one required, and an output schema. The description covers all necessary operational details: how to hide/show, scope semantics, role requirements, and that it is non-destructive to drafts. Combined with annotations and schema, an agent has everything needed to invoke it correctly without further clarification.

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 100%, so the baseline is 3. The description adds meaning by explaining the scope enum ('inbox' vs 'workspace') and the hidden parameter (defaults to true, pass false to show again). However, it does not elaborate on the distinction between inbox and inbox_id, though the schema descriptions already cover those. Overall, it enhances understanding beyond the 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?

The description clearly states the tool's function: 'Turn OFF the in-chat draft editor card, either for one inbox or for the whole workspace.' It specifies a precise verb and resource, distinguishes it from sibling tools by noting it is a display preference only, and clarifies it does not affect drafts or sending. This is unambiguous and easily distinguishable.

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 provides explicit guidance on when to use the tool and its effects, including scope options ('inbox' vs 'workspace'), the role requirement for workspace scope (owner/admin), and how to reverse the action (hidden:false). It also notes that drafts and sending are unaffected, so agents know not to use this for those purposes. This is comprehensive.

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