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

Beyond the annotations, the description discloses substantial behavior: it mints a short-lived widget token, opens the upload UI, returns one of three chat payloads, never expects chat attachments, never accepts base64/file bytes, and explains how fax_ids are added to conversation context. No contradictory claims against the annotations.

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 long but dense and well front-loaded with the required call order. Most sentences carry operational value, especially the mode branches and exclusions. There is some redundancy in the repeated warnings about never passing base64/file bytes and never asking for chat attachments, which could be tightened.

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 tool's complexity, seven parameters, output schema, and destructiveHint annotation, the description is remarkably complete. It covers sequencing, parameter pass-through, mode-specific behavior, side effects, follow-up actions after fax_id is known, and which sibling tools must not be called, leaving no major gaps for an agent invoking it.

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% and already documents each parameter. The description adds genuinely useful semantics beyond the schema: pipeline_id must be passed unchanged, numbers/contacts must be passed through from list results, to/from are prefill-only and should be omitted unless the user named them, and start_file_upload must always be true. This exceeds the baseline, though some information duplicates the schema.

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 name and title make the core action clear, and the description strongly implies it requests a fax file from the user via a UI widget or curl recipe. However, there is no single crisp statement like 'asks the user to upload a fax file'; instead the purpose is embedded in orchestration details and mode-specific behavior. It does distinguish itself well from siblings like send-fax-uploaded and upload-file.

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 states the required call order: pipeline_start first, then list-numbers and list-contacts, then this tool. It also gives direct exclusions: do not re-list, do not ask for sender/destination, do not call send-fax-uploaded, upload-file, or await-fax-upload. Mode-specific instructions for MCP Apps, unconfirmed, and agentic modes make selection unambiguous.

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