tv_pairShows an Allow pop-up on the Samsung TV and waits up to 30 seconds for physical remote acceptance; set force=true to discard the current token and re-pair.
Shows an "Allow" pop-up on the TV and waits up to 30 s for someone to accept it with the physical remote. Tell the user to look at the TV before calling. force=true discards the current token and pairs again.
| Name | Required | Description | Default |
|---|---|---|---|
| force | No |
Changes observed during successful MCP inspections.
v0.1.0Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Significantly exceeds the annotations: it discloses a blocking wait of up to 30 s, that acceptance requires physical human action on the remote, and that force re-pairs by discarding the existing token. It stops short of saying what is returned or what happens when the user declines or the 30 s elapses, which is the main remaining behavioral gap.
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?
Three short sentences with the core behavior first, then the user-facing instruction, then the parameter branch. No filler or repetition.
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 one-parameter, no-output-schema tool with annotations only covering safety hints, the description supplies the essential runtime characteristics (blocking, timeout, human-in-the-loop). The only omission is the failure/decline outcome, which an agent would want but can discover at call time.
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 0% for the single boolean 'force', and the description fully compensates by explaining exactly what force=true does (discards the current token and pairs again). Only the default/implicit behavior of force=false is left to inference, which is derivable.
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?
Names the concrete action (shows an 'Allow' pop-up on the TV and waits for acceptance via the physical remote), which is unmistakably pairing and distinct from every sibling (tv_status, tv_power, tv_press_keys, etc.). An agent can route this without opening the 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 an explicit prerequisite ('Tell the user to look at the TV before calling') and states the condition that selects the force path ('force=true discards the current token and pairs again'). It does not name what to do if a token already exists but pairing is unnecessary, but the when-to-use context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.