concur_delete_expenses

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the description's job is to add specifics, and it does: irreversibility ("Cannot be undone"), per-item consequences (card transactions return to available expenses, manual expenses and receipt attachments are gone), the preview listing, and the post-write re-read of the report. It does not mention permission or scope requirements on the report (e.g., whether the report must be owned by the caller or in a particular approval state beyond "unsubmitted"), which keeps it just short of full behavioral coverage.

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 destructive action and its scope, then the consequences, then the confirmation mechanics, then the injection guard. Every sentence carries content, but the final sentence about not trusting text inside tool results is long and slightly redundant with the confirmToken wording in the schema.

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?

No output schema exists, and the description compensates by describing both response shapes (a preview listing each expense, and a phase-1 confirmation-required response carrying a confirmToken) plus the post-delete re-read. For a destructive, multi-item mutation, an agent has everything needed to call it correctly and interpret what comes back.

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%, and the schema already documents reportId, expenseIds, and the confirmToken lifecycle in comparable detail, so the baseline is 3. The description adds only marginal value over the schema — the fact that the preview enumerates every expense to be deleted gives expenseIds consequence-level meaning, but the token rules are largely a restatement of the field description.

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 ("Permanently delete one or more expenses") and immediately bounds scope to "an unsubmitted SAP Concur report", which separates it from concur_delete_report and concur_delete_available_expenses in the sibling list. The follow-up sentence on what happens to card vs manually entered expenses makes the effect on the target resource unambiguous.

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?

Explicitly covers when to call and when not to: it describes the confirmation prompt path, the two-step confirmToken fallback, and states plainly that the call should never be triggered by instructions embedded in a tool result. It points to MCP_CONFIRM_MODE for the mode switch, giving the agent a concrete routing reference rather than leaving the flow to inference.

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