save_mapping_profile

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

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false and openWorldHint=false, but the description adds real value on top: it explains that the call persists a reusable profile and that human sign-off is required first. The notable remaining gap is what happens on a name collision — whether an existing profile is overwritten or a new version created — which matters given idempotentHint=true.

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 purpose and the consent gate are front-loaded in the first two sentences, then the per-argument lines follow. With zero schema coverage every line is carrying information that would otherwise be missing, so nothing is padding.

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?

An output schema exists, so return values need not be described, and the description covers the remaining obligations: purpose, prerequisite ordering, and the meaning of all eight parameters including the nested maps. For a persistence tool with nested objects, this is sufficient to call it correctly on the first try.

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 carries the full burden, and it does: all eight parameters get concrete meaning and an example. It pins down the closed set for `target` (orders, psp_transactions, bank_settlements, disputes), disambiguates `amount_unit` with sample values (24.99 vs 2499), and clarifies the direction of the `columns` mapping ('Our field -> their column header'), which the bare object schema would not convey.

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 — saving a CSV-to-field mapping profile — plus the payoff ('the same export imports with no mapping step next time'). That framing distinguishes it cleanly from import_transactions (which moves data) and preview_import (which shows a mapping without persisting it).

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?

It states an explicit precondition — 'Only call after the person agrees with the mapping shown by preview_import' — which names both the gating sibling and the human-consent condition. An agent knows exactly what must happen before this call and which tool precedes it, leaving little to infer.

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