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

The description mentions the welcome_email side effect but does not address the destructive implications indicated by the destructiveHint annotation. The statement 'Updating an existing client's profile is not supported' actually conflicts with the annotation that suggests destructive behavior. Important side effects like possible Stripe customer creation or other modifications are not disclosed, leaving the agent underinformed about the tool's behavior.

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 brief and front-loaded with the main action, making it easy to scan. It contains only two sentences, which is appropriate for a simple tool. However, the inclusion of contradictory statements adds noise, slightly reducing clarity but not affecting structure.

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 complexity of the schema (17 parameters, nested objects), the description is quite sparse. It does not cover parameter relationships beyond a couple of mentions, and the output schema is absent. While the schema descriptions are rich, the tool description leaves gaps about use cases, edge cases, and side effects, making it only partially complete for a tool of this complexity.

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 provides high coverage, but the description adds contradictory parameter guidance. It states 'Requires email' even though email is not in the schema's required list, and mentions client_id as 'Required when updating an existing record' while simultaneously saying updating is not supported. These inconsistencies undermine understanding of parameters despite the schema descriptions.

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 primary purpose: 'Create a client account.' It also explicitly distinguishes from update operations by saying 'Updating an existing client's profile is not supported by this tool,' which helps separate it from other write tools. The verb and resource are specific and unambiguous.

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 implies when to use it (for creating a client) and explicitly says it is not for updating. However, it does not mention alternative tools (e.g., client-read for reading) or other scenarios where another write tool would be more appropriate. It gives partial guidance but not fully explicit context around alternatives.

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