download_documents

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

The description adds useful behavioral context beyond annotations: it writes files to a specific directory, states the default path, and explicitly says existing files are kept. This complements the idempotentHint and non-destructive annotation without contradicting them.

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?

Two sentences with no filler. The core action and destination come first, and the key conditional behavior is stated efficiently. Every sentence earns its place.

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 tool has no output schema and four parameters with zero documented semantics. The description covers the core save behavior but leaves unclear what the tool returns, how each filter parameter works, and how saved files are named or organized. This is incomplete for confident parameter selection.

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 description coverage is 0%, so the description must explain parameters. It only clarifies document_ids behavior; source, since_days, and title_contains are left unexplained. An agent would not know how these filters affect which documents are downloaded.

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?

Clearly states the action (save), resource (documents), output format (PDF), and destination (local folder TR_DOCUMENTS_DIR). It does not explicitly name a sibling for differentiation, but the PDF-saving action makes it easy to distinguish from list_documents and other read-only 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 conditional guidance: without document_ids, all documents matching filters are saved. This helps an agent decide how to invoke it, but it does not say when to prefer this tool over alternatives or explain what 'matching filters' means for each parameter.

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