blockrun_phone

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

Annotations declare destructiveHint=true and readOnlyHint=false; the description goes further by disclosing costs, 30-day leases, release-to-pool side effects, and the wallet-ownership requirement. It also marks which operations are free, which are paid, and what the flat call rate is.

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 well structured: a one-line summary, a compact bulleted endpoint list with pricing, and short requirement/format sections. Every line carries actionable information with no filler. The critical requirement about wallet-owned numbers 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 definition covers all main endpoints, prerequisites, costs, number format, and voice presets, which is strong for a multi-endpoint tool. However, it defers 'full body shapes' for voice/call to an external `phone` skill and leaves the semantics of `task` undefined, so an agent may need additional information to construct a fully valid voice call request.

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 only describes path generically and body as a JSON object, but the description maps specific path strings to endpoints, lists exact body key shapes, marks `from` as required for voice/call, and gives E.164 formatting. This is far more semantically useful than the schema alone.

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 precise summary: 'Phone-number intelligence, US/CA number provisioning, and outbound AI voice calls.' It then enumerates eight distinct endpoints with method, body, and purpose, making its scope and resource clear and separating it from sibling tools.

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?

Provides explicit endpoint routing under 'Common paths', states the prerequisite that voice/call 'from' must be a wallet-owned number provisioned via phone/numbers/buy, and explains when to use the free GET poll instead of a POST. This gives clear when-to-use and prerequisite guidance.

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