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

Goes well beyond the readOnly/idempotent annotations: it discloses that the Desk only drafts while the captain sends from their own phone or email, forbids the agent from sending or reading a teammate's contact details, and states the Desk Pass requirement per member per week. Those are exactly the constraints an agent cannot infer from annotations and would otherwise violate.

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?

Purpose is front-loaded in the first sentence and the operational constraints follow in a logical order. Some sentences are densely packed and the Desk Pass/pricing sentence sits awkwardly mid-paragraph, but nothing is redundant.

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 10-parameter tool with no output schema, the description covers the output (the list of unanswered players plus one drafted group message with deadline and grid link), the input shape, the deadline default, and the send/no-send boundary. An agent has everything needed to call it correctly and to avoid acting on the result itself.

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 every parameter is already documented, and the description largely restates it ('each match column's header, and each player's row with one cell per column'). It adds no format examples, ordering rules, or guidance on when to supply the many optional fields such as asked, signAs, matchId, or lineupNow beyond what the schema says.

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?

Opens with a specific verb and resource: finds the players who have not answered the next match on the USTA NorCal availability grid, and adds that it also lists blank/maybe answers and drafts one group message. An agent can tell what it produces. It does not, however, distinguish itself from the closely named sibling plan_lineup_from_availability, which a reader would reasonably guess overlaps with this.

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?

'Call it when a captain asks who has not answered on NorCal, or wants reminder texts' gives a concrete triggering condition, and the input guidance ('pass the team and the grid as your agent read it') states a prerequisite. Missing is any explicit exclusion against plan_lineup_from_availability or plan_lineup, which is the main routing ambiguity here.

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