Hatch

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

Annotations already declare readOnlyHint=false, destructiveHint=true, and idempotentHint=true, so the description doesn't need to restate those. It adds valuable behavioral context: the sign-in screen lives at `/__roost/login`, the return shape is `{ enabled, mode, loginUrl }`, and `useraccounts` is unavailable because per-hatch databases are no longer provisioned. It could go further by noting whether `disable` is reversible or whether `setPassword` invalidates existing sessions, but the disclosed behavior is solid.

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 front-loaded: the core purpose is in the first sentence, followed by a scannable bullet list of actions. Every sentence earns its place, and the return shape and login URL are included without padding. The structure makes it easy for an agent to parse the action semantics quickly.

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 6 parameters, no required params, and no output schema, the description covers the main decision points: which action to use, which mode to prefer, what the return value is, and where the login screen lives. It doesn't explain the `tenantId` legacy alias or `sessionToken` pairing context, but those are fully documented in the schema. The description is complete enough for an agent to invoke the tool correctly in the common cases.

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 adds meaning beyond the schema by explaining the action/mode/password combinations: e.g., `enable` with `mode: "password"` and a `password` creates ONE shared password, and `setPassword` rotates it. It also clarifies that `action` defaults to `status`, which is not in the schema. The only minor gap is that `tenantId` and `sessionToken` are not mentioned in the description, but the schema already documents them fully.

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 clear verb+resource: 'Put a sign-in screen in front of any roost so visitors must authenticate.' It then enumerates the four actions (enable, setPassword, disable, status) with concrete effects, which fully distinguishes this tool from siblings like share or deploy. The title 'Protect a site with a login' reinforces the purpose without being the sole source of meaning.

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-use guidance: 'Best for a private demo or staging link' for password mode, and explicitly says 'Prefer password mode; useraccounts is unavailable.' It also explains when to use setPassword (rotate the shared password) and disable (remove the login and serve publicly). This is strong routing guidance relative to alternatives.

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 declare the mutation/open-world profile (readOnlyHint=false, openWorldHint=true, idempotentHint=false), and the description adds substantial context beyond them: the default option set, the non-terminal changes_requested outcome, the max_iterations_exceeded failure mode, the window.__VR_HITL_GET_SETTINGS__ requirement for interactive pages, and webhook-vs-poll delivery semantics with a payload doc reference.

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?

It is a dense paragraph, but front-loaded with the core action and each sentence carries operational content (defaults, flow, automation preference, doc pointer). Slightly cramped across topics, but no filler sentences.

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, no-output-schema, open-world mutation, the description covers the review lifecycle, timeout/iteration behavior, and outcome delivery routes well. Minor gaps remain around unexplained parameters such as contextUrl and sessionToken, which neither the schema nor the description clarifies.

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 82%, which already documents defaults for options, maxIterations, and timeoutSeconds, so the baseline is 3. The description largely restates those defaults (Approve/Request changes/Reject, default 5, max_iterations_exceeded) rather than adding new per-parameter meaning; the genuinely new points (webhook preference, __VR_HITL_GET_SETTINGS__) are workflow-level, not parameter-level.

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 human-in-the-loop review on the live artifact.' It further distinguishes itself from sibling tools by explaining the non-terminal Request changes flow and routing to continue_decision and poll_decision, so an agent can tell it apart from the other poll_/continue_ tools without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly names alternatives and the conditions that select them: 'call continue_decision after regenerating,' and 'prefer webhook over poll_decision for automation' when wiring n8n/Temporal/CI. Both when-to-use and which-alternative guidance are present.

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=false, so the safety profile is established. The description adds meaningful behavioral context by specifying the return structure and the precondition relative to `checkout`, going beyond what annotations 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 sentences, front-loaded with purpose, then usage guidance, then return shape. Every clause serves a purpose and the inline price list is compact and useful.

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 only one optional parameter and no output schema, the description fully compensates by stating the exact return shape. It tells the agent what it does, when to use it, and what to expect, leaving no critical gaps.

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 the single `grant` parameter at 100% with enum descriptions, so the baseline is 3. The description adds extra meaning by mapping grant values to product names with prices and clarifying when the parameter is needed, enriching understanding beyond 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?

The description states a specific verb ('List') and resource ('VibeRooster features the user can pay for'), with concrete price examples and return fields. It clearly distinguishes itself from sibling tools like `checkout` and generic `list` by focusing on payable feature catalog data.

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 instructs to 'Call this before `checkout` if you don't already know the grant', giving a concrete precondition and naming the related sibling. This makes the usage context 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?

Beyond the annotations, the description discloses the webhook side effect (grant applied), the exact return shape, the required follow-up polling behavior, and the metadata stamping the webhook expects. This gives the agent a clear model of what the call starts and what happens afterward.

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 long, but every block earns its place: behavior, return value, follow-up, required-id mapping, and the Stripe MCP warning. Essential call semantics are front-loaded; the grant-specific detail is dense but necessary for correct invocation.

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 fully compensates by specifying the return shape, post-payment actions, grant-specific id requirements, and default pricing behavior. The agent has everything needed to invoke checkout correctly and continue the flow.

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%, but the description adds important conditional semantics: required ids by grant, default behavior when priceId is omitted, and quantity meaning per grant. This adds real value beyond the schema's per-field descriptions, though the schema already documents each field.

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 Stripe Checkout Session so the user can pay for a VibeRooster feature in this chat.' This clearly distinguishes checkout from sibling tools like poll_checkout and catalog by stating its exact 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 explicit when-to-use guidance: create the checkout session, ALWAYS show checkoutUrl, then poll_checkout until status is complete. It also names an explicit exclusion: do not use Stripe MCP for VibeRooster features, which steers the agent away from a plausible wrong tool.

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-read-only, non-idempotent, non-destructive, open-world. The description adds real behavioral value beyond that: it performs a state transition to pending_review on the same decision, and clarifies that hatchId is derived rather than supplied. It does not mention timeout/session semantics or what the call returns, but the safety profile is adequately covered.

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, zero filler, with the precondition front-loaded ahead of the effect and the parameter hint. Every clause carries information.

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?

Covers the workflow position, state change, and required parameter for a 7-param, no-output-schema tool. Optional params like sessionToken and timeoutSeconds are left to the schema, which is acceptable but leaves a small gap for a state-mutating call.

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 only 57%, but the description compensates by stating that only decisionId is required and that hatchId is read from the decision, resolving the ambiguity between hatchId and its tenantId alias. It says nothing about sessionToken, title, agentOutput, or timeoutSeconds.

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 (reopen) on a specific resource (the decision) and names the resulting state (pending_review), which distinguishes it from poll_decision and await_decision. An agent can tell what this does without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives the exact trigger condition (poll_decision returns changes_requested) and the required preceding action (regenerate), plus the follow-on outcome (next human round). This is explicit when-to-use routing, not inference.

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 annotations, it discloses atomic rename behavior, atomic old-slug release, the side effect of creating a second site if `hatch` is called again, Promo conditional rules, Pin/carousel default visibility, and the custom-domain checkout grant requirement. It is consistent with annotations (`destructiveHint: true`, `idempotentHint: true`, `openWorldHint: true`) and adds useful operational context.

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 purpose and constraints in a logical order, but some passages duplicate schema parameter descriptions, especially the Promo rules. It is lengthy for a tool description, though much of the length is justified by the multi-action 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?

For a complex multi-purpose mutation tool with no output schema, the description covers operations, parameter combinations, alternatives, constraints, and side effects. Annotations already carry the safety profile, and the description fills in the remaining behavioral and routing context needed 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?

Schema description coverage is 100%, so the schema already documents parameters, but the description adds a critical cross-parameter constraint: `hatchId` plus at least one of the four action parameters, with `promo` alone being sufficient. It also clarifies `newTier`/`checkout` boundaries and the custom-domain grant condition, though it does not cover every parameter such as `tenantId` or `sessionToken`.

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 explicitly states the tool's multiple actions: atomically rename a roost URL, change gallery listing, mark/unmark Promo, or bind a custom domain. It distinguishes the tool from siblings by warning against using `hatch` for rename/Promo and by pointing to `checkout` for paid Pins.

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 explicit when-to-use and when-not-to-use guidance: pass `hatchId` plus at least one of `newPreferredSlug`, `galleryListed`, `promo`, or `customDomain`; do not call `hatch` again to rename or change Promo; after subscription Pin slots are exhausted, use `checkout` with grant `publish`; do not use `convert` to collect payment.

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, readOnlyHint=false, idempotentHint=true and openWorldHint=true, so the safety profile is covered. The description adds the 'advanced' framing and a 1.5 MiB text-only script constraint, but says nothing about the HITL review flow that the schema's policy/approvalId/hitlTitle/await_decision parameters imply, which is the most consequential behavior for this tool.

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 tight sentences: purpose, routing guidance, then required inputs and limits. Front-loaded and free of 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?

Adequate for invoking the tool given 80% schema coverage and annotations covering the mutation profile, but for a 10-parameter, HITL-driven, no-output-schema operation the description omits the review/approval lifecycle an agent needs to complete the call. The missing piece is behavioral, not syntactic.

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 most parameters are already documented; the description names hatchId, workerName and script plus a useful 1.5 MiB size limit not present in the schema. However, it does not touch the HITL-related parameters (policy, approvalId, hitlTitle, webhookUrl) that carry the most ambiguity, so the baseline 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?

Specific verb 'Replace' plus a precise resource 'the server-side code of an existing roost', and it explicitly names sibling tools it is not (upload, convert). An agent can distinguish it from all siblings without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

States the selection condition up front ('Advanced — most agents should use upload... or convert... instead') with the reason each alternative applies (static files, renames). Explicit when-to-use and when-to-avoid 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 the safety profile (readOnly=false, idempotent=false, destructive=false); the description adds the 10-minute TTL, the code-reuse semantics behind idempotentHint, and the critical rendering constraint about which URL to show the user in a desktop chat vs. in-app QR.

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?

Purpose and TTL are front-loaded, and the URL-display guidance is operationally necessary. It is slightly dense and repeats the reuse rule that schema descriptions also carry, but almost 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?

With no output schema, the description compensates by naming the returned fields (pairingUrl, appUrl), explaining their difference, and giving the polling follow-up. Nothing an agent needs to call and present the result 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 baseline is 3, but the description adds genuine meaning: it distinguishes the consumer path (hatchId) from the partner path (workspaceId) and clarifies forceNew's rotation behavior. Only tenantId's legacy-alias role is left solely to 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 concrete verb+resource (issue a pairing code + URL) with a TTL and both distinct use cases (claiming a hatch via hatchId, authorizing an agent session via workspaceId), making it clearly distinguishable from siblings like whoami or poll_pairing.

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 specifies when to reuse the active pending code, when to rotate with forceNew=true, and when not to call again (until poll_pairing returns expired/completed). It also routes the agent on which sibling to use next, leaving nothing to inference.

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 flag this as a non-read-only, open-world, non-idempotent create; the description adds real behavioral context beyond them — the returned object shape, the presigned-upload two-step flow, the 1.5 MiB script cap, promo's carousel/chip interaction, and the explicit 'NEVER call twice' idempotency warning that reinforces idempotentHint=false. Nothing contradicts 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?

Front-loaded with the single most important sentence, then bulleted by calling mode, which is appropriate structure for an 18-parameter tool. It is long, and the promo paragraph largely restates the schema's promo description plus a redundant 'call convert, do not hatch again' reminder, so a little pruning is possible.

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, and the description compensates by spelling out the return object keys and telling the agent what to do with them (show url, remember hatchId). For a high-complexity, open-world, nested-object tool, all the operational facts an agent needs — upload flow, size limits, expiry, workspace precondition — are present.

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 the baseline is 3, but the description adds decision-level meaning: the apex list is mapped to user intent with a 'do not invent other apexes' guard, the five mutually exclusive content parameters are ranked by preference (html for n8n, manifest for assets, site for text-only, script for advanced), and tiers are explained operationally ('free' then checkout with grant publish). Some of this overlaps the schema text, keeping it below 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?

States a specific verb and resource ('Create a NEW site (a roost)') plus the return value in the very first clause, and immediately separates itself from siblings by naming 'convert' for rename/tier/promo and 'upload'/'deploy' for content updates. An agent can route correctly without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit when/when-not guidance: never hatch twice for the same site, use convert instead; enumerates five distinct calling modes (html, omit-all, manifest, site, script) and states which is preferred for which situation. Exclusions are also given (mutual exclusivity, no empty strings, no base64 in script).

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/idempotent/non-destructive/closed-world, so the safety profile is covered. The description adds real value beyond that: the exact return shape, the meaning of `promo`, the fact that `workspaceId` may be omitted for a paired session, and the auth recovery path. It does not mention pagination or result-size limits, which is the main remaining gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, front-loaded with purpose, then returns, then usage and auth. The inline return-shape block is dense but justified because no output schema exists. Slightly heavy but every element 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?

With no output schema, the description carries the return contract and does so field-by-field, plus the pairing prerequisite. An agent has everything needed to call this correctly and interpret the result.

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 both `workspaceId` and `sessionToken` are already documented. The description restates the `workspaceId` optionality rule rather than adding syntax or edge-case meaning, 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?

States a specific verb and resource ('List every hatch in a workspace') and even enumerates the returned fields, so the agent knows exactly what this produces. It does not, however, differentiate itself from plausible siblings such as `catalog` or `lookup`, which likely also enumerate resources, so the reader must infer the distinction.

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 concrete triggering contexts: recovering lost hatchIds, checking before `hatch` to avoid duplicates, and answering 'what is live'. It also lays out the prerequisite chain (`whoami` → `get_pairing_code`). It stops short of naming a when-not-to-use case or an alternative tool, so it lands at clear-context rather than fully 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 cover the safety profile (readOnly, idempotent, non-destructive, openWorld), and the description adds genuinely new context: the return shape, that descriptions come from frontmatter, and the important caveat that the file body is not returned. This is more than the annotations 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?

Front-loaded with the purpose and return shape, then caveats, then contribution instructions. Mostly earns its place, though the PR workflow sentence is slightly tangential to invocation.

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 by documenting the exact return object and the frontmatter provenance, and it flags what is not returned. For a zero-arg listing tool this is 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?

Zero parameters, so the baseline is 4; the description confirms 'No arguments' consistently with the empty schema. Nothing further is required.

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 ('List HTML templates and explorable archetypes from the public template catalog') and names the source URL. However, it never distinguishes itself from potentially overlapping siblings such as 'catalog' and 'list', so an agent must infer the boundary.

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 is only implied: 'No arguments' tells the agent how to call it, and the PR instructions hint at the catalog's purpose. There is no explicit when-to-use statement or comparison against the 'catalog'/'list' 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 readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds substantial value beyond that: the full return shape, the multi-condition `promo` visibility rules, and the password exception ('A password still keeps a Promo hatch off the carousel'). It omits edge behavior such as what happens when neither identifier is supplied (0 required params).

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?

Front-loaded with the core action, followed by return shape, promo rules, use case, and the alternative. The promo sentence is dense but every clause conveys real gating logic; minor length creep but no filler sentences.

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 carries the return-value burden and does so thoroughly by enumerating the compact view fields. Gaps are minor: no guidance on the 0-required-param case, error behavior, or the legacy `tenantId` alias.

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 baseline is 3; the schema already documents `slug`, `hatchId`, and the `tenantId` legacy alias. The description names the two primary parameters but adds no format or constraint detail beyond what the schema provides, and never mentions `tenantId`.

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?

Opens with a specific verb and resource: 'Resolve a roost by `slug` or `hatchId`', and explicitly distinguishes itself from `list` ('To see every hatch in a workspace, use `list` instead'). An agent can identify the tool's function and its primary alternative without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit when-to-use guidance ('recover state across turns when the user mentions their site without giving you the hatchId') and names the alternative tool with the condition that selects it ('To see every hatch in a workspace, use `list` instead'). Nothing about tool selection is left to inference.

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?

Annotations already establish read-only/idempotent, and the description adds substantial extra context: the ~20s long-poll window, the guarantee that polling never writes, and the precise meaning of timeout_exceeded (the await_decision timeoutSeconds deadline, not a human action). It also enumerates all terminal and non-terminal outcomes.

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 polling behavior, required input, and return values come in that order with no filler. Slightly clause-heavy, but each clause carries distinct behavioral information.

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 fully enumerates possible return statuses and included fields (comment, settings, conversation, iteration), which is exactly what an agent needs to branch on. Nothing material is missing 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 67% and decisionId has no schema description, but the description clarifies that only decisionId is required and that hatchId is read from the decision rather than supplied. It does not address tenantId (the legacy alias), so the schema must still carry that.

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+resource (long-poll the decision) and the exact condition it waits on (until it leaves pending_review). An agent can distinguish it from siblings await_decision and poll_approval from the description alone.

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 concrete call guidance: only decisionId is required, hatchId is derived, and call again if still pending_review. However it never says when to prefer this over await_decision or poll_approval, leaving the sibling choice to inference.

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 indicate a non-read-only, non-destructive, idempotent operation. The description adds meaningful behavioral context beyond that: payment prerequisite, workspace-pairing requirement, failure on free Hatch workspaces, and the exact return shape. 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 compact and front-loaded. Each sentence earns its place: purpose, usage conditions, failure mode, alternative, and return value. 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 mutating tool with no output schema, this description is complete enough for correct selection and invocation. It covers prerequisites, failure behavior, remediation steps, exclusions, and return format. The only minor gap is the behavior when no name parameter is supplied, but this does not meaningfully hinder an agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description adds useful combinatory semantics: pass `orgName`, `workspaceName`, or both, and clarifies that omitting each leaves it unchanged. This goes slightly beyond the individual schema 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?

States a specific verb and resource: renames the organization and/or workspace. It also explicitly distinguishes itself from `convert`, which handles hatch URLs, so an agent can tell it apart 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?

Provides explicit when-to-use context: after Roost or Roost Audit has been paid, and with a workspace-paired session. It names the billing path (`checkout` with grants, then `poll_checkout`) and the alternative for hatch URLs (`convert`), leaving no ambiguity about when to choose this tool.

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 behavior beyond the annotations: the URL is 'signed' and 'expiring', and it states the return shape `{ url, viewToken, expiresAt }`. However, it does not disclose whether issuing a URL creates server-side state, consumes a session, or revokes previous links, and with readOnlyHint=false and openWorldHint=true this information would be useful. It partially compensates for weak annotations but leaves implicit side effects.

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 with a distinct job: action+behavior, use case, and return shape. The most important information is front-loaded and there is zero 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 tool with no output schema, the description provides the return shape, purpose, and usage scenario, which covers most of what an agent needs. The remaining gap is parameter-level detail (sessionToken, expiresSeconds), which was already penalized in parameter_semantics. Overall, the description is nearly complete for a simple URL-issuing tool.

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 only 50% (hatchId and tenantId are documented). The description adds 'any tier' and 'expiring', loosely tying to hatchId and expiresSeconds, but it never explains sessionToken or how expiresSeconds should be set beyond the schema's min/max. Since the schema leaves two parameters undocumented and the description does not compensate, this is a clear gap.

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 precise verb+resource pair: 'Issue a signed, expiring guest view URL', and qualifies it with 'for any tier' and the concrete `?vt=…` format. This clearly states what the tool does and fully distinguishes it from any sibling tool, none of which overlap with sharing/guest access.

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 second sentence gives an explicit use case: 'Use for private run reports without the shared site password.' This tells an agent the exact scenario where this tool is appropriate. It doesn't name alternatives or exclusions, but the share function is unique among the sibling list, so the contextual guidance is strong enough.

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 (destructive/idempotent/openWorld), the description discloses the two-step mechanism: it returns one presigned PUT URL per file and bytes are uploaded directly via HTTP, with files going live as each PUT completes. This is high-value behavioral context the annotations cannot convey. It does not cover auth/permission requirements, which is the main remaining gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action and the EXISTING constraint, followed by the input, the return mechanism, and the workflow context. Every sentence adds distinct information with zero padding.

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 8-param, nested-schema tool with no output schema, the description compensates by explaining the return (presigned URLs) and the follow-up HTTP PUT step. The policy/HITL/session/expiry params are left to the schema, which is reasonable but not fully addressed.

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 88%, so the schema already documents hatchId, manifest structure, policy, and the HITL/webhook params. The description restates the manifest fields (path, size, content type) rather than adding semantic detail, so baseline 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?

States a specific verb (add/replace files) and resource (an EXISTING roost), and the capitalised 'EXISTING' cleanly separates it from the creation-oriented `hatch` sibling. An agent can tell what this does and where it applies without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives a concrete trigger ('Use after regenerating a dashboard locally; Hatch does not schedule regenerations') and clarifies no separate publish call is needed, which heads off a common wrong workflow. It does not name explicit alternatives or exclusions, so it stops short of full when/when-not 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 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.