receive_fax

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

With no annotations, the description fully explains behaviors: 24h window, caller ID matching, email delivery, optional OCR with cost and partial refund on failure, callback webhook, no refund if no fax arrives, and Bitcoin Lightning payment. No contradictions with schema.

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 several sentences long but every sentence adds value, covering use case, mechanism, optional features, and policy. It is well-structured and informative, though could be slightly more concise.

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 lack of an output schema, the description explains the outcome (fax delivered to email, optional OCR file, webhook) but does not specify the immediate return value of the tool (likely a job ID or status). It covers all key aspects for a receive tool.

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?

All 6 parameters are described in the schema (100% coverage), and the description adds significant additional meaning: explains fromNumber matching, OCR cost and failure handling, callback_url for webhook, and paymentId prerequisite. This goes well beyond 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 tool is for receiving faxes, using a specific shared number with a 24-hour window. It distinguishes itself from sibling tools like send_fax by focusing on inbound reception.

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 explicitly says when to use (expecting a fax back) and provides context like caller ID matching and email delivery. It does not explicitly exclude other use cases or recommend alternatives, but the scenario is clearly defined.

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