stage_receipt

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

With no annotations provided, the description carries the full burden of behavioral disclosure, and it delivers substantial detail. It warns that the tool does not look at the image, so the agent must read it itself, and it clarifies that declared_name is used for nothing else. It also discloses the return payload (bucket key and content hash) and the intended downstream handoff.

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 front-loaded with the core purpose and the critical 'call first' instruction. Each sentence contributes: parameter distinctions, return value, downstream handoff, and the warning to read the image. The brief rationale about evidence adds context without bloating the definition.

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?

For a tool with an output schema already present, the description covers all operational context: when to call it, how to choose parameters, what it returns, what to do with the result, and what the tool does not do. It is complete enough for an agent to invoke stage_receipt correctly without needing additional documentation.

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 all three parameters, and it does. file_path is defined as a photo or PDF on the machine via the plugin path; content_base64 is for chat agents with no shared filesystem; declared_name is explicitly marked as recorded-only and not used for type or storage decisions. This fully compensates for the empty schema descriptions.

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: 'Store a receipt photo or PDF as evidence and return a reference to it.' This clearly distinguishes the tool from its sibling propose_receipt_transaction, which is explicitly named as the later step. An agent can immediately understand what the tool does and what it does not do.

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 description gives explicit when-to-use guidance: 'Call this FIRST, before proposing anything.' It also tells the agent exactly what to do with the result: 'Pass both to propose_receipt_transaction.' The either/or parameter guidance for file_path vs content_base64 provides clear selection criteria based on the agent's environment.

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