tealfabric_download_document

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

With no annotations, the description carries the full burden; it does disclose the return encoding (base64) and that the transfer is binary-safe, which is real behavioral value. It is silent on permissions/auth scope, size limits, and what happens when the path doesn't exist – notable gaps for a read of arbitrary storage paths.

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 short sentences, zero waste, with the return-format detail front-loaded immediately after the action. Nothing to trim.

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?

There is no output schema, so the base64 note usefully covers the return value, and only one required parameter keeps the surface small. However, for a storage-fetch tool it omits error behavior (missing file, permission denied) and whether paths are tenant-relative, leaving an agent without expectations for failure cases.

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 the file_path example ('packages/report-v1.zip') already establishes the path format, so the schema does the heavy lifting. The description adds no further semantics about path resolution or the ignored tenant_id, so baseline 3 applies.

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?

States a specific verb and resource ('Download a document/file from Tealfabric documents storage') and adds the return encoding. It doesn't explicitly distinguish itself from the closest siblings tealfabric_read_document_text or tealfabric_upload_document, so an agent must infer that this is the binary counterpart to the text reader.

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?

Usage is implied by 'document/file' and 'base64 for binary-safe transfer', which hints at binaries rather than text, but there is no explicit when-to-use or 'use read_document_text for plain text instead' routing statement despite that sibling existing.

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