Record a Transaction

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

With no annotations, the description carries the full burden. It discloses that the tool will 'categorize it, calculate GST, and file it properly,' which are important behavioral side effects beyond simple recording. It also mentions that it will 'figure out if it's income or expense from the description,' providing insight into the tool's auto-detection behavior. The description does not disclose potential mutations or reversibility, but for a creation tool this is acceptable and useful context.

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 three sentences long, front-loaded with the core purpose, then instructions, then outcomes. Every sentence earns its place: the first defines the action, the second explains required inputs, and the third describes follow-up behavior and the tool's role. There is no fluff or repetition, making it appropriately sized.

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?

With 10 parameters and no output schema, the description covers the main workflow and user-facing instructions, but it omits details about what the response will look like (e.g., confirmation, transaction ID) and any prerequisites (e.g., business setup). It also does not mention optional parameters like receipt_path or has_receipt, but these are fully described in the schema. The description is complete enough for a simple record action but lacks some agent-facing operational context.

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 100%, so the baseline is 3. The description adds some meaning by grouping parameters ('what you bought/earned, from whom, how much, and when') and noting that the tool will auto-determine income vs. expense from the description, which complements the is_revenue parameter. However, it adds no detail about formats or constraints beyond what the schema already provides, and it does not clarify the relationship between is_revenue and the auto-detection claim.

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 clearly states the tool records a business expense or income, using the specific verb 'Record' and the resource 'business expense or income'. It includes a direct call to action: 'Tell me what you bought/earned, from whom, how much, and when.' While it doesn't explicitly distinguish from siblings like record_bulk_transactions, the phrase 'This is how you feed me your receipts and invoices' positions it as a primary method for individual transactions, making the purpose clear.

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 provides implicit guidance by instructing users what information to provide ('what you bought/earned, from whom, how much, and when'), which maps to key parameters. However, it does not explicitly state when to use this tool versus alternatives like record_bulk_transactions, record_receipt, or import_csv. There are no exclusions or named alternatives, so an agent might not know which tool is best for multi-transaction uploads or receipt-specific workflows.

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