Pane

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

Discloses behavioral traits beyond the annotations: whoami has no network call or secrets, claim is one-way, and logout only clears local state without revoking on the relay. The annotations are all false, providing no safety signals, so this context is valuable.

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 opens with the tool's purpose, then lists actions in a structured way. It is somewhat lengthy but each clause adds necessary detail. No filler text.

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 all actions, their side effects, and alternatives. It even describes the return value for whoami, which is useful given no output schema. Complete for a three-action tool with two parameters.

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

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

The input schema already provides full descriptions for both parameters (100% coverage), including detailed action semantics. The description adds little beyond what the schema's action enum already documents, such as the Settings UI origin for the code, but this is also present in the schema. 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 clearly states 'Agent identity and binding' and enumerates the three actions (whoami, claim, logout) with specific behaviors. It distinguishes from siblings by referencing the `key` tool's revoke action for logout's non-revocation.

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

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

Explicitly states that logout does not revoke the key on the relay, directing the user to the `key` tool's revoke action for that purpose. Also clarifies whoami makes no network call and claim requires a one-shot code from the Settings UI.

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 say destructiveHint=true, but the description discloses far more: audit is read-only and computed from stored manifests, delete is an idempotent soft-delete, wake is a no-op that reports status, share_link_rotate revokes the old link, domain_set makes the first domain serve and later ones redirect, and domain_remove without domain removes all. This is exactly the kind of behavioral context that goes 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?

The description is a single dense paragraph with a run-on structure, making it hard to scan. While every sentence adds value, it lacks front-loading and would benefit from a structured list of actions. It is adequately informative but not concise or well-structured enough for a 5.

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

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

Given the tool's complexity (10 actions, 10 parameters, no output schema), the description covers all actions, edge cases, and domain-specific behavior (e.g., audit severity explanations, domain aliasing, timezone defaults). It is complete enough for an agent to select and 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 coverage is 100% with detailed parameter descriptions already present. The tool description adds little parameter-specific meaning beyond what the schema provides; any extra nuance (e.g., domain_remove omitting domain removes all) is also present in the schema. 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 clearly states it covers the v2 app lifecycle apart from creation and redeploy, explicitly naming deploy_app as the sibling covering those. It enumerates all actions (list, show, audit, update, etc.) with their specific resources, making the tool's purpose unmistakable and distinct from deploy_app.

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 directs deploy_app for creation/redeploy, providing an alternative. For each action it gives context on when to use it (e.g., audit for security review, domain_set for custom domains) and even advises reading the app before proposing a fix, which is strong when-to-use 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 annotations (readOnlyHint=false, destructiveHint=true), the description discloses SSRF guards, soft-delete semantics, token shown-once behavior, byte-sniffing with mime misstatement being caught, and backend-specific error conditions. This adds substantial contextual detail without contradicting 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?

Although long, the description is dense with essential information: cost model, security constraints, backend dependencies, and per-action behavior. It opens with the core resource, then moves to the most consequential decision (upload cost), and proceeds logically through each action—high signal density with no filler.

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

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

With 11 actions, 17 parameters, no output schema, and numerous operational constraints, the description covers all actions, key return shapes (put_url, base64, metadata-only), failure modes, and security safeguards. It is complete enough for an agent to correctly select and invoke any action.

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 every parameter has a highly detailed description, so the baseline of 3 applies. While the tool description reinforces critical choices like content_base64 vs file_path, it does not add meaning significantly beyond the schema's own strong explanations.

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 opening sentence identifies the resource (binary attachments) and the exact format they're referenced by, then enumerates all 11 actions. This clearly distinguishes the tool from sibling operations like row access or row manipulation.

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 decision guidance on upload path selection based on cost, with clear trade-offs among inline, fetch, and presign+finalize. It also states prerequisites (presign requires Azure, file_path requires relay-local file) and notes when fetch applies to any backend.

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 goes well beyond annotations, disclosing privacy consequences of publishing (seed rows become public), idempotence of unpublish, install isolation, upgrade refusal conditions, and attestation requirements. These are valuable behavioral details not expressed in readOnlyHint/destructiveHint, with 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 long but organized by action, front-loaded with an overview. It is somewhat verbose and repeats content from the action parameter description, but for a multi-action tool with 12 sub-actions, the structure is appropriate and every part serves a purpose.

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

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

The main description omits the upgrade_check/upgrade/revert actions from its initial action enumeration and does not explain return values (no output schema). Those gaps are partially filled by the action property description in the schema, but the main description still leaves a coverage gap for a significant subset of actions.

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

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

With 100% schema coverage, the baseline is 3. The description adds meaningful parameter relationships such as the slug/version interplay for republishing, the distinction between config and upload values, and snapshot_id ownership semantics. Though it does not systematically document every parameter, it clarifies how key parameters interact.

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 scope: publishing an app as a community template, unpublishing, installing, and operator review actions. It enumerates the specific actions and distinguishes this from sibling tools like 'publisher' and 'review' by centering on the community template lifecycle.

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 for each action: when to use publish vs unpublish, that list_pending/approve/reject are for relay operators, and that install creates a fresh private copy. However, it does not explicitly name alternatives or state 'use this instead of X' for overlapping sibling tools like deploy_app or publisher.

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

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

Beyond the annotations (destructiveHint, readOnlyHint), the description reveals critical behavioral traits: never returns secrets, create returns metadata only, delete is idempotent, consent_url builds rather than fetches, and new OAuth2 connections start in pending_auth until owner approval. This adds substantial contextual value not present in annotations.

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

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

The description is two dense paragraphs with a clear structure: first defines the resource, then elaborates actions and lifecycle. Every sentence contributes meaning (security, idempotency, consent flow), and the length is justified for an 18-parameter tool. It is front-loaded with the core concept.

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 no output schema, the description explains return behavior for create/list (metadata, fingerprint, never secret), consent_url (returns URL), and the pending_auth lifecycle. It does not cover error cases or pagination, but for a complex tool with thorough schema descriptions, it is largely complete.

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

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

Schema description coverage is 100%, and each parameter already has detailed descriptions. The tool description adds high-level context (e.g., allowed_host as exfiltration defense, kind-specific fields) but does not materially alter or augment the per-parameter semantics beyond what the schema provides. 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 precisely defines the resource—'a v2 app's Connections: the stored credential... bound to a host'—and enumerates the actions (create, list, delete, consent_url) with operational specifics. It clearly distinguishes this from sibling tools by emphasizing host-binding and secret-exfiltration defense, which is unique to this tool.

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

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

The description gives explicit usage guidance: 'There is no update action: change a connection by deleting and recreating it' and explains when consent_url is appropriate ('a human-in-a-browser step an agent key cannot complete'). It does not directly name alternative tools but provides clear contextual and 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?

Annotations only declare readOnlyHint=true and openWorldHint=false. The description adds substantial behavioral context beyond these: the countRead opt-in gate, independence from the read list, the refusal error collection_count_forbidden, the '3 spots left' use case, and the exact return shape { count }. This is exactly the kind of behavioral disclosure that helps an agent anticipate outcomes. 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 long and front-loaded with the core purpose. Each additional clause adds behavioral detail. The spec reference 'spec B4, issue #1056' is potentially unnecessary for an AI agent and adds noise, but it does not harm usability. Overall, it is dense yet efficient.

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 explicitly explains the return value ({ count }) and the error condition (collection_count_forbidden). It covers scope (whole-scope, no filter/paging), permission nuances, and the difference from list read access. This is sufficient for an agent to know when and how to call the tool safely and correctly.

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

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

The input schema has 100% description coverage for both parameters (app_id and collection). The tool description adds minimal parameter-specific meaning beyond the schema, such as 'v2 app's collection', but does not elaborate on accepted formats or edge cases. Baseline 3 is appropriate because the schema already carries the semantic load.

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 and resource: 'live row count of a v2 app's collection'. It also explicitly scopes the operation as 'whole-scope total with no filter and no paging', which distinguishes it from row-listing operations like list_rows. The spec reference (B4, #1056) adds precision.

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: it is a whole-scope total, has no filter or paging, and is gated by the countRead opt-in. This implies when to use it (for counts only) and when it might not work (if opt-in is absent). However, it does not explicitly name alternative tools or provide a direct 'when not to use' statement.

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 indicate destructiveHint=true and readOnlyHint=false, but the description goes far beyond these by disclosing that tokens are shown only once and only hashes are stored, that pause is reversible while revoke is permanent, that rotate overlaps the old token, and that effective permissions are always the intersection with owner authority. It also explicitly states service credentials cannot access these actions, fully aligning with annotations and adding essential 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 single dense paragraph that is information-rich with no fluff, but it could benefit from structured bullet points or short paragraphs for each action. Every sentence serves a purpose, though the lack of visual structure makes it slightly harder to scan quickly. It is appropriately sized for the tool's complexity.

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

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

Given the tool's complexity (6 actions, security nuances) and the absence of an output schema, the description thoroughly covers return behaviors (e.g., raw token shown once, list returns allowlist/status, rotate issues fresh token), side effects (pause/resume/revoke semantics), and access restrictions. It explains the security model of credential narrowing and the fact that credentials cannot self-manage, leaving no critical gaps for an agent to select and invoke the tool correctly.

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

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

The input schema already provides rich descriptions for all parameters (100% coverage), so the baseline is 3. The description adds meaningful semantic context beyond the schema, particularly for 'mode' and 'grants' by explaining how they affect the credential's reach and the intersection permission model. However, some parameters like ttl_seconds, overlap_seconds, and members are only described in the schema, not in the tool description, so it doesn't fully compensate but still adds value.

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 as managing v2 app's scoped service credentials and enumerates all six actions (mint, list, pause, resume, rotate, revoke) with specific outcomes. It distinguishes this tool from potential siblings by emphasizing the scoped/bearer-token model and owner-only access, making the purpose unmistakable.

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

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

The description explains when to use each action (e.g., mint for creating a credential for a backend, rotate for issuing a fresh token with overlap, revoke for permanent removal) and clarifies the access restriction (owner-or-owning-agent only). It does not explicitly name alternative tools or state when not to use this tool, but the context strongly implies its intended use case.

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?

Goes far beyond the annotations by explaining the soft-delete tombstone behavior, 30-day recoverability, live change feed event (op:delete), and the exact return value. This is critical context since destructiveHint=true alone might imply permanent deletion, but the description clarifies it's recoverable.

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 carrying distinct value: the core action, recovery semantics, and conditional parameter use with return value. Front-loaded with 'Soft-delete' and free of fluff 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?

The description covers the essential aspects: what the tool does, how it behaves (soft vs hard delete), how to undo, how to observe via change feed, how to use optimistic locking, and what to expect as output. With no output schema, this is a complete picture 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?

Schema coverage is 100%, so the description doesn't need to explain basic parameters like app_id and collection. It adds value by explaining the purpose of if_match ('optimistic-locked delete') and the shape of the response, which are 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: 'Soft-delete a row from a v2 app's collection.' It clearly distinguishes itself from sibling tools like get_row, update_row, and restore_row by explicitly referencing restore_row and list_deleted_rows, making its unique role obvious.

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 the tool and related alternatives: it notes the deletion is recoverable via restore_row and points to list_deleted_rows for viewing deleted rows. It also instructs when to use the optional if_match parameter for optimistic locking, offering clear context.

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

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

Beyond annotations, it discloses the compat gate with force bypass, atomic asset validation, that dry_run returns a report without mutating anything, that html_path is read on the MCP-server host, and that removed collections are detached rather than deleted. This is substantial non-obvious behavior.

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

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

The description is long but well-organized into thematic paragraphs: core semantics, manifest keys, create/redeploy, compat gate, assets, and return values. While it could be condensed, most sentences contribute; the structure aids readability for a complex 10-parameter tool.

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

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

Despite no output schema, it documents return shapes for create and redeploy. It covers prerequisites (manifest grammar via get_skill), constraints (2 MB cap, html_path host-bound), edge cases (force, clearing assets), and validation behavior. The description is self-sufficient for correct invocation.

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

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

Schema coverage is 100% with descriptive parameter documentation, so baseline is 3. The description adds redeploy-specific semantics like 'Every content field is optional when app_id is given' and the meaning of 'assets: []' to clear the set, and clarifies precedence of inline html over html_path, adding value 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 opens with 'Deploy a v2 app: an HTML document plus a capability manifest, hosted at its own URL,' which clearly states the action and resource. It also distinguishes between create and redeploy by app_id, separating it from sibling tools like apps (management) and attachments (upload).

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 explains when to use create (no app_id) vs redeploy (with app_id), when to use html_path instead of inline html for locally-run connectors, and dry_run for validation without mutation. It also says 'omitting all three is refused' and points to get_skill for manifest grammar, providing alternatives and exclusions.

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

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

With all annotations false, the description carries the full burden. It discloses that the operator sees the row, not the session, that there is no reply channel, that duplicates cost triage, and gives detailed requirements for an actionable message. This goes beyond the schema.

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 information-dense, with no fluff. Each paragraph adds unique value: scope boundaries, duplicate policy, message composition, and parameter semantics. The main purpose is front-loaded in the first sentence.

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 no output schema, the description covers return behavior (list newest first, paginated by `before`), all param semantics, and operational expectations (no reply channel, duplicate handling). It is comprehensive for a reporting tool with moderate complexity.

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 enriches parameters: it defines each `type` enum ('bug for something broken, feature for something missing, note for a rough edge'), explains `app_id` scopes to one app, and `before` as pagination cursor. It also clarifies the `action` parameter's effects.

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 first sentence explicitly states the tool 'Reports a problem with homespun itself to the relay operator, and lists what this agent has already reported,' naming the resource (homespun problems) and actions (create/list). This distinguishes it from sibling tools like `taste` or `deploy_app` by scope.

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 scope: it lists what is in scope (5xx, error codes, disagreements, platform issues) and out of scope (human's task, authored app bugs, presentation preferences – which it says belong in `taste`). It also instructs to use `list` to check duplicates before creating a report.

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 long-poll behavior, cursor mechanism, and resync condition. Describes return shape ({ entries, cursor, truncated }). Annotations indicate readOnlyHint=true, which aligns. 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?

Description is a single paragraph well-structured: purpose, loop logic, optional parameters, error handling, return shape. No wasted words; every sentence adds value.

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 no output schema, the description covers return shape, error condition, and complete usage pattern. Handles complexity of polling pattern and parameter interaction thoroughly.

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. Description adds value by explaining parameter interaction in the polling loop (e.g., 'since' as cursor, 'wait' for long-poll) and the resync behavior, though it repeats some 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 clearly states the tool polls a v2 app's change feed for row creates, updates, and deletes. It uses specific verbs and distinguishes from sibling tools like list_rows by focusing on the change feed.

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 instructions: call without 'since' first, process entries, keep cursor, then call with 'since'. Explains long-poll with 'wait' and when to fall back to list_rows on resync_required.

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=true, so the description adds value by disclosing the route method (dedicated relay route vs. client-side scan) and the return format with error handling, providing 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?

Two sentences, front-loaded with action, no wasted words. Every sentence contributes meaningful 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?

For a simple read-only tool with 3 required parameters and no output schema, the description fully covers functionality, route method, return format, and error case, making it complete.

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

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

Schema coverage is 100% with parameter descriptions provided. The description does not add significant meaning beyond the schema, 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?

The description clearly states the verb 'Fetch', the resource 'a single row by its key from a v2 app collection', and distinguishes the tool from siblings by mentioning the dedicated relay route and specific return format.

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?

While the purpose is clear, the description does not explicitly state when to use this tool versus alternatives like list_rows, update_row, or delete_row. It implies usage for direct key-based access but lacks explicit when-not or alternative 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, and the description reinforces this by stating no API key needed. It discloses what the tool returns (full SKILL.md or version string) and the content of the guide, adding value beyond the annotations without contradiction.

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

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

Three well-structured sentences: first describes the resource, second states prerequisites, third gives usage with the parameter. No fluff; every sentence serves a purpose.

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

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

For a simple read-only tool with one optional parameter and no output schema, the description covers all needed context: what it returns, why you'd use it, how the parameter works, and that no authentication is needed.

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% for the single boolean parameter, providing a baseline of 3. The description adds extra context: 'to tell whether a cached copy is current', which helps the agent understand the parameter's utility.

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 it retrieves the relay's SKILL.md guide covering events vs records, schema grammars, and poll loop. This distinguishes it from all sibling tools which are other operations (agent, apps, etc.).

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

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

The description explicitly says 'Needs no API key' and suggests using it when working out how tools fit together or to refresh a cached copy. It also explains the version_only parameter purpose, giving clear guidance on when to use which variant.

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 important behavioral traits beyond annotations: grant_url is shown once and unrecoverable, list never returns tokens, revoke is idempotent, and the subtle edge case where a write-only pinned grant can read existing row data. These details add significant value even though annotations already mark destructiveHint=true and idempotentHint=false.

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

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

The description is a dense paragraph but each sentence carries unique information. It could be formatted with bullet points for easier scanning, but it is not padded or redundant—every clause contributes to understanding.

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?

Even without an output schema, the description explains key return behavior (mint returns grant_url in #g= fragment, list returns links but never tokens). It covers all actions, modes, pins, and a security-relevant edge case, making it nearly complete for an agent to 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?

Although schema coverage is 100%, the description adds extra meaning beyond the raw parameter descriptions: it clarifies mode behavior (once claimed by first browser, multi capped by max_uses), explains that pins narrow access, and highlights the write-only grant dedup consequence. This goes beyond what the schema alone communicates.

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 what the tool does: manages app grant links, which are capability URLs conferring declared custom roles. It enumerates the three actions (mint, list, revoke) and explicitly notes that grants do not escalate to owner/member/agent, distinguishing it from any 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?

The description provides clear context for when to use each action (mint vs list vs revoke) and explains mode semantics (once vs multi) and pin limitations. It doesn't explicitly name alternative tools, but none of the siblings overlap, so the guidance is sufficient for an agent to decide.

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 (readOnlyHint=false, destructiveHint=true), the description extensively discloses behavioral traits: rotate invalidates the old URL immediately without redeploy, set_signing_secret returns a minted secret only once and never echoes stored secrets, clear_signing_secret removes the signing secret, and signature verification currently 'ships dark' (nothing verifies a signature). This provides substantial context that annotations alone do not cover, with 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 longer than average but well-structured: it opens with a definition, then explains the manifest/deploy constraint, and then breaks down each action. Every sentence contributes meaningful context (e.g., external system examples, behavior on rotate, dark signature). Some redundancy with the schema's action descriptions exists, but it does not feel bloated for the tool's 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?

Given the tool's complexity (5 parameters, 4 actions, no output schema), the description is remarkably complete. It explains what each action returns (URL once, secret once), the lifecycle (no create/delete, secrets not echoed), and the current limitation of signature verification. It covers edge behaviors (old URL stops immediately, grace_seconds for rotation) sufficiently for an agent to invoke it correctly without an output schema.

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

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

The input schema already covers all parameters with high detail (100% coverage), so baseline is 3. However, the description adds clarifying context about the difference between URL secret and signing secret, and explains the 'secret' parameter's two paths (omit to mint vs pass to store verbatim), which enhances understanding beyond the schema. It doesn't introduce new parameter syntax but improves semantic comprehension.

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 manages a v2 app's inbound catch-hooks, with a clear resource (inbound-webhooks) and specific actions (list, rotate, set_signing_secret, clear_signing_secret). It distinguishes from siblings by focusing on webhook URL management and signing secrets, and clarifies it has no create/delete. This is a specific verb+resource that 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 gives explicit usage context: 'After deploying a manifest that declares a hook, list is what yields the exact URL to paste into the external system.' It also states when not to use the tool ('no create or delete') because hooks are declared in the manifest and materialized at deploy. This provides clear when/when-not guidance, and while no alternative sibling is named, the exclusion is sufficient for this unique 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?

Despite annotations indicating destructiveHint, the description adds crucial behavioral details: revoke is irreversible and requires confirm:true, mint returns the raw value only once and it becomes non-retrievable, and the sibling key appears in later lists. It also clarifies that identity comes from the caller's token, preventing targeting others.

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

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

The description is a single long run-on paragraph containing many details. While all information is relevant, the lack of structured bullet points or clear separation between actions reduces readability and conciseness.

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 all aspects needed for operation with no output schema: what list returns, what mint returns and its one-time-only caveat, revoke's requirements, identity derivation, and security constraints. It is fully self-contained for an agent to invoke actions correctly.

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

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

The input schema already has 100% coverage with descriptions for both 'action' and 'confirm' that mirror the tool description. The description does not add new semantic meaning beyond the schema, 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 clearly states the tool manages the calling agent's API key with three specific actions: list, mint, and revoke. It distinguishes itself from sibling tools by focusing on API key lifecycle operations, using specific verbs and resources.

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 scenarios for each action: mint is for handing a CLI or child process a credential, revoke is for irreversible destruction requiring confirmation, and list is for key info. It also states what cannot be done ('mint cannot target another agent's id'), offering clear when-to-use and limitations.

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 (readOnlyHint, idempotentHint, destructiveHint), the description discloses key behaviors: soft delete, recoverable_until (30 days default), purged rows with purged:true that cannot be restored, and independence from read permissions. This significantly enriches the agent's understanding of what to expect.

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

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

The description is a single, well-structured paragraph that front-loads the primary purpose, then adds relevant details (recovery, permissions, purged status, return format). Every sentence adds value without unnecessary verbosity.

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 explains the return shape '{ rows, next_before }' and the purged flag. It covers access restrictions, recovery window, and a key behavioral nuance (purged rows cannot be restored). For a list operation with good annotations, 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?

Schema description coverage is 100%, so the input schema fully documents app_id, collection, limit, and before. The description adds context about the 'next_before' cursor in the return value but doesn't need to explain parameters further. Baseline 3 is appropriate since the schema carries the parameter semantics.

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

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

The description clearly states the tool's purpose: 'List a collection's recently deleted rows: the recovery bin.' It identifies a specific verb (list), resource (deleted rows), and scope (a collection), and distinguishes it from sibling tools like list_rows and restore_row.

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 useful usage context: 'Owner or agent only, and deliberately independent of the collection's read permissions.' It also explains the soft-delete behavior and the 30-day recovery window, which helps the agent know when this tool is appropriate. It doesn't explicitly name alternatives, but the context implies when to use it over list_rows.

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 and openWorldHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond these annotations: MCP has no streaming, the tool doubles as a poll mechanism, and the `since` cursor returns only new or changed rows. This meaningfully clarifies the tool's runtime behavior and pagination contract.

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

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

The description is three sentences long and every sentence earns its place: the core operation, the critical polling behavior, and the return shape. It is front-loaded with the primary purpose and contains no filler or redundant restatements of the title or annotations.

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 moderate complexity of cursor-based pagination and polling, the description is complete: it states the return fields, explains how to use `since`, and notes the mutable-collection context. With readOnlyHint and a 100%-covered schema, no critical gaps remain for an agent to invoke the tool correctly.

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

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

Schema coverage is 100%, providing baseline parameter descriptions for all four fields. The description goes beyond the schema by giving `since` rich semantic meaning (poll handle, prior next_cursor, 'only rows that are new or changed'), and by clarifying the response structure ({ rows, next_cursor, has_more }). This adds real value over the schema alone.

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: 'List rows in a v2 app's mutable collection', which clearly identifies the operation and scope. It also differentiates itself from sibling tools like get_row (single row) and list_deleted_rows by focusing on the mutable collection and adding a polling use case.

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 explains when to use the tool for polling ('This is also how a collection's current state is polled') and how to leverage the `since` cursor for incremental fetches. It does not name alternatives or exclusions (e.g., when to use list_deleted_rows instead), but the context is clear enough for most selection scenarios.

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 side effects such as remove being idempotent and revoking live sessions, set_role leaving sessions intact, add attaching immediately if a Human exists else sending a magic-link invite, and roles reporting separate effective access for members vs grant-link holders. This adds substantial 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 single dense paragraph, front-loaded with the purpose and then breaking down each action. Every clause carries unique information, but the length may challenge skimming; still, it is efficient with no filler.

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

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

For a 6-parameter, 5-action tool with no output schema, the description covers each action's behavior, side effects, limitations, and edge cases (owner immovable, session invalidation, role floors). It provides enough guidance to invoke any action correctly.

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

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

The input schema already provides detailed descriptions for all parameters with 100% coverage. The description partly restates these semantics (e.g., email attach vs invite) without adding much beyond the schema. There is a minor inconsistency: the description says set_role clears 'when null' while the schema requires an empty array, so no extra value is provided.

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 this tool manages a v2 app's membership, enumerating each action (add, list, set_role, remove, roles) with specific verbs and resource scoping. It distinguishes itself from sibling tools like grants by focusing on app membership and access control.

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 recommends set_role over removing and re-adding for re-roling, and notes that the app owner cannot be removed or re-roled, giving concrete usage guidance. It doesn't systematically list when not to use each action, but the key exclusions and alternatives are covered.

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 reveals key behavioral traits beyond the annotations: one-time use for claim, permanence of the handle, refusal of reserved/taken handles, email verification requirement, the provisional `maker-...` handle renaming, and that update can happen 'at any time'. This greatly enriches the agent's understanding of side effects and restrictions.

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?

At roughly 120 words, the description is compact yet information-dense, front-loading the resource identity before detailing actions. The semicolon-separated structure is efficient, though it could be improved with bullet points for readability. Every sentence adds value.

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 purpose, prerequisites, constraints, and get's return fields (handle, claimed status, tenure, counters). It does not specify the return values for claim or update actions, and there is no output schema, so that is a minor gap. Overall it is complete for a complex multi-action 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 100%, so a baseline of 3 applies, but the description adds meaningful action-level semantics: it explains what get/claim/update do, the handle format and permanence rule, and which fields update modifies. This goes beyond the schema's parameter descriptions, though it doesn't explicitly mention that null clears fields (already in 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 clearly defines the resource as 'the caller's community publisher identity: the @-handle and public profile shown in the template gallery' and enumerates three distinct actions (get, claim, update) with specific behaviors for each. This explicitly distinguishes it from sibling row-management tools by focusing on the publisher profile.

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

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

The description gives clear context for when to use the tool (managing the caller's publisher identity) and discloses prerequisites ('claim and update require a verified email') and constraints ('may be used only once', 'handle is permanent'). It does not explicitly name alternative tools or state when not to use this one, but the unique resource scope makes usage obvious.

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 (readOnlyHint=false, idempotentHint=false, destructiveHint=false), the description adds rich behavioral context: the row returns with original data and creator, version is bumped, only owner/agent can restore, specific error codes are listed (restore_expired, restore_conflict), and it explicitly states the return shape as { row }. 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 four sentences, front-loaded with the core purpose, and packs substantial detail (behavior, authorization, errors, return) without redundancy. Every sentence earns its place.

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

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

Despite having no output schema, the description fully explains what the tool does, how to find inputs, what the return looks like, under what conditions it fails, and who can call it. It is complete for a mutation tool with 3 parameters and no output schema.

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

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

The input schema already covers all three parameters with 100% description coverage. The description adds practical semantics by tying the 'key' parameter to list_deleted_rows, which helps the agent select valid values. App_id and collection are straightforward and schema-described, so this is a modest but meaningful addition over the baseline.

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 restores a soft-deleted row, explicitly connecting it to 'undoing delete_row'. It distinguishes itself from siblings like list_deleted_rows, delete_row, update_row, and upsert_row by specifying the exact action and resource.

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 explicit guidance on when to use: 'Find restorable keys with list_deleted_rows' tells users how to locate valid inputs, and 'Owner or agent only' states an authorization prerequisite. It also covers when the tool will not work via failure conditions like restore_expired and restore_conflict.

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 goes well beyond the annotations (readOnlyHint=false, destructiveHint=true). It discloses critical behavioral details: requires a verified email, exactly one review per install, aggregate carries across template versions, auto-hold for bodies containing links/contact emails, deduped reports per account, editable response with null to clear, and aggregate adjustments on remove. This fully compensates for the lack of detailed annotation semantics and provides high 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 a single dense paragraph but well-structured by action, progressing from create to respond to report to remove/unhold. Each sentence explains a distinct action or constraint without excessive fluff. While long, it earns its length given the complexity of five sub-operations. Could be slightly improved with bullet points, but it remains readable and scannable.

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's complexity (5 actions, 9 parameters, no output schema), the description is remarkably complete. It covers permission levels (verified email, relay operators), state changes (one review per install, aggregate carrying across versions), moderation behavior (auto-hold, unhold), and edge cases (null clearing, deduplication). The only minor omission is exact return values, but the absence of an output schema makes that acceptable.

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% with every parameter described, which meets the baseline of 3. The description adds value beyond the schema by explaining cross-parameter constraints (e.g., 'identifying it by `template` or by `handle` plus `slug`', 'null clears it', 'one report per account'). It clarifies the action-specific parameter usage, enhancing the agent's understanding of how parameters interact.

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 scope statement: 'Ratings and reviews of community templates, responses from a template's own publisher, and, for relay operators, moderation.' It then enumerates five distinct actions with specific verbs (create, respond, report, remove, unhold) and their targets (templates, reviews, moderators). This distinguishes it from sibling tools like 'feedback' and 'taste' by focusing on the community review lifecycle.

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 for when to use each action: create is for installed templates with verified email, respond is for one's own template line, report is for flagging, remove/unhold are relay-operator-only. It implies exclusions (e.g., relay operators only for moderation) but does not explicitly name alternative tools or say 'when not to use.' The context is strong enough for an agent to select appropriate actions.

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 explicitly discloses behavioral traits beyond annotations: 'set replaces it in whole, so it does not append; clear discards it.' This aligns with the destructiveHint annotation (true) and provides necessary detail about the replace (non-append) behavior, ensuring the agent understands the tool's 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?

The description is concise at three sentences plus action definitions. It front-loads the purpose and scope, with no redundant information. Every sentence contributes meaning, making it easy for an agent to process efficiently.

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's simplicity (2 parameters, no output schema), the description covers all necessary context: what taste notes are, when to read them, how each action works, and the scope. The annotations provide destructive hint, but the description adds the critical detail that set is a full replacement. Complete 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 description coverage is 100%, so baseline is 3. The description adds value by clarifying that the 'set' action replaces the whole document and requires non-empty taste. This goes beyond the schema's description by emphasizing the 'whole-document replace' behavior, preventing misinterpretation as append.

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 what the tool does: manages a freeform markdown document of UI taste notes. It specifies the actions (get, set, clear) and distinguishes it from general storage by scoping it to presentation preferences. This avoids confusion with sibling tools like update_row.

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 explains when to use the tool: 'Reading it before generating or revising an app is what carries earlier feedback into new output.' It also clarifies that it is for presentation preferences only, not general storage. While it doesn't explicitly list alternatives, the context is clear enough for correct usage.

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

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

Annotations already indicate idempotentHint=true and destructiveHint=false. The description adds valuable context: authorization behavior, optimistic locking details, and the outcome on version mismatch ('returns the current row, which is what a retry needs'). 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?

Three sentences, each serving a purpose: definition, authorization, locking. No filler words, front-loads the core action. Efficient 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?

Covers core behavior, authorization, and optimistic locking details. The success response is mentioned minimally as '{ row }', but without an output schema, this is acceptable. Minor lack of detail on other error conditions besides version mismatch, but overall sufficient for a moderate-complexity 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 100%, so baseline is 3. The description goes beyond by explaining the if_match parameter's behavior ('on a version mismatch the relay returns the current row') and implicitly clarifying the collection parameter's role in authorization. Adds meaningful 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?

Clearly states 'Update an existing row in a v2 app's collection, replacing its data.' The verb 'update' and resource 'row' are specific, and the scope is well-defined, distinguishing it from sibling tools like delete_row, get_row, and upsert_row.

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 clear context on authorization gating ('Gated by the collection's update role list') and optimistic locking with if_match. However, it does not explicitly mention when to use this tool versus the sibling upsert_row, leaving a slight gap in usage guidance.

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

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

The description discloses far more than annotations: retry semantics with key dedup, duplicate creation without key, manifest write-list gating, read-list restrictions causing row_not_found, and the return shape. Since annotations only provide generic hints (readOnlyHint false, idempotentHint false), this description carries the full behavioral burden and does so excellently.

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 sentence contributes valuable information: core behavior, key semantics, retry behavior, permissions, access-control edge cases, and return shape. It is front-loaded with the main action and no sentence is filler. The structure is logical and appropriately sized for the tool's complexity.

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

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

Despite no output schema and sparse annotations, the description covers all essential context: the dedup behavior, key-based retry safety, prerequisites (manifest write list), access-control consequences, and return payload. It also mentions edge cases like row_not_found. This is complete for an upsert tool with subtle permission and idempotency considerations.

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 describes all four parameters with 100% coverage, so the baseline is 3. The description adds meaningful context beyond schema definitions, especially for `key`: it explains that omitting it creates a server-generated key and that retrying with an omitted key produces a duplicate. This extra guidance justifies a score above baseline.

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 action: 'Create a row in a v2 app's collection, or return the existing row when `key` is already present (deduped:true).' It clearly identifies the resource (v2 app collection), the verb (create/upsert), and differentiates from siblings like get_row and update_row by noting there is no separate strict-create verb. This is a specific and unambiguous statement of purpose.

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 strong guidance on when to use it: omit `key` for a new row with a server-generated key, or pass `key` to ensure existence and make retries safe. It also explains access-control preconditions (manifest write list) and read-list behavior. However, it does not explicitly contrast with sibling tools such as 'use get_row for reads' or 'use update_row for modifications,' so it falls just short of full alternative differentiation.

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