Hatch

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

Despite having annotations (readOnlyHint=false, destructiveHint=true), the description adds substantial behavioral context: disable 'remove[s] the login', setPassword 'rotate[s]' the password, and the return shape `{ enabled, mode, loginUrl }`. It also discloses the login screen location and prerequisite roost type, going beyond the raw annotation hints.

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 lead-in summary, a bulleted action list, a return format line, and prerequisite caveats. Every sentence serves a purpose: it explains the core function, each action, the response, and the forever-roost requirement without 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?

The tool has no output schema, yet the description provides the return shape. It covers all major usage aspects: prerequisites (forever roost), actions, mode caveats, login URL, and disable behavior. The only omitted detail is sessionToken's optional use, but that is in the schema and not critical for general understanding.

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. The description adds semantic value by explaining each action's effect in business terms (e.g., 'ONE shared site password', 'rotate the shared password') and notes that `useraccounts` is unavailable, which is not in the schema descriptions. This elevates it above baseline but not to a 5 because sessionToken is not re-explained and the schema already documents required 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 explicitly states 'Put a sign-in screen in front of a `forever` roost so visitors must authenticate,' which is a specific verb and resource. It also enumerates distinct actions (enable, setPassword, disable, status), making it clearly distinguishable from sibling tools like deploy or share.

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

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

It provides clear when-to-use context ('Best for a private demo or staging link') and when-not-to-use constraints ('only available on `forever` roosts — `convert` a free roost first'; 'useraccounts is unavailable'). It also directs users away from unavailable modes, fulfilling the when/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?

The description discloses several behavioral traits beyond the annotations: reviewers see a 'Review required chip → modal,' request changes is non-terminal, and the settings-exposure requirement for interactive controls. However, it leaves ambiguity about whether the tool blocks while awaiting a decision or returns immediately for polling, and it does not describe the return value. Given sparse annotations, this gap is noticeable.

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 a clear purpose statement and uses four sentences to cover both setup and workflow nuances. Each sentence adds substantive information, though the density of concepts (timeout, maxIterations, settings exposure, poll_decision) could be slightly better organized.

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 core initiation flow, the non-terminal changes path, and a special requirement for interactive controls. However, it omits what the tool returns, how to initiate the subsequent poll, and the meaning of several required parameters. Given no output schema and moderate complexity, these gaps leave the description incomplete for an agent to fully orchestrate the human-in-the-loop workflow.

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?

Input schema coverage is 67%, and the description adds little param-specific meaning beyond what schema descriptions already provide. It reinforces defaults for options and maxIterations but does not clarify tenantId, contextUrl, or sessionToken. The behavioral note about non-terminal request changes is more about workflow than parameter semantics, so the description only marginally compensates for the coverage 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 'Create a human-in-the-loop review on the live artifact,' which is a specific verb+resource pair that clearly states the tool's function. It distinguishes this tool from siblings like poll_decision and continue_decision by positioning it as the creation step, and the rest of the description elaborates on the review 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 practical workflow guidance: it explains that 'Request changes is non-terminal' and instructs to 'call continue_decision after regenerating,' and mentions using poll_decision on resolve. It does not explicitly state when not to use this tool versus alternatives, but the context makes the primary use case 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 already declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false, so the write/non-idempotent nature is known. The description adds that the tool transitions the decision from changes_requested to pending_review, which is useful state-change context. It does not disclose additional behavioral traits beyond that.

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?

One sentence, front-loaded with the condition, and every word contributes. Excellent structure for quick scanning.

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 essential workflow but omits important details such as required parameters (tenantId, sessionToken), return behavior, and any error conditions. With no output schema, some of this burden falls on the description, leaving it incomplete for a 6-parameter 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 descriptions cover only 33% of parameters (agentOutput and timeoutSeconds). The description implicitly identifies decisionId as 'the same decision' and hints at agentOutput through 'regenerate,' but leaves tenantId, sessionToken, and title unexplained. This doesn't fully compensate for the low schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Description states exactly what the tool does: after poll_decision returns changes_requested, it reopens the decision as pending_review. Uses specific verb 'reopen' and resource 'same decision', and distinguishes it from sibling poll_decision by referencing that tool's status.

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 the precondition ('After poll_decision returns status changes_requested') and the required action ('regenerate, then call this'). This clearly indicates when to use the tool. However, it does not discuss alternatives or exclusions, but it's enough for the intended flow.

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?

Discloses atomicity ('Atomically'), that the old slug is released, that forever roosts are hidden from the carousel by default, and that 'galleryListed: true' is required to feature publicly. These details go beyond the destructiveHint/idempotentHint annotations and clarify real side effects. 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 front-loaded with the primary action and is compact. Every sentence adds essential information: the atomic rename/tier change, the requirement to pass tenantId plus one field, the explicit warning about hatch, and the carousel visibility caveat. No filler or repetition of schema details.

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 no output schema and 5 parameters, the description covers all necessary invocation context: the required parameter, which combinations are valid, a critical sibling-tool pitfall, and behavioral effects (gallery visibility, slug release). It is sufficiently complete for correct selection and invocation without additional external knowledge.

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 schema already documents most parameters. The description adds meaningful semantics by grouping parameters ('Pass tenantId plus at least one of...'), explaining the meaning of newPreferredSlug as 'rename', giving a concrete tier example ('free' → 'forever'), and clarifying galleryListed behavior not fully captured 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?

The description opens with a specific verb+resource: 'Atomically rename a roost's URL and/or change its tier.' It clearly distinguishes from the 'hatch' sibling by warning that calling 'hatch' again creates a second site. The scope (URL rename, tier change, gallery listing) is fully covered.

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 guidance: pass 'tenantId' plus at least one of the three mutable fields. Explicitly names an alternative and warns against it: 'Do NOT call hatch again to upgrade — that creates a second site with a new id.' Also gives context for gallery listing behavior when promoting to forever.

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 destructive and non-read-only behavior, so the bar is lower. The description adds useful constraints: 'text only, 1.5 MiB max' for the script, and it implies that the operation is a full replacement. It does not elaborate on side effects beyond what annotations cover, but the added size/format constraints provide extra transparency.

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

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

The description is concise: two sentences that lead with the core purpose, then provide guidance and key constraints. There is no filler or repetition of schema details. It is well-structured and 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?

Given the tool has 6 parameters and no output schema, the description covers the main purpose, alternatives, and key parameter constraints. However, it omits context about the approval workflow (e.g., when `approvalId` or `sessionToken` are needed) and does not describe return values or success behavior. It is adequate but not fully comprehensive.

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 description needs to compensate. It does clarify that `script` must be a full ES module and size-limited, and it names the required parameters. However, it does not explain the semantics of `tenantId` and `workerName` (which lack schema descriptions), leaving some ambiguity. Overall, it adds some value but not comprehensive compensation.

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 ('Replace the server-side code of an existing roost') with a specific verb and resource. It distinguishes itself from siblings by explicitly mentioning `upload` and `convert` as alternatives for different use cases, making the tool's unique scope evident.

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 clear usage guidance: it warns that this is 'Advanced' and most agents should use `upload` or `convert` instead. It also specifies the required parameters (`tenantId`, `workerName`, `script`), giving direct instructions on when and how to invoke the 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 discloses TTL of 10 minutes, invalidation of the previous code on repeated calls, and the need to render pairingUrl as a QR. These are substantive behavioral details not present in the annotations, which only indicate flags. 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 three sentences, front-loaded with the core action, and every sentence adds meaningful operational detail without redundancy or 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?

Despite having no output schema, the description mentions pairingUrl, references poll_pairing and whoami for context, and covers side effects and usage conditions. For a single-parameter tool, this is complete enough for an agent to select and invoke 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?

Input schema covers 100% of parameters with 'tenantId' described as 'Tenant id from hatch response.' The description does not add parameter-specific syntax or additional semantics, so the 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?

The description uses a specific verb ('Issue') and names the resource ('pairing code + URL'), explicitly stating the purpose for claiming a tenant or authorizing a new agent session. It also distinguishes itself from the sibling 'whoami' by saying 'Prefer this over whoami.'

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 guidance: 'Prefer this over whoami when starting a pairing flow' and provides the exact condition for when not to call again ('until poll_pairing returns expired/completed'). It also warns about repeated calls invalidating the previous code, which is clear exclusionary 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?

Beyond the annotations (readOnly=false, openWorldHint=true, idempotent=false), the description discloses the return shape, the presigned upload flow for manifest mode, the cost implication of inline site mode, and hard limits like 1.5 MiB script size with no base64 binaries. This is substantial behavioral context that the sparse 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?

The description is front-loaded with the core purpose and return value, immediately warns about the biggest misuse (calling twice), and then presents four modes in a scannable list. Every sentence adds information without repeating the schema, making the length justified.

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 supplies the response fields ({ tenantId, slug, url, apex, uploads? }) and tells the agent what to do with them. It also covers the main invocation pathways, connects to sibling tools, and explains token and binary constraints, making it complete for a complex multi-mode creation 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?

Even though schema description coverage is 91%, the description adds significant cross-parameter meaning. It explains when to pass manifest versus site versus script, how apex is chosen from user intent, and warns against invented apexes, which the flat schema alone does not convey.

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 'Create a NEW site (a 'roost') and return its public URL in one call', giving a specific verb and resource. It distinguishes itself from sibling tools like convert and upload by explicitly saying 'NEVER call hatch twice' and by framing the four creation modes.

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: use convert for rename/tier changes, use upload/deploy for content updates, and never call hatch twice. It also breaks down the four calling modes with clear recommendations, such as preferring manifest for projects with assets and using site only for tiny text-only sites.

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 readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds the return shape, the ability to resolve by slug or tenantId, and the intended use for state recovery, providing useful behavioral context beyond 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 three concise sentences, front-loaded with the action and return value. Every sentence adds value with 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 simple 2-parameter tool with strong annotations, the description includes the use case, the return format, and the parameter roles. Despite no output schema, it specifies the exact fields in the return view, making the tool's behavior fully understandable.

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 gives a description for slug but not for tenantId. The description clarifies that both are alternate identifiers and that the return includes tenantId, giving purpose to the tenantId parameter. It partially compensates for the missing schema description by implying the relationship between slug and 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?

The description clearly states the tool resolves a roost by slug or tenantId, using a specific verb and resource. It distinguishes itself from siblings by focusing on a read-only lookup that returns a compact view with a specified set of fields.

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 states when to use this tool: to recover state across turns when the user mentions their site without providing tenantId. This provides a clear use case and implies it should be used when you need context about a site.

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?

While annotations already declare readOnlyHint and destructiveHint, the description adds useful behavioral context: it reveals that the tool blocks until the owner makes a decision ('Returns the result once the owner approves or denies'). This goes beyond the annotations and helps the agent understand the polling behavior and the blocking nature of the call.

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 short sentences, starts with the action verb 'Poll', and contains no redundant information. It is concise and well-structured.

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 polling tool with two parameters, the description covers the core behavior well enough. It explains what it polls, when it returns, and the trigger for completion. However, it does not explain what a 'Tier-2 phone approval' is or how the returned result is structured, though the lack of an output schema makes the return format less critical.

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

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

The input schema provides no descriptions for the parameters (0% coverage), and the description does not mention approvalId or tenantId at all. The agent is left to infer their meanings solely from the names, which is insufficient, especially since the description adds no parameter-level context.

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 identifies the tool's purpose with a specific verb ('Poll') and resource ('pending Tier-2 phone approval'), distinguishing it from sibling tools like poll_decision and poll_pairing. It also states the outcome ('Returns the result once the owner approves or denies'), which is unambiguous.

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 clear context that this tool is for polling Tier-2 phone approvals specifically. However, it does not explicitly state when to use this tool over similar siblings like poll_decision or await_decision, nor does it mention any exclusions or 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?

Beyond the annotations (read-only, idempotent, non-destructive), the description discloses the long-poll duration, exact exit conditions (pending_review left), the complete set of return statuses, and the included response fields. This gives a rich operational contract that annotations alone 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?

The description is compact and front-loaded with the core purpose ('Long-poll (~20s) until...'). Every clause adds value: timeout, exit condition, return values, and response contents. No filler or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 2-parameter polling tool, the description covers the essential behavior and output. It lacks guidance on how to interpret each status for next actions and does not clarify the relationship to similar sibling tools, but the core polling workflow is well specified.

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

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

The input schema has 0% description coverage, and the description itself does not mention tenantId or decisionId. Although the parameter names are self-explanatory, the description adds no additional meaning or guidance about formats, constraints, or relationships, failing to compensate for the lack of 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?

The description uses a specific verb ('Long-poll') and resource ('decision') with a clear state transition ('leaves pending_review'). It also enumerates distinct return values, which distinguishes it from sibling polling tools like await_decision 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?

The description clearly conveys when to use the tool: to wait for a decision to resolve, with a ~20s timeout. However, it does not explicitly mention alternatives or when not to use it, leaving some sibling differentiation to the reader.

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, destructiveHint=false, so the operational safety is clear. The description goes far beyond, adding the ~20s blocking wait, status set, storage requirements, token lifetime, connector binding, and a caveat about device claim vs billing upgrade. This is rich behavioral 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 a dense paragraph, but every sentence carries actionable information (timeout, statuses, storage, refresh guidance, server binding, tenantId, caveat). It is front-loaded with purpose and not wasteful, though a bulleted format might improve scannability.

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 must convey return semantics and workflow. It covers all statuses, the ~20s wait, storage/refresh duties, token binding, and a warning about billing implications. The tool is adequately described for an agent to use it correctly in 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 coverage is 100%, so both parameters are documented. The description adds value by specifying the source of the code (get_pairing_code/whoami) and clarifying that tenantId improves lookup after approval—detail that is helpful beyond the schema's description.

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?

Clearly states it polls for pairing completion in Device-Grant style, and enumerates possible statuses (pending/completed/expired/not_found). This distinguishes it from sibling poll tools, which are not mentioned but the specific resource and style make the purpose unambiguous.

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 guidance on when to use this tool (after getting pairing code, waiting for phone approval) and what to do with the result (store tokens, call refresh_session on expiry). It names refresh_session as a follow-up alternative but does not explicitly exclude other poll tools like poll_approval; still, the context is 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 annotations (all false, no safety hints), the description thoroughly discloses behavioral traits: the token's ~1h validity, the 7-day grant lifetime, refreshToken rotation on each refresh, the need to store the new token, and the fingerprint mismatch condition that requires re-pairing. This is comprehensive and actionable.

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, each earning its place: purpose, expiration/alternative, and rotation/session requirements. It is front-loaded with the primary action and contains 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?

Despite having no output schema, the description fully addresses the tool's complexity: token lifetime, grant lifetime, rotation, session binding, failure mode (fingerprint mismatch), and recovery path (re-pair). It even implies the response contains a new token to store. This is complete for a session-refresh 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 coverage is 100%, so parameters are already documented. The description adds valuable context by specifying that refreshToken comes from poll_pairing and notes the rotation behavior, while tenantId is tied to hatch/poll_pairing. This enhances understanding beyond the schema definitions.

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 (~1h) using the refreshToken from poll_pairing.' This is a specific verb+resource combination that distinguishes it from sibling tools like get_pairing_code and poll_pairing, which are explicitly mentioned as alternatives.

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: when to use (renew short-lived token), when to re-pair instead ('after that, re-pair via get_pairing_code'), and the requirement for the same MCP-Session-Id. It also names specific alternative tools, making the when/when-not distinction 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?

The description adds meaningful behavioral context beyond annotations: the link is signed, expiring, works for any tier, and returns a specific object shape. It also clarifies the auth context ('without forever-tier password auth'). It does not, however, disclose prerequisites like sessionToken or potential side effects of issuing multiple links.

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 concise sentences with a clear front-loaded purpose. Every phrase adds value, including the use case and return format, with no redundant or filler content.

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 tool's core function, usage context, and return value, which is good given no output schema. However, the lack of parameter semantics and any mention of error conditions or prerequisites makes it only partially complete for an agent to invoke confidently.

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 has 0% description coverage, and the description provides little direct parameter guidance. It indirectly references expiresSeconds via 'expiring' and the response's expiresAt, but tenantId and sessionToken are not explained at all, leaving an agent to guess their roles.

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 ('Issue') and resource ('signed, expiring guest view URL'), clearly distinguishing it from sibling tools like auth or deploy. It also includes the exact query parameter format (`?vt=…`), making the tool's function unambiguous.

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 states a key use case: 'Use for private run reports without forever-tier password auth.' This provides clear context for when the tool is appropriate, though it does not explicitly name alternatives or exclusion criteria.

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 behavioral context beyond annotations: it discloses that the tool returns presigned PUT URLs, requires direct HTTP upload, and that files go live immediately on PUT completion with no separate publish call. The annotations (readOnlyHint=false, destructiveHint=true) are consistent with the mutation described. No contradictions.

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—four sentences that cover purpose, workflow, return value, and timing. It front-loads the core action and uses a concrete curl example, making it efficient and informative.

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 appropriately explains the return value (presigned URLs per file) and the delivery mechanism. It also provides critical timing information ('go live immediately') and the intended post-regeneration context. Minor gaps like error handling or what happens on partial failure are not covered, but for a tool with moderate complexity this is 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?

The description calls out tenantId and manifest with path/size/contentType, which mirrors the schema, but does not explain sessionToken or expiresSeconds beyond their schema descriptions. Since schema coverage is 75%, the description adds modest clarity on the manifest structure but relies on schema for the rest. Overall it doesn't significantly exceed the schema's parameter documentation.

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 phrase 'Add or replace files on an EXISTING roost' and distinguishes from sibling tools by noting Hatch does not schedule regenerations and this is for after local regeneration. This clearly identifies the tool's function and separates it from deploy/hatch.

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 states an explicit use case: 'Use after regenerating a dashboard locally; Hatch does not schedule regenerations.' This tells the agent when to invoke this tool. It also implies not for creating new sites by emphasizing 'EXISTING.' It doesn't explicitly name alternative tools, but gives clear contextual 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?

While annotations already indicate readOnly and idempotent, the description adds substantial behavioral detail: never errors when unidentified, returns a pairing path, server-side session binding, sessionExpiresAt (~1h), grantExpiresAt (~7d), and sessionExpired handling. This is valuable beyond 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 dense but well-structured, front-loading the purpose and then providing sequential, non-redundant behavioral notes. Every sentence contributes essential functionality, staying within a reasonable length.

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 listing return fields (sessionExpiresAt, grantExpiresAt, sessionExpired) and explaining failure/edge behavior. It also references sibling tools and tie-in to poll_pairing and refresh_session, making it fully self-sufficient for 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?

Input schema already covers both parameters (tenantId, sessionToken), and the description enriches them by explaining when to pass sessionToken (connectors that cannot set Authorization headers) and how tenantId relates to re-pairing. This adds meaning beyond 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?

The description explicitly states 'Return the caller's current identity and tenant state,' a specific verb+resource. It distinguishes itself from siblings like poll_pairing and refresh_session by referencing the pairing flow and session renewal, making its unique role clear.

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 concrete usage context: when to call after poll_pairing, how to handle unidentified states, and when to delegate to refresh_session on sessionExpired. This effectively guides selection among the sibling tools.

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