Hatch

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

Annotations already indicate destructive and read-only behavior, so the bar is lower. The description adds valuable context: exact return shape `{ enabled, mode, loginUrl }`, the login URL `/__roost/login`, the irreversible-sounding `disable` behavior, and the availability constraint on `forever` roosts. It does not contradict the 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?

The description is well-structured with a bulleted action list, front-loads the core purpose, and each sentence adds non-redundant information such as prerequisites, return shape, and login URL. It is appropriately sized for a multi-action tool.

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 tool with six parameters and no output schema, the description covers prerequisites, action semantics, parameter combinations, return value shape, and important constraints. There is no obvious missing information an agent would need to select and invoke this 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?

Schema coverage is 100%, so the baseline is 3. The description adds value by mapping actions to required parameters (e.g., `enable` with `mode: 'password'` and `password`, `setPassword` with new `password`, `disable`, `status`) and clarifies that `useraccounts` is unavailable despite being present in the schema enum.

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 states a specific action and resource: 'Put a sign-in screen in front of a `forever` roost so visitors must authenticate.' It further enumerates the four operations (enable, setPassword, disable, status), making the tool's purpose concrete and distinguishable from any generic auth tool.

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?

Provides explicit when and when-not guidance: auth is only available on `forever` roosts, requires calling `checkout` with grant `publish` first, and explicitly says not to convert newTier to forever. It also advises preferring `password` mode and notes `useraccounts` is unavailable.

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 are minimal, so the description carries the full disclosure burden. It adds key behaviors: changes_requested is non-terminal, timeout/maxIterations semantics, the requirement for window.__VR_HITL_GET_SETTINGS__ on interactive pages, and webhook POST behavior on every transition.

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 dense and front-loaded with the core action, then progresses through behavioral nuances and integration guidance. Every sentence adds information, though the length is justified by the tool's complexity. A slightly tighter arrangement of external-workflow details would raise it to 5.

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 an 11-parameter tool with no output schema, the description covers the full lifecycle, defaults, failure modes, and external integration, and even points to PARTNER-WEBHOOKS.md for payload details. The interactive-controls requirement addresses a critical edge case. Nothing essential is missing.

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 82%, so the schema already documents most parameters. The description adds value beyond the schema for webhookUrl (prefer over poll_decision, receives POST on every transition), maxIterations (default and failure at last iteration), and options (classification into approve/reject/changes_requested).

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: 'Create a human-in-the-loop review on the live artifact.' It goes on to detail default options and the review lifecycle, which clearly distinguishes it from siblings like poll_decision and continue_decision.

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?

Explicit guidance is given for selecting alternatives: 'prefer webhook over poll_decision for automation' and 'then call continue_decision after regenerating' when changes are requested. It also specifies when to pass webhookUrl for external workflows, leaving no ambiguity about when to use this tool versus its siblings.

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 already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds the exact return shape (`{ items: [{ grant, title, description, priceId, amountCents, scope }] }`), which is behavioral context beyond the annotations. It does not discuss errors or rate limits, but for a simple read-only listing this is sufficient. No contradiction with 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?

The description is two sentences, front-loaded with the core purpose and examples, then immediately provides usage guidance and the return format. Every sentence earns its place with zero 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 tool with one optional parameter and no output schema, the description is complete: it states the purpose, gives usage context, lists the return structure, and provides examples. An agent has everything needed to decide when to call it and what to expect. No missing critical information.

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 description coverage is 100% (the single parameter `grant` has a description). The tool description does not add meaning beyond the schema for the parameter itself—it mentions examples of features but does not map them to enum values beyond what the schema says. The baseline of 3 is appropriate since the schema carries the parameter 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?

The description clearly states the action (List) and the resource (VibeRooster features the user can pay for) with concrete examples. It also includes the output structure and explicitly ties its usage to the `checkout` sibling, distinguishing it from other tools.

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 context: 'Call this before `checkout` if you don't already know the grant.' This gives a clear scenario for when to use it. It does not mention exclusions or alternatives, but the condition is specific enough for an agent to decide. Since it lacks explicit when-not-to-use or alternative tool names, it earns a 4 rather than a 5.

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?

Beyond readOnly=false and openWorldHint=true, the description reveals the side-effectful flow: a Stripe session is created, the webhook later applies the grant, and the returned URL must be shown to the user. It also explains metadata stamping, which the annotations do not cover.

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?

Dense but front-loaded: the core action, return contract, and follow-up come first, with conditional id requirements and warnings after. Nearly every sentence earns its place, though the instructions could be tightened slightly.

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 7-parameter tool with no output schema, the description supplies return shape, post-payment polling protocol, cross-parameter id requirements, and integration cautions. Nothing needed to invoke it correctly is missing.

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 is 3, but the description adds essential conditional logic absent from any single property: which id is required for each grant value (hatchId, workspaceId, orgId). It clarifies default priceId behavior and prevents incorrect cross-field choices.

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 the specific operation and resource: create a Stripe Checkout Session for a VibeRooster feature payment. It also differentiates from siblings by telling the agent to call poll_checkout afterward and not to call convert or the Stripe MCP.

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 explicit when-to-use and when-not-to-use instructions: show checkoutUrl, poll until complete, never call convert(newTier: forever), and never use Stripe MCP for VibeRooster. Also explains required ids per grant, so the agent knows prerequisites before calling.

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 already declare non-readOnly and non-idempotent, so the agent knows it mutates state. The description adds that it transitions a decision from changes_requested to pending_review. However, given openWorldHint is true, it could disclose potential side effects (e.g., notifications, external updates), which it does not. It adds some context but not exhaustive behavioral detail.

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?

A single sentence that front-loads the trigger condition and clearly states the action. No redundant words or filler; every part serves a purpose.

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 state-transition tool, it gives the essential workflow: trigger, regenerate, call. It doesn't describe return values, but with no output schema that may be less critical. It could mention what to expect afterward (e.g., next poll_decision returns pending_review), but it's reasonably complete for its role.

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 57%, so some parameters are documented in the schema. The description adds no parameter-specific meaning—it only references 'the same decision' and implies decisionId. It doesn't clarify the roles of title, hatchId, tenantId, agentOutput, sessionToken, or timeoutSeconds beyond what the schema already provides. With moderate coverage, the description doesn't compensate, so it's adequate but not enhanced.

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 tool's purpose: to reopen a decision as pending_review after poll_decision returns changes_requested. It uses a specific verb ('reopen') and resource ('same decision') and ties it to a precise state transition, distinguishing it from sibling tools like poll_decision and await_decision.

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 explicitly specifies when to call this tool (after poll_decision returns changes_requested) and instructs to 'regenerate' first, providing a clear precondition. It doesn't explicitly list alternatives, but the context implies this is the continuation path rather than creating a new decision, making the usage guidance strong.

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?

Beyond the annotations (destructiveHint, readOnlyHint, etc.), the description discloses atomicity ('Atomically rename'), the effect of galleryListed on forever roosts ('Forever roosts are hidden from the carousel by default'), and the rejection behavior of newTier: forever. These details materially impact how an agent invokes the tool and what outcomes to expect, and they do not contradict any 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?

The description is three sentences long, front-loaded with the core action and requirement, then the most critical warning (newTier: forever), then the default behavior detail. Every sentence carries necessary information with no fluff 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?

Given the tool has 6 parameters and no required fields, the description covers the primary use cases (rename, gallery toggle), the key exclusions, and the correct alternative for permanent tier. It does not explicitly explain how 'change tier' (to free) works via newTier, but the schema covers that and the description already tells agents to avoid forever. This is complete enough for correct invocation.

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 schema documents each parameter fully. However, the description adds a key semantic constraint not present in the schema: 'Pass hatchId plus at least one of newPreferredSlug or galleryListed.' It also clarifies the newTier parameter by reiterating the checkout requirement. Since the schema already does most of the work, this is a 4 rather than 5.

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 tool's purpose: 'Atomically rename a roost's URL and/or change gallery listing.' It specifies the resource (roost) and the actions (rename/change gallery), and explicitly distinguishes from 'hatch' by warning 'Do NOT call hatch again to rename — that creates a second site.' This gives agents crisp scope and differentiates it from related tools.

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 when-to-use and when-not-to-use guidance: it states the condition ('Pass hatchId plus at least one of newPreferredSlug or galleryListed') and gives clear exclusions: 'Do NOT call hatch again to rename' and 'Do NOT pass newTier: forever to collect payment.' It also names the correct alternative workflow ('To make a roost permanent, call checkout...') making the routing unambiguous.

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 already declare destructiveHint=true, so the description isn't required to restate mutation, but it reinforces replacing existing code and adds actionable constraints (ES module, text-only, 1.5 MiB max). It does not describe HITL/forking side effects, but that nuance is captured in the policy parameter's schema description; no contradiction with 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?

Two dense sentences with no filler. The warning about alternatives is front-loaded before the required payload, so the most important routing information is immediately visible.

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?

The description covers the common path well, but this is a 10-parameter advanced mutation with no output schema. It does not explain outcomes (e.g., fork behavior under policy=required, HITL/approval flow, session token use) though most optional terms are at least documented in the schema. Acceptable but not complete for every agent decision.

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 80% so the baseline is already strong; the description adds real value by calling out the required-ish trio (hatchId, workerName, script) and defining script as 'full ES module (text only, 1.5 MiB max)', a constraint not in the schema. It omits optional params but they are documented in the schema.

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 and resource ('Replace the server-side code of an existing roost') and frames itself as the advanced option vs upload/convert. This clearly differentiates it from sibling tools.

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 tells agents when not to use it ('most agents should use upload for static files or convert for renames instead'), giving alternatives and their applicable cases. The intended use case—advanced server-side replacement—is clear.

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 provide only generic flags (`readOnlyHint` false, `idempotentHint` false), so the description carries the behavioral burden. It adds the 10-minute TTL, reuse of the active pending code, invalidation on `forceNew: true`, and the expectation to render `pairingUrl` as a QR code. This exceeds what annotations and schema alone convey, and there is 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?

The description is three dense sentences with no filler. The action and TTL are front-loaded, the reuse semantics follow immediately, and the final sentence contains the critical operational instruction. Every sentence earns its place.

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 names the returned artifacts (`pairing code`, `pairingUrl`), tells the agent how to consume them (render as QR), and explains the lifecycle through `poll_pairing` and `forceNew`. For a tool with this complexity, the description is sufficiently 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?

Schema description coverage is 100%, and the description reinforces the parameter roles by tying `hatchId` to the consumer path and `workspaceId` to the B2B path. It also clarifies `forceNew` behavior by stating it invalidates the outstanding QR. It stops short of stating whether exactly one of the id parameters is required, but the schema already documents `tenantId` as a legacy alias.

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: 'Issue a pairing code + URL' and immediately names the two supported contexts: claiming a hatch via `hatchId` and authorizing an agent session via `workspaceId`. This is far more specific than the title and clearly distinguishes the tool from polling and auth siblings.

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 explicit when-to-call and when-not-to-call guidance: 'do not call again until poll_pairing returns expired/completed or you intentionally rotate with forceNew.' It also names the companion tool `poll_pairing` and explains the `forceNew` rotation path, so an agent can sequence calls correctly.

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 already declare readOnly=false, openWorldHint=true, idempotentHint=false abnormal. The description adds valuable behavioral context: it is non-idempotent ('NEVER call hatch twice'), describes the exact response shape, presigned upload workflow, placeholder behavior when nothing is passed, and warns against empty strings. It does not mention potential side effects like auto-opened HITL or charging, but those are covered in the schema. Consistent with annotations, 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?

The description is structured with a clear opening, a punchy warning, and bullet points for each call mode. Every section earns its place; there is no redundant fluff given the tool's complexity.

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, but the description explicitly lists the returned fields and their purpose. All major call scenarios (html, manifest, site, script, placeholder) are described with constraints. The schema covers the remaining parameter details, so together they are complete enough for correct invocation.

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 94%, so parameters are mostly documented. The description adds practical meaning: which content mode to choose, script strict limits (1.5 MiB, text only), file key conventions ('index' accepted as 'index.html'), and which fields to omit. It does not repeat schema details but enriches them with usage rules.

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: 'Create a NEW site (a 'roost') and return its public URL in one call.' It names sibling tools it is not: 'use convert to rename or change tier, and upload/deploy for content updates.' An agent can clearly distinguish this from its siblings.

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 tells when to use this tool vs alternatives: 'NEVER call hatch twice for the same site' and directs to convert/upload/deploy. Also provides a clear decision tree for call modes (html vs manifest vs site vs script) with preferences (e.g., 'PREFER this for any project with images, fonts, video').

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 already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context beyond annotations: the exact return shape (a nested object with hatch details), the optionality of workspaceId when paired, and the workspace-paired session prerequisite with an auth recovery path. This exceeds what annotations provide without contradicting them.

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 three sentences that pack the core purpose, return shape, three use cases, parameter optionality, and an auth prerequisite without fluff. It is front-loaded with the action and return value, and the less-common auth edge case appears last. Slightly dense but well-structured, so a 4 is warranted.

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 list tool with no output schema, the description fully covers the return type (including the nested object structure), the conditions for omitting workspaceId, and the session-pairing requirement. Nothing essential to invoking it correctly is missing; the auth flow is referenced and delegated to sibling tools appropriately.

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 both parameters well. The description's note that 'workspaceId is optional when this connector is already paired' essentially echoes the schema's guidance ('Omit when the session is already scoped to a workspace'), adding little new meaning. Thus the baseline 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 clearly states the action ('List every hatch') and the resource ('in a workspace'), and it distinguishes itself from sibling tools like 'hatch' and 'lookup' by naming concrete use cases: when hatchIds are lost, before hatching to avoid duplicates, or when the user wants to know what is live. This makes the tool's 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?

The description explicitly lists when to use the tool ('when you lost hatchIds', 'before hatching', 'when the user asks what is live'), and it provides an alternative path ('call whoami, then get_pairing_code') for unpaired sessions. This gives the agent clear decision criteria and actionable fallback, satisfying the 'when/when-not/alternatives' criterion.

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 already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the exact return shape and the intended use case, but it does not disclose behavior when neither slug nor hatchId is provided, which matters because the schema marks all parameters as optional.

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?

Four sentences, each carrying distinct value: what it resolves, what it returns, when to use it, and which sibling to use instead. The core action and return contract are front-loaded, and there is no 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?

For a simple read-only lookup tool, the description provides the return contract, the lookup keys, and the sibling alternative, which is strong. The main gap is the missing statement about required identifier presence and behavior on a miss, but the schema and annotations fill enough of the surrounding context.

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 baseline is 3; the description does not need to restate parameter definitions. It adds some semantic guidance by framing slug and hatchId as alternative lookup keys, but it stops short of clarifying that at least one identifier is expected despite required=0.

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 a specific verb ('Resolve') with a clear resource ('a roost') and identifies the lookup keys: slug or hatchId. It also distinguishes itself from the sibling tool `list` by explicitly saying 'use `list` instead' for workspace-wide enumeration.

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 a concrete when-to-use scenario: recover state across turns when the user mentions their site without giving the hatchId. It also names the alternative (`list`) and the condition for choosing it, making the routing decision explicit.

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 already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds useful behavioral context: this is a long-poll that waits until the owner approves or denies on their phone. It does not describe timeout or error behavior, but it does add 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?

Two short, front-loaded sentences with no filler. The first sentence identifies the action and subject, and the second clarifies the blocking/return behavior.

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 poll tool with no output schema, the description states the return trigger but not the shape of the result, timeout behavior, or how approvalId is obtained. The annotations cover safety and the schema covers the hatchId aliases, but an agent still lacks a few operational details needed to handle the poll cleanly.

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 covers hatchId and tenantId, including the alias relationship, but approvalId has no schema description and the tool description adds no parameter-level meaning. With only 67% schema coverage and no compensation in the description, the required parameter remains underspecified.

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 states a specific verb ('Poll'), a specific resource ('pending Tier-2 phone approval'), and the expected outcome ('Returns the result once the owner approves or denies'). This clearly distinguishes the tool from generic polling siblings by tying it to the phone-approval 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 implies the right context: call when an approval is pending and the owner has not yet decided. However, it does not explicitly name alternatives like poll_decision or await_decision, nor does it state when not to use this tool, so usage guidance is only implicit.

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 already signal read-only, idempotent, and non-destructive behavior, so the description's burden is lower. It adds valuable behavioral detail: the ~18s long-poll timing, the exact status enum, the semantics of `grantApplied`, and the webhook timing caveat ('has or is about to apply the grant'). This is consistent with the annotations and goes well beyond them.

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 sentences, each earning its place: the first states what the tool does and returns, the second gives the open-status instruction, and the third explains the grantApplied flow. Key information is front-loaded and there is no filler or 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?

Because there is no output schema, the description correctly takes responsibility for explaining the return shape and the meaning of key fields. It also covers the two follow-up actions an agent must take depending on the result. With one well-documented parameter and rich annotations, nothing essential is missing for safe invocation and correct follow-through.

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 schema already explains that `sessionId` is a Checkout Session id (`cs_…`) from `checkout`. The tool description does not add any additional meaning for the parameter beyond what the schema provides, so the baseline of 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 and resource: 'Long-poll a Checkout Session from `checkout`'. It also defines the tool's output (payment status with open/complete/expired), which distinguishes it from sibling polling tools like poll_approval and poll_pairing. The reference to `lookup` as a follow-up further clarifies its role in the payment 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 concrete conditional usage instructions: if status is 'open', tell the user to finish paying and call poll_checkout again; if 'grantApplied' is true, call `lookup` to confirm. It names `lookup` as the next step, but does not explicitly state when to use poll_checkout versus other related sibling tools beyond the checkout context. This is strong but not a full when/when-not guide.

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?

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses the long-poll duration (~20s), termination conditions (timeout, max iterations), possible exit states, and included response fields. This is rich behavioral context the annotations do not provide.

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 dense sentences with the primary behavior front-loaded, followed by termination states and response contents. Every clause carries useful information; no filler or 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 polling tool with one required parameter and no output schema, the description explains the wait period, all possible resolutions, and the included response fields. It could be slightly more complete about how the decisionId is used or how changes_requested should be handled, but it is largely sufficient.

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 67%, and the required decisionId parameter has no description in the schema. The tool description does not mention any parameter, failing to compensate for the undocumented and required decisionId. It adds no meaning beyond the schema for the other fields.

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 tool long-polls until a decision leaves pending_review and enumerates possible outcomes, giving a concrete verb and resource. It does not explicitly differentiate from the sibling tool await_decision, which appears to serve a similar purpose, so it stops short of a 5.

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?

Usage context is implied: the description mentions 'regenerate + continue_decision' for changes_requested, hinting at a follow-up workflow. However, it never explicitly says when to use this poll versus alternatives like await_decision, nor provides exclusions or prerequisites.

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?

On top of readOnlyHint/idempotentHint, it discloses blocking wait time, the exact status set, what to store on completion, the 7-day refresh limit, the 1-hour sessionToken lifetime, server-side token binding, and a billing caveat. These are precisely the behavioral details an agent needs and none contradict the 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?

The description is front-loaded with the core purpose and timing, and almost every sentence carries operational value. The final billing caveat is terse and could confuse agents, but the overall length is appropriate.

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 compensates well by listing statuses and token-handling rules. It does not guide the agent on how to react to pending/expired/not_found statuses, such as whether to re-poll, which is a small but real completeness gap.

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 all four parameters with 100% description coverage, including code's source and hatchId's lookup benefit. The description's only parameter advice ('Pass hatchId when known') is less informative than the schema, so it adds no real meaning beyond schema.

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 title and first sentence identify a precise verb and resource: 'Poll for pairing completion' in Device-Grant style. The phone-approval framing and token-return details make it easy to distinguish from siblings like get_pairing_code and poll_approval.

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 gives clear workflow context: poll after phone approval, wait up to ~20s, pass hatchId when known, and switch to refresh_session when access expires. It never explicitly names an alternative poll tool or states when not to use this one, so the routing guidance is implicit rather than explicit.

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 critical behavioral traits beyond annotations: token lifetime (~1h), grant lifetime (7 days), refresh token rotation (each refresh rotates the refreshToken; store the new one), and session/fingerprint requirements. It also implies mutation (rotating tokens) consistent with readOnlyHint=false. This is rich behavioral context that annotations alone don't provide.

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 sentences, each earning its place: the first states the core action and token lifetime, the second explains the expiration boundary and alternative, the third discloses rotation and session requirements. Information is front-loaded with the most critical fact (renew token) first. No wasted words.

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 token-refresh tool with no output schema, the description covers everything an agent needs: what the tool does, when to use it, what happens after 7 days, the rotation behavior, and the session requirement. The parameter semantics are fully covered by the schema, and the behavioral traits are thoroughly disclosed. Nothing critical is missing.

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 schema already documents all parameters. The description adds value by explaining the refreshToken format (vr1.{grantId}.{secret}) and its origin (from poll_pairing), which helps the agent understand what value to pass. It also clarifies the relationship between hatchId, tenantId, and workspaceId implicitly by mentioning consumer vs B2B paths in the schema, though the description itself doesn't elaborate on parameter selection. Baseline 3 is exceeded because the description adds meaningful context about the token's structure and source.

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 tool's purpose: renew a short-lived access token using a refresh token. It specifies the resource (access token), the action (renew), and the mechanism (refreshToken from poll_pairing). It also distinguishes itself from related tools like get_pairing_code and poll_pairing by explaining the lifecycle relationship.

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 when-to-use guidance: use when renewing a short-lived token, and explicitly states when not to use it (after 7 days, re-pair via get_pairing_code). It also names the prerequisite (same connector session MCP-Session-Id) and the alternative (re-pairing). This is comprehensive routing information.

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 already declare readOnlyHint=false, destructiveHint=false, openWorldHint=true, idempotentHint=false. The description adds meaningful behavioral context: the URL is 'signed, expiring', and the return shape is `{ url, viewToken, expiresAt }`. It also clarifies that this is a non-destructive, open-world operation (issuing a link) without contradicting annotations. It doesn't mention rate limits or revocation, but the core behavior is well disclosed.

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 sentences, zero waste. The core action and mechanism are front-loaded, the use case is stated, and the return shape is given. Every sentence earns its place.

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 tool with 4 params, no output schema, and moderate annotation coverage, the description is quite complete: it states the action, the use case, the mechanism, and the return shape. The only gaps are the semantics of sessionToken and expiresSeconds, which are partially inferable from the schema. Given the tool's complexity, this is strong but not perfect.

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 50%, so the schema documents hatchId and tenantId but not sessionToken or expiresSeconds. The description adds the return shape and the `?vt=…` mechanism, but it doesn't explain the semantics of sessionToken or expiresSeconds beyond what the schema's min/max implies. The description partially compensates for the coverage gap but not fully, so a 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 states a specific verb ('issue'), a specific resource ('guest view URL'), and a distinguishing mechanism ('signed, expiring', '?vt=…'). It also clarifies the intended use case ('private run reports without forever-tier password auth'), which differentiates it from sibling tools like auth or lookup. The title 'Guest view link' is reinforced, not merely restated.

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 explicitly says when to use it: 'Use for private run reports without forever-tier password auth.' This gives clear context. It doesn't explicitly name alternatives or exclusions, but the sibling list and the phrase 'without forever-tier password auth' imply the alternative (auth) and the condition. A 4 is appropriate because the guidance is clear but not exhaustive.

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 already mark this tool as destructive/non-read-only, and the description adds important mechanics: it returns one presigned PUT URL per file, requires direct HTTP upload, and states files go live immediately with no separate publish call. This goes beyond the annotation hints, though partial-failure or idempotency behavior is not elaborated.

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?

Four dense sentences, each earning its place: purpose, required inputs, return/upload behavior, and usage context. The most important scoping, EXISTING roost, is front-loaded.

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 complex 8-parameter tool with a nested manifest and no output schema, the description covers the return contract (presigned PUT URLs), the direct upload flow, and the no-publish consequence. Schema covers the remaining parameters; only auth prerequisites and error/partial-failure behavior are left implied.

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?

With 88% schema coverage, the schema carries most parameter meaning. Still, the description adds the key invocation relationship 'Pass hatchId plus a manifest,' clarifies that content type is optional, and includes a concrete curl example, which helps an agent assemble the call beyond the raw schema.

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 action and object: 'Add or replace files on an EXISTING roost.' The word EXISTING and the note that 'Hatch does not schedule regenerations' differentiate this from hatch and similar siblings, so an agent can tell exactly what the tool is for.

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 gives a clear trigger: 'Use after regenerating a dashboard locally; Hatch does not schedule regenerations.' This states when upload is appropriate and contrasts with hatch, though it does not enumerate explicit exclusions or other alternative tools beyond that one context.

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 already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: it never errors when unidentified (returns a pairing path instead), explains the server-side session binding mechanism, and discloses the expiry times for session and grant tokens. This goes beyond what annotations provide, though it doesn't detail the exact response structure or error cases beyond the unidentified scenario.

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 compact and information-dense. Every sentence adds value: identity/hatch state, non-error behavior, session binding, expiry times, and the refresh_session fallback. It's front-loaded with the core purpose and then provides necessary operational details without fluff.

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 read-only identity check tool with no output schema, the description covers all essential aspects: what it returns, when it returns a pairing path, how session binding works, token expiry durations, and the next step if the session is expired. The sibling list shows related tools like poll_pairing and refresh_session, and the description correctly references both, making the tool's place in the workflow clear.

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 all three parameters. The description adds meaning by explaining the purpose of sessionToken (for connectors that cannot set Authorization headers) and the relationship between hatchId and tenantId (legacy alias). This is valuable context beyond the schema's basic descriptions.

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 tool's function: returning the caller's current identity and hatch state. It distinguishes itself from siblings by explicitly mentioning the pairing path and session binding, which is unique among the listed tools.

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 guidance on when to use this tool: after poll_pairing completes, and when sessionExpired is true, it directs the agent to call refresh_session. It also explains the sessionToken parameter's purpose for connectors that cannot set Authorization headers, which is a clear usage condition.

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