quick_add_expense

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

With no annotations, the description carries full behavioral burden. It discloses automatic participant resolution, equal-split default, payer-inclusion behavior, the custom owed_shares sum constraint, fuzzy category matching, currency defaulting, and the return value ('who owes what'). This is rich transparency, though it omits edge-case behavior like unresolvable participants or failure modes.

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 a dense but well-organized paragraph. It front-loads the core purpose and then efficiently covers the most important configurable behaviors. Each sentence earns its place; there is no filler. It is a bit long, but justified by the need to document 11 parameters without schema aid.

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?

Given 11 parameters, no output schema, and no annotations, the description is notably complete. It covers participant resolution, splitting defaults, custom shares, category handling, currency defaulting, and return shape. Minor gaps remain (e.g., what happens when participant resolution fails, group_id semantics, cost string format), but the core usage is well covered.

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 compensate, and it does. It explains the flexible formats for participants (names, partial names, emails, IDs), the meaning of include_payer_in_split, the required sum constraint for owed_shares, and the fuzzy-matching behavior of category_name. Some parameters like cost format and group_id semantics are left to inference, but the description adds substantial meaning to the most nuanced parameters.

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 identifies the action ('expense creation') and the resource ('expense'), with a distinctive angle: 'Agent-friendly expense creation from messy input.' This differentiates it from the sibling tools, which are auth-related (setup_auth, get_auth_status, logout), discovery (search_tools, resolve_users), or summary (money_summary). The purpose is unambiguous and specific.

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 implies its usage by highlighting 'messy input' and automatic resolution, suggesting it is the go-to tool for flexible or unnormalized participant input. However, it never explicitly contrasts with alternatives or states when not to use it. It provides parameter-level guidance (e.g., include_payer_in_split=false when the payer did not consume) but no tool-selection guidance.

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