create_account_shell_customization_draft

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

The description discloses important behavioral details: the draft is immutable, the tool cannot publish or roll back, tenant authority and lifecycle fields are server-owned (so the caller should not supply them), and base_revision_id is sent as an explicit null when empty. These facts inform the agent about side effects and constraints, compensating for the lack of 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?

The description is somewhat verbose and repetitive (e.g., 'exact' appears multiple times, and the same ideas about component_version and props are stated across sentences). While the purpose is front-loaded, the redundancy and jargon-heavy phrasing could be streamlined without losing critical information.

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 description covers the tool's purpose, key constraints, and some parameter semantics, but it does not describe the expected output or response format (though an output schema exists). It also lacks a concrete example of a valid 'document'. Given the complexity of the account-shell domain, an agent might struggle to use the tool correctly without additional context from the get/preview siblings or external documentation.

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 description adds semantic meaning to the parameters: for 'document', it clarifies it must be an 'exact bounded account-shell token object' and provides details about component_version, props.action, props.visibility.page_scope, and what is not allowed (routes, code, URLs, scripts, event handlers). For 'base_revision_id', it explains when to use an empty string. However, the document format is still vague and not fully specified, so the agent may need additional domain knowledge to construct a valid value.

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 action ('Create a governed account-shell draft') and the resource (account-shell draft). It also distinguishes the tool from siblings like get_account_shell_customization and preview_account_shell_customization by explicitly noting it only creates an immutable draft and cannot publish or roll back. The verb and resource are specific enough for an agent to understand the primary intent.

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 some usage guidance, such as when to use an empty base_revision_id ('only when the tenant has no current revision') and preferences for component_version and props fields. However, it does not explicitly state when to choose this tool over the sibling get or preview tools, leaving the agent to infer that 'create' implies a creation action. More explicit differentiation from siblings would improve the score.

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