gage_pair_start

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 return payload, that nothing is written yet, that the human verification happens out-of-band in the Gage app, and that the confirm step leaves the key 'unconfirmed.' It does not cover failure modes (invalid key/handle, expired pairing_id) or what happens if the human rejects the match, which keeps it from 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?

Front-loaded with the action and the critical 'adds NOTHING yet' caveat, then proceeds through the human handoff and the follow-up call. Dense with no filler, though the middle clause about the words-match button and banner is slightly long-winded for the value it adds.

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?

No output schema exists, and the description compensates by naming the return values (pairing_id plus four word-pairs) and explaining what to do with them. Combined with the next-step routing to gage_pair_confirm, an agent has everything needed to invoke this correctly in the flow.

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 baseline would be 3, but the description adds real meaning: `key` is explained as the person's `gage whoami` token in the context of the pairing flow, and `handle` is reframed as 'a machine announcing on this network' rather than just a label. The 'pass X or Y' phrasing also implicitly conveys the either/or choice that the schema (zero required params) leaves ambiguous.

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?

States a specific action ('Begin adding someone to the buddy list') and immediately clarifies its scope: it returns a pairing_id and four word-pairs but 'adds NOTHING yet.' That non-mutation statement cleanly separates it from gage_pair_confirm, which actually puts the key on the list.

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 an explicit end-to-end sequence: show pairs and name to a human, let the comparison happen in the Gage app, then call gage_pair_confirm with the pairs exactly as returned. It also names an exclusion ('do not ask the human to read pairs back to you'), so the agent knows what not to do as well as what to do.

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