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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the risk profile is known; the description adds meaningful behavior by revealing that some actions are reversible/voiding (undo, time.invoice_void, withdraw). It does not disclose authority/permission requirements (despite the 'authority?' params), failure behavior, or what state changes are irreversible, leaving real gaps for a destructive dispatcher.

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?

Purpose is front-loaded in one short sentence, followed by invocation instruction and a compact action catalog with zero filler. The telegraphic style ('query actions says what each does') is slightly awkward but costs little space given how much it conveys.

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 no-output-schema, destructive, polymorphic dispatcher, the description covers the action vocabulary and parameter shape adequately, and it delegates detailed semantics to the query tool. It is still thin on prerequisites, authorization expectations, and result behavior for a tool whose actions mutate shared state.

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 only 33% and the 'action' field has no enum, so the description carries most of the weight — and it does, enumerating the valid action values with their per-action parameter names and optionality markers (holder?, reason?, authority?, within, changeset). That is substantial meaning added beyond the schema, though the free-form 'params' object has no type or format detail.

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 pairs a broad verb phrase ('Change, correct or undo what is on the map') with a concrete catalog of the six actions it exposes (release, withdraw, publish, publish_all, undo, time.invoice_void), so an agent knows this is the generic mutation dispatcher. It stops short of distinguishing itself from closely-named siblings like 'change' and 'undo', which overlap directly with the stated purpose.

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?

'Call with the action and its params' plus the pointer to 'query actions' for per-action semantics gives useful invocation guidance, including discovery routing. However, it never says when to pick this tool over siblings such as change, undo, assign, or settle, nor whether actions require preconditions or confirmation.

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