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

Annotations only say readOnlyHint=false, destructiveHint=false, leaving the description to carry the behavioral burden. It does so thoroughly: explains the risk of base64 mutation and truncation, that nothing is ingested yet, and that received_file_hash is the only reliable check. It even discloses that a corrupted file can appear plausible. This far exceeds minimal expectations.

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 tightly packed with critical guidance. It opens with the core purpose, then flows through exclusions, size advisory, hash verification, and next steps. Every sentence adds operational value; none are filler. The structure mirrors the decision order an agent would follow.

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?

Despite having no output schema, the description fully explains what the tool returns (upload session with detected columns and mapping suggestions) and the required follow-up (verify hash, review mapping, call confirm_column_mapping). It covers all parameters, failure modes, and the alternative path. Nothing an agent needs to call it correctly is missing.

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%, so the baseline is 3. The description adds value beyond schema by explaining when to set source ('tally_file' for Tally exports), why format should be left unset, and that client_id comes from list_clients. It reinforces that file_base64 must be raw bytes encoded as base64. This extra context justifies a 4.

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 (stage), resource (Trial Balance spreadsheet), format (xlsx/csv), size limit (max 4 MB), and method (inlining base64). It clearly distinguishes itself from the sibling create_upload_link, so an agent cannot mistake which tool to use.

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?

Explicitly reserves this tool for programmatic callers holding the file on disk, and outright forbids its use for human-supplied files, naming create_upload_link as the alternative. It also gives a concrete size threshold (prefer create_upload_link above ~10 KB) with a rationale, so usage conditions are unambiguous.

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