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

Annotations already provide idempotentHint, openWorldHint, readOnlyHint=false.Image The description goes beyond them by disclosing permission requirements ('Requires numbers:write and billing:write') and explicitly negating two side effects ('Does not approve payment or prove activation'). These clarifications add real behavioral context beyond what annotations alone convey. Note: readOnlyHint=false is consistent with the write nature of reserving/reviewing, so no 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?

Three sentences, each carrying distinct information: core operation, prerequisite scopes, and a sibling-routing exclusion with a non-goal disclaimer. No filler and the primary action is front-loaded.

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 operation's purpose, prerequisites, and non-goals. It names the alternative (attach_number) and clarifies what the tool does not do. With four required string parameters and no output schema, the description is close to complete for invocation, though it could clarify the meaning of idempotency_key and the unique owner-only nature. Still, it's strong.

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 has 0% description coverageaging and the description does not explain what business_id, agent_id, phone_number, or idempotency_key mean in this context. 'exact pool number' hints at phone_number but doesn't map parameters to their roles or constraints. The description should explicitly connect these parameters to the operation.

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 opens with a crisp verb-object pair: 'Reserve an exact pool number and request an owner-only browser review of its recurring extra-line price.' This clearly distinguishes the action from sibling tools like attach_number or buy_number, using specific resources ('pool number', 'extra-line price') and an explicit qualifier ('owner-only').

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 gives an explicit exclusion with a direct alternative: 'Never charges included or prepaid capacity; use attach_number for included allocation.' This tells the agent when NOT to use this tool and names the sibling to use instead. It doesn't elaborate on broader conditions (e.g., when you'd need a browser review vs. direct attach), but the key decision point is covered.

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