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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds genuine context beyond that — the documents are scans tied to GL entries and the returned FileID is the input to download_attachment — but it omits pagination/limit behavior and any auth requirements.

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?

Three sentences, front-loaded with the purpose, then the disambiguation, then the search/next-step guidance. The middle sentence is slightly long but each sentence carries distinct information, so there is little waste.

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?

An output schema exists, so return values needn't be explained, and annotations cover the safety profile. The description is complete enough to select and call the tool, with the only real gap being the undocumented limit and journal_id parameters.

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 carry the parameter burden. It names 'date range, memo, or amount' (covering start_date/end_date, memo, amount) but says nothing about limit or journal_id, leaving two of six parameters undocumented anywhere. Partial compensation only.

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 ('List') and resource ('invoice/receipt scans attached to JOURNAL (GL) entries'), and explicitly distinguishes itself from the sibling attachment tools by noting the documentation is 'out of reach of the bill, check, and card tools.' An agent can tell it apart from get_check_attachments and get_credit_card_attachments without opening any schema.

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?

Names the scenario that selects this tool (charges posted straight to the GL, including credit card purchases entered as journal entries rather than card transactions) and the alternative attachment tools it is not. It also gives the follow-up path: 'pass a FileID to download_attachment to read the document.' When-to-use and the next step are both explicit.

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