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

The description goes well beyond the annotations. It discloses the sensitive-tier approval workflow, the first-ask card behavior ('Call it on the first clear ask; the card is the yes — do not re-ask in chat'), and the permission boundary for autonomous agents. These are critical behavioral traits not inferable from readOnlyHint=false or destructiveHint=true.

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 dense but well-structured: definition, usage triggers, permission gate, prerequisite, and a bracketed approval note. Every sentence carries important information, though the length is substantial. The front-loaded definition helps an agent quickly grasp the tool's core, while supporting details are organized in separate clauses.

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 no output schema, this description covers what, when, who, and the procedural steps (call get_attention_budget first, get approval, surface recommendation if autonomous). It does not specify success/failure return values, but that is not essential for a setter. Overall, an agent has enough to decide when and how to invoke this tool correctly.

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?

Although the schema already documents all parameters (100% coverage), the description adds semantic depth for 'max_pending_cards' — the concept of 'overloaded', the whole-number range 1–100, and the default value 7. It does not elaborate on companyId or note, but those are straightforward and already well-described in the schema. The added context justifies a score above the 3 baseline.

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 states a specific verb and resource: 'Set the founder's attention budget' and defines it as 'the maximum pending review cards before they are overloaded'. It includes the valid range and default, making the tool's action unmistakable. It also differentiates this tool from siblings like get_attention_budget by framing it as a setter for a human-gated constraint.

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?

Explicit usage conditions are given: 'Use when the founder (or a manager on their behalf) wants to raise or lower their overload threshold', with concrete example utterances. It clearly states the gate: 'an autonomous agent CANNOT change it (surface a recommendation instead); only a human-present company manager can.' It also instructs a mandatory prerequisite: 'Always call get_attention_budget first and explain why a change helps the founder.'

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