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

Beyond annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=false), the description discloses meaningful operational context: it writes flayr data, requires the write scope plus an explicit `approve` scope that admin does not include, and is limited to Agency plans. It still omits batch behavior such as atomicity or what happens to ineligible IDs, which matters for a 100-item operation.

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 sentence order is effective: scope tag first, then the action, then the crucial 'never approves' caveat and the required scope. It is dense but every clause carries information; the trailing endpoint wrapper is marginally useful but standard.

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 mutation tool with nested parameters, no output schema, and sparse annotations, the description covers important ground: permission requirements, plan gating, and the non-effect of approving or booking. It stops short of describing the return payload or error/partial-failure behavior, which are the remaining gaps.

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 50%: the nested `to` object is richly documented in the schema, while `ids` has no schema description. The description compensates by stating that the tool moves 'one or many items waiting for approval,' clarifying that `ids` are approval item identifiers and that batches are supported, though it does not mention the maxItems cap or how to select IDs.

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 gives a specific verb and resource: 'Moves the planned time of one or many items waiting for approval,' and adds that moving 'never approves and books nothing,' which implicitly separates it from decide_approval-style tools. It does not address the near-name sibling move_reviews, so an agent must infer that this tool handles approval items rather than reviews.

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?

Usage context is implied (items waiting for approval) and one exclusions statement is present ('moving never approves and books nothing'), which tells the agent not to expect a decision to be recorded. However, there is no explicit when-to-use guidance naming alternatives such as decide_approval, reschedule_post, or move_reviews, and no prerequisites beyond scope notes.

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