Yo

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

Annotations only indicate readOnlyHint=false, which signals mutability. The description adds crucial behavioral context: the tool revokes the API key for already-approved pairings, works both pending and after approval, and has a specific time window. This goes well beyond what annotations provide, making the side effects and constraints explicit.

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?

The description is concise, consisting of three sentences that each carry essential information. It front-loads the primary purpose, then adds timing and alternative guidance, and finally suggests the follow-up action, all without redundancy or unnecessary filler.

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?

Despite having no output schema, the description fully covers the operational scope: what the tool does, when it is usable, what happens after use (API key stops working), and what to do next. The sibling tools and parameter schema provide enough context to invoke correctly without additional clarification.

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?

The input schema already provides complete descriptions for both parameters (claim_token and pairing_code) with 100% coverage. The description does not add additional parameter-level detail, but the schema fully documents them, so a baseline score of 3 is appropriate.

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 opens with a specific verb and resource: 'Abort a pairing you started with register_agent.' It clearly distinguishes the tool from the sibling revoke_self by explicitly naming the alternative, ensuring an agent understands which operation this tool performs.

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?

The description provides explicit usage guidance, including when the tool is valid ('Available until the pairing expires, and for 15 minutes after you pick up the API key') and when to use an alternative ('later than that, use revoke_self'). It also instructs to call register_agent again afterward, giving complete context for proper usage.

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

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

It discloses critical, non-obvious behavior: the api_key appears exactly once, must be stored immediately, paired_with identifies the connected account, and the user must be shown that account. This goes well beyond the minimal annotations (readOnlyHint false).

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?

Two sentences: the first states purpose, the second immediately highlights the critical response handling. No filler or redundant restatement of schema fields.

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 output schema, the description covers the essential return values (api_key, paired_with) and required user action. It doesn't describe pending states or error scenarios, but for a small polling tool it is largely self-contained.

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?

Both parameters already have full descriptions in the schema, so the description adds little beyond naming pairing_code as coming from register_agent. It doesn't explain claim_token in its own words or add any new parameter-level semantics.

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?

Description opens with a specific verb and resource: 'Check the status of a pairing code from register_agent.' This clearly distinguishes it from siblings like cancel_registration or register_agent by indicating a polling/read step in the registration flow.

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?

The description gives clear usage context: poll after register_agent, with a specific behavior on the first poll after approval. It does not explicitly list exclusions or alternatives, but the intended workflow is evident.

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

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

The description adds meaningful behavioral context beyond the sparse annotations (readOnlyHint=false, openWorldHint=false). It discloses the return type, the user approval flow, and the need for polling asynchronously. This adequately informs the agent about the tool's operational characteristics, though it doesn't cover edge cases like duplicate registrations.

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?

The description is a single sentence that is front-loaded with the primary purpose and flows logically to the return value and next steps. Every clause contributes necessary information without redundancy, making it appropriately concise.

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?

Given the simple tool (no output schema, all parameters documented, no nested objects), the description fully conveys the expected flow: register, receive pairing info, user approval, then poll a sibling tool. This is complete for an agent to invoke the tool correctly.

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?

The input schema has 100% coverage with clear descriptions for all three parameters (platform, description, proposed_name), including examples. The description adds no additional parameter explanation, so it meets the baseline for schema-heavy contexts without going beyond.

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 clearly states the action ('Register this agent with Yo'), the resource (agent with Yo), and the unauthenticated nature. It also distinguishes itself from sibling tools by describing the return value (pairing URL and code) and the follow-up step (poll check_registration), making it clear this is the initial registration step.

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?

The description provides a clear usage context: use this to start registration, then poll check_registration for the API key. It explicitly mentions the alternative/sequel tool, which helps an agent decide when to use it. However, it doesn't mention when not to use it (e.g., if already registered), so it misses explicit exclusions.

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

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

The description discloses that revocation is permanent, immediate, and makes the key stop working. While annotations only indicate readOnlyHint=false, the description goes further by explaining the irreversible effect and the auth mechanism (API key as Bearer token), adding significant value beyond annotations.

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 concise sentences, each adding necessary information: the action, the condition to use it, and the consequence/next step. No filler or redundant wording.

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 simple tool with one param and no output schema, the description covers the purpose, usage condition, effect, and recovery path. It lacks only minor details like return value or error cases, but these are not critical given the tool's simplicity.

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% and the single parameter (confirm) is fully described in the schema itself. The tool description does not add additional parameter semantics, but does not need to because the schema already provides complete meaning.

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 uses the specific verb 'revoke' and identifies the resource as 'THIS agent', clearly distinguishing it from sibling tools like cancel_registration. It also explicitly contrasts with cancel_registration, making its unique purpose 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?

Explicitly states when to use: 'when you discover ... that paired_with is not your owner's account and cancel_registration no longer works.' It also provides an alternative next step ('call register_agent to start over'), giving clear directional guidance.

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

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

The description adds important behavioral context beyond annotations: requires an agent API key as Bearer token, specifies the notification is content-free, and explains the tap-through behavior of context_url. Annotations only indicate readOnlyHint:false which aligns with the write nature; no contradiction.

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?

Two sentences, front-loaded with the primary purpose, followed by essential auth and optional parameter details. Every word is useful; no redundancy.

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 simple one-parameter tool with no output schema, the description covers purpose, authentication, and optional parameter. It does not mention what happens on success/failure or any side effects, but given the simplicity and lack of output schema, this is nearly complete.

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?

The schema already covers the single parameter context_url with a full description. The tool description essentially restates the same meaning ('Optionally include a context_url the notification tap-through will open'). Since schema coverage is 100%, the baseline is 3, and no additional semantic value is added.

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 clearly states the action: 'Send a Yo' — a content-free push notification — and specifies the recipient ('to your owner'). It distinguishes itself from sibling tools (registration/revocation) by clearly defining a notification-sending function.

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?

It provides clear context: use this to send a push notification to the owner. It also mentions a prerequisite (Bearer token) and an optional behavior (context_url). However, it does not explicitly state when not to use it or compare with alternatives, though siblings are obviously different.

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