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

With no annotations, the description carries the full burden and does well: it discloses the 10/hour rate limit, the macOS/Caddie-open requirement, and non-obvious callback behavior (a tapped button returns to the running agent task as the user's reply, otherwise the tap is inert). It doesn't say what happens when the rate limit is hit or what a call returns, so not a 5.

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?

It leads with the action, then constraints, then button semantics, so it is front-loaded and every clause carries information. The nested parentheticals ('as you (your agent's name and face when you're one of their Caddie agents)') make it denser than it needs to be, costing the top score.

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 three-parameter, no-output-schema notification tool with no annotations, the description covers purpose, rate limit, platform prerequisite, and button reply behavior — enough to call it correctly. The main omission is failure/return behavior (what happens when rate-limited or when Caddie is closed).

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 100%, so the schema already documents all three parameters and the baseline is 3. The description adds real semantic value for 'buttons' by explaining what tapping does downstream (label becomes the task reply) and what happens when not in an agent task, which is meaning the schema does not convey.

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 surface: 'Show the user a short line in Caddie's notch on their Mac (and the Planner's thread).' That's concrete and distinguishable from messaging siblings like slack_send or phone_ask. It doesn't explicitly name those alternatives, which keeps it from a 5, but the core action is unmistakable.

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?

'For something they should see now, not for every update' is an explicit when-to-use and when-not-to-use rule, reinforced by a hard rate limit (at most 10 an hour across all callers) and the prerequisite 'Needs Caddie open on the Mac.' It stops short of routing the agent to specific alternatives (slack_send, agent_reply, phone_ask), so 4 rather than 5.

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