FPD_get_document_download

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

With no annotations provided, the description carries the full burden of behavioral disclosure and does so effectively. It explains the proxy behavior ('ALWAYS-ON PROXY (DEFAULT): Proxy server starts with MCP'), link persistence options ('True: Attempts persistent link via USPTO PFW MCP', 'False: Session-based link'), and response format requirements ('CRITICAL RESPONSE FORMAT - Always format with BOTH clickable link and raw URL'). The only minor gap is lack of explicit mention about authentication requirements or rate limits.

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 well-structured with clear sections (purpose, proxy info, workflow, response format, document types, parameters) and front-loads the core purpose. While comprehensive, some sections like the detailed workflow and response format justification could be slightly more concise. Every sentence earns its place by adding value.

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 (4 parameters, no annotations, but with output schema), the description is remarkably complete. It covers purpose, workflow integration, behavioral details (proxy, persistence), parameter semantics, response formatting requirements, and document type context. The presence of an output schema means the description doesn't need to explain return values, and it focuses appropriately on the operational context.

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?

With 0% schema description coverage, the description fully compensates by providing detailed semantic explanations for all parameters. It explains petition_id ('Petition UUID from search results'), document_identifier ('Document identifier from documentBag'), proxy_port ('Optional (defaults to FPD_PROXY_PORT env var or 8081)'), and generate_persistent_link with its two modes and implications. This goes well beyond what the bare schema provides.

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 explicitly states the tool's purpose: 'Generate browser-accessible download URL for petition documents (PDFs) via secure proxy.' This is a specific verb ('Generate') + resource ('download URL for petition documents') that clearly distinguishes it from sibling tools like Get_petition_details (which retrieves details) or FPD_get_document_content_with_mistral_ocr (which extracts content via OCR).

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 provides explicit workflow guidance: '1. fpd_get_petition_details(petition_id='uuid', include_documents=True) → get documentBag 2. fpd_get_document_download(petition_id='uuid', document_identifier='ABC123') → get download link 3. Provide download link to user.' It clearly positions this as step 2 in a sequence and distinguishes it from content extraction tools by focusing on URL generation rather than document analysis.

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