Auction documents and download links

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

Beyond the annotations (readOnlyHint, idempotentHint), the description discloses that download URLs are public and require no authentication, explains the default attachment scope, and notes that documents attached to bids are never published. This adds meaningful behavioral context without contradicting 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 well-structured with clear sections (main statement, WHEN TO USE, KEY PARAMETERS, EXAMPLES, RETURNS). Every sentence adds value; there is no redundancy or filler. It is long enough to be thorough yet remains skimmable.

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?

With no output schema, the RETURNS line fills the gap by describing the response fields. The description also explains defaults, edge cases, and the fact that bid attachments are excluded, making it self-contained for an agent to understand behavior and limitations.

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?

Even though the schema covers all parameters, the description enriches each one with operational meaning: common document_type values, the semantics of include_attachments_of ('outcome paperwork', 'withdrawal justification'), and the default of include_superseded. Two concrete examples show how to combine parameters, making the API easier to invoke correctly.

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: 'Files published for one auction, each with a direct public download URL...' This clearly identifies the tool's purpose and distinguishes it from sibling tools like get_auction, get_auction_timeline, or get_auction_results, which handle other aspects of an auction.

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 'WHEN TO USE' section lists concrete user phrases such as 'show me the documents' and 'where is the technical specification', giving clear context for when this tool is appropriate. It also hints at when to extend scope with include_attachments_of or include_superseded. However, it does not explicitly name alternative sibling tools, so it stops short of a full 5.

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