direct_write

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

The description asserts the write is 'non-destructive', while the annotations declare destructiveHint: true. That is a direct, safety-relevant conflict: an agent could reasonably believe an irreversible mutation is impossible. Although the description does add useful context (server write flag, audit log, unit spend, user confirmation), the contradiction on the destructive axis is exactly what the rubric penalizes at 1.

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?

Three front-loaded sentences: what it is, where it sits (write flag/audit log), which alternatives to prefer, and the confirmation caution. Dense but every clause carries weight, and the constraints come before the routing advice. Minor deduction for parenthetical nesting that makes the first sentence harder to parse.

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 no explanation, and the description does cover the operational envelope (write flag, audit log, unit cost). However, for a tool whose entire behavior is determined by arbitrary service/method/items, the parameter space is entirely undocumented, and the 'non-destructive' claim leaves the actual blast radius of a call ambiguous alongside destructiveHint: true.

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% across 4 parameters (service, method, items, idempotency_key) and the description adds nothing about any of them. For a generic pass-through write, the agent gets no guidance on valid service/method values, the shape of items, or how idempotency_key should be used. The description must compensate for the zero-coverage schema here and does not.

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?

Names a verb (write) and a resource (Direct), and explicitly carves its scope against siblings: no deletes or bid changes (direct_prepare_write), campaign changes preferred via direct_prepare_changes -> direct_apply_changes. What it does not clarify is that it is essentially a pass-through write taking arbitrary service/method/items, so 'Direct write' remains somewhat abstract. The sibling differentiation is genuinely strong, hence a 4 rather than 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?

Gives explicit alternatives with the conditions that select them: direct_prepare_write for deletes/bid changes, and the prepare→apply pair for campaign changes. It also adds a procedural guardrail ('confirm with the user first'), which is exactly the kind of usage instruction an agent needs before a write. Nothing about routing is left to inference.

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