authorize_order

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

With no annotations, the description must disclose behavior; it identifies a payment-authorization mutation and a mandatory confirmation gate, which is more than nothing. It does not explain side effects, reversibility, permissions, or what happens if the order is already authorized, so key behavioral risks remain undisclosed.

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?

Two short sentences, front-loading the action and then the key confirmation requirement, with no redundant wording. The terseness does not itself create clutter; missing details are a completeness issue rather than a conciseness problem.

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?

The tool is a financial mutation with a nested, undocumented payload and no annotations, so it needs substantial contextual explanation. The description supplies only the action and confirm=true, leaving payload shape and operational consequences unclear, even though the output schema covers return values.

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%, and the description only documents the confirm flag's required value. The required payload object—including what fields it should contain—is left entirely unexplained, so the description does not compensate for the schema's lack of parameter documentation.

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 names a specific verb ('Authorise') and object ('an order's payment'), so the tool's purpose is unambiguous. It does not explicitly differentiate from siblings such as order_authorization_state, cancel_order, or place_order, so it stops short of a 5.

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 a prerequisite for calling the tool ('Requires confirm=true'), which tells the agent a condition for a successful invocation. However, it gives no guidance on when to choose authorization over alternatives like place_order or order_authorization_state, nor any exclusions.

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