concur_update_expense

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

Annotations only say this is a non-read-only, non-destructive, open-world write. The description adds substantial behavior beyond that: it sends only changed fields, a new currency or date re-fetches Concur's exchange rate, the response reflects the expense as Concur shows it including exceptions, and the confirm/confirmToken flow with MCP_CONFIRM_MODE is spelled out. It even includes a prompt-injection guardrail, which is rare and valuable for a mutation tool.

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?

Front-loaded with the verb, scope and editable surface, then moves to side effects, return value, and confirmation mechanics in a logical order. It is dense and long, but nearly every clause carries operational information; only the injection-warning sentence runs a bit long relative to its payload.

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 14-parameter mutation with a nested free-form fields object and no output schema, the definition covers what changes, what side effects occur, what the response looks like, and how confirmation gates the write. Nothing an agent needs in order to call this safely 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 prose still adds meaning where it matters — exchangeRate defaults to Concur's own rate for the transaction date, businessPurpose is a dropdown item text when a required field exists, and fields accepts labels plus id, with value-type rules (list item text/code, checkbox "true"/"false", date format). Minor gap: the interaction between amount/currency/exchangeRate is described but not fully worked through as an example.

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 and resource ("Change an expense") scoped to "an unsubmitted SAP Concur report" and enumerates exactly which attributes can be changed. It also explicitly carves out the adjacent case ("To change the expense TYPE, delete it and create a new one"), which separates it from concur_delete_expenses and concur_create_expense.

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?

Gives explicit when-to-use (edit fields on an unsubmitted report), when-not-to (changing type requires delete + create), and the mandatory confirmation workflow with the two-step fallback. The dependency on prerequisites (expenseId from concur_get_report, locationId from concur_search_locations in the schema) is clear enough that an agent can route correctly.

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