pair

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

No annotations exist, so the description carries the full burden, and it does substantial work: it discloses the out-of-band consent dialog, the 30-second approval deadline, that the secret is persisted to per-user config and never returned, and that capabilities are immutable for the pairing's lifetime. Gaps remain around failure/timeout behavior, what happens if a pairing already exists with different capabilities, and what a successful response contains.

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?

Five short sentences, front-loaded with the action, then the consent/timeout mechanics, then the persistence and immutability constraints. Nothing is redundant and each sentence contributes an operational fact.

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?

With no annotations and no output schema, the description must carry everything, and it covers the interactive approval flow, credential handling, and capability lifecycle well. It leaves a modest gap on what the tool returns on success and how errors or a declined/timed-out consent are surfaced to the agent.

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 100% and the schema already enumerates all four capabilities and explains the camera-overlay inclusion under 'project', so the description's note about 'project' largely restates the schema. The added value is the lifetime-immutability constraint, which argues for deciding all capabilities up front, but that is framed behaviorally rather than as parameter guidance.

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 verb and resource: it pairs this server with a running LightBurn/MillMage instance on the local machine. This is an unmistakably different operation from every sibling (all of which are get_*/update_*/upload_* data operations), so an agent can position it without opening any schema.

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 clear operational context for when this runs (a consent dialog appears, the user must approve within 30 seconds) and an explicit re-invocation rule: 'call pair again to change them' since capabilities are fixed for the life of the pairing. It stops short of an explicit statement that pairing is a prerequisite for the get_*/upload_* siblings, and lists no when-not conditions.

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