FleetQ

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

With empty annotations, the description carries the full burden. It successfully discloses the role requirement ('requires admin role'), which is critical authorization context. However, it fails to describe the destructive nature of team_suspend or user_revoke_sessions, potential side effects, or reversibility of these operations.

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 description is tightly structured into two efficient sentences. The action enumeration, while duplicative of the schema enum, serves as human-readable documentation. The 'Note:' prefix efficiently signals a limitation. Only minor waste exists in repeating the full action list when schema covers it.

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?

Critical gap: This multiplexed tool has incorrect schema-level required constraints (marks team_id, amount_cents, payment_intent_id, user_id as universally required when they should be action-dependent). The description fails to address this complexity—omitting which parameters apply to which actions (e.g., that payment_intent_id is only for refunds), which is essential for correct invocation given the schema flaw.

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 documents parameters well (e.g., amount_cents includes example '-1000 = €10 credit'). The description adds minimal semantic value beyond listing which actions exist. With full schema coverage, baseline 3 is appropriate, though description could clarify conditional parameter requirements.

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 clearly identifies this as 'Super admin operations' requiring an 'admin role', and enumerates the seven specific actions available (team_suspend, billing_credit, etc.). This distinguishes it from sibling tools like team_manage or user_manage. However, it doesn't explicitly contrast its scope against the other 25+ manage tools.

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?

The description lists available actions and includes a note that 'feedback tools not available in cloud', which implies when NOT to use it. However, there is no explicit guidance on when to use this vs team_manage for team operations, or which action to select for specific goals (e.g., billing_refund vs billing_credit).

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