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?

Annotations only declare readOnlyHint=false and openWorldHint=false, so the description carries real extra weight: it discloses the auth requirement ('Requires an agent API key as the Bearer token') and the privacy consequence that the subject appears on the lock screen and in the app, hence 'avoid secrets'. It stops short of describing delivery, rate limits, or failure behavior.

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, front-loaded with the action, then recommendations, then the auth caveat. Nothing is padding, though the parameter recommendations partially duplicate the schema descriptions.

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 two-parameter, zero-required tool with no output schema, the description covers purpose, both parameters, authentication, and the lock-screen/secret caveat. Minor gaps remain around result reporting and send frequency limits.

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%, so the schema already documents length limits, Unicode code-point counting, and https/deep-link formatting. The description restates the recommended usage of both fields (why to include a subject, when a context_url is useful) but adds little beyond that, so the baseline 3 applies.

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, resource and target: 'Send a Yo push notification to your owner.' That is unambiguous and cannot be confused with the sibling registration/revocation tools, none of which send messages.

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 implies the use case (notify the owner) and gives parameter-level recommendations ('include a short subject...', 'a context_url when there is a useful link'), but never states when to notify versus not to, nor any frequency/appropriateness limits. With no true alternative tool to route between, this is adequate but thin.

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