create_verification

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

No annotations exist, so the description carries full behavioral burden. It thoroughly discloses branch behavior: LIVE vs pk_test_ telegram_bot behavior, challenge presence, no qr_text, deep_link on messenger channels, OTP code flow, and the Proof API key prerequisite. This goes well beyond a simple 'create' statement.

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 dense but information-rich, with the core purpose front-loaded and all major behavioral branches covered. It is somewhat long and would benefit from bullet structure, but every sentence contributes meaningful usage or behavior context rather than padding.

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?

For a complex tool with 9 parameters, no output schema, and no annotations, the description is unusually complete: it explains response shape, channel-specific flows, tracking next steps, rendering links, and the API key access prerequisite. An agent has enough context to call it correctly and follow up appropriately.

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, but the description adds substantial meaning beyond the schema: concrete type/channel/identifier examples, the interaction between telegram_bot and test keys, what challenge objects convey, and which response fields are absent. This materially improves parameter selection and interpretation.

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 specific verb and resource: 'Create a new identity verification' and immediately clarifies it initiates a verification flow for an asset identifier. It provides concrete example inputs and explicitly routes deep-link handling to render_auth_link, distinguishing its role from that sibling and from start_login.

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 explicit agent-facing usage guidance: pass type, channel, and identifier, with concrete examples. It also states when to use alternatives — pass deep_link to render_auth_link, poll get_verification or use wait_for_verification for OTP flows — and warns that start_login does NOT open this tool.

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