textverified_create_verification

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

With no annotations, the description carries the full burden, and it does disclose the most important trait: this spends money and requires an explicit confirm_purchase=true gate. It leaves out reversibility/refund behavior, rate limits, and the role of idempotency_key in safe retries, so it is useful but incomplete for a purchase operation.

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 short sentences, front-loaded with the action and followed immediately by the safety precondition. Every sentence conveys a distinct constraint; nothing is padded.

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-value explanation is rightly omitted, and the payment/confirm behavior is covered. However, for a 6-parameter mutating purchase tool with zero annotation coverage, the unexplained idempotency_key and options fields leave real gaps.

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 description coverage is 0% across 6 parameters, so the description must compensate. It mentions service_name, capability, max_price, and confirm_purchase in prose, but 'options' (free-form object) and 'idempotency_key' get no explanation at all, leaving roughly a third of the surface undocumented.

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?

States a specific verb and resource: 'Purchase a single-use verification number for SMS or voice.' The 'single-use' qualifier implicitly separates it from textverified_create_rental, so an agent can route between them. No sibling is named explicitly, which keeps it short of a 5.

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?

Guidance is limited to the confirm_purchase gate ('only after confirming service, capability, and max price') and the test_* mock convention. It says nothing about when to prefer this tool over textverified_create_rental or textverified_get_verification, so the sibling-selection decision is left to inference.

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