Homespun

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

Beyond the annotations (readOnlyHint=false, etc.), the description discloses behavioral traits such as whoami performing no network call and revealing no secrets, claim being one-way, and logout not revoking the key on the relay. It also clarifies the relationship with the key tool's revoke action. No contradictions with annotations. Slightly missing details on error handling or auth requirements, but the added 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 is two sentences, front-loaded with the core purpose, and then lists actions efficiently. Every sentence earns its place, no redundancy or fluff. The structure is easy to scan and understand.

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

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

For a tool with two parameters (one enum, one conditional) and no output schema, the description is quite complete. It explains what whoami returns, the one-way nature of claim, and the non-revoking behavior of logout. The only minor gap is lack of detail on what claim/logout return, but that's not critical for a simple identity management tool. Overall, it provides enough context to use correctly.

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

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

Schema description coverage is 100%, and the enum descriptions in the schema already explain each action's behavior, including the key tool distinction. The description repeats much of this information without adding significant new parameter-level semantics. It does add the 'Settings UI' origin for the claim code, but this is minor. Baseline 3 is appropriate when schema carries the 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 clearly states the tool's purpose as 'Agent identity and binding' and enumerates the three specific actions (whoami, claim, logout). It distinguishes from the sibling 'key' tool by explicitly referencing its revoke action. The verbs and resources are specific and 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 context for when each action is appropriate: whoami is a no-network status check, claim binds via one-time code, logout clears local state. It explicitly notes the alternative 'key' tool for revocation, guiding when not to use logout. However, it does not explicitly state 'use this tool when...' but the action breakdown is sufficient.

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 extensive behavioral traits: share_link_rotate revokes the old link, delete is an idempotent soft-delete, wake is a no-op that reports actual status, and domain_set explains first-domain-redirect behavior. These details go far beyond the annotations' simple destructiveHint, giving the agent a realistic model of side effects.

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

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

The description is dense with no fluff and front-loaded with the deploy_app exclusion, but it is a single long run-on paragraph separated by semicolons rather than structured bullets. The length is justified by the tool's 10 actions, though readability would improve with line breaks.

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

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

For a complex 10-action tool with no output schema, the description covers return values for most actions (DNS records, share_url, serving domain/aliases) and edge cases (idempotency, no-op, redirects). However, it does not specify what update/delete/wake return, leaving a minor gap in completeness.

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 the schema covers all parameters, the description adds rich semantic context—e.g., 'the right list differs per app' for audit, 'switching to link returns a share_url once', and 'when no domain is given' for domain_remove. This clarifies parameter interactions and domain-specific behavior beyond the schema's field-level 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 opens by framing the tool as 'The v2 app lifecycle apart from creation and redeploy, which deploy_app covers,' clearly distinguishing it from the sibling deploy_app. It then enumerates each action (list, show, audit, update, etc.) with specific verbs and outcomes, making the tool's scope 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 first sentence explicitly excludes creation/redeploy and points to deploy_app as the alternative, providing clear when-not-to-use guidance. Each action's purpose is described (e.g., audit as a read-only security review, domain_set for binding custom domains), giving context for when each sub-operation is appropriate.

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?

Adds substantial behavioral detail beyond annotations: SSRF guard specifics, byte-sniffing/re-check on finalize, soft-delete semantics, token shown once, cost implications of inline uploads. No contradiction with destructiveHint/readOnlyHint.

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?

Well-organized and front-loaded, but lengthy with some repetition (e.g., 'same byte-sniff, allowlist, size, quota and scan checks' appears multiple times). For a 17-param/11-action tool, the length is mostly justified; a tighter edit could remove 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?

Covers all actions, cost model, SSRF constraints, backend requirements, token behavior, scoping, and upload path trade-offs. With no output schema, it still gives enough for correct invocation; missing auth details are not critical given annotations.

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, so baseline is 3. The main description adds orchestration-level meaning (presign/finalize flow, which params are required together, content_base64 cost), but relies heavily on the schema for individual parameter details.

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 'Binary attachments...' and enumerates 11 actions, clearly identifying the resource and verbs (upload, fetch, presign, finalize, download, etc.). It distinguishes from sibling row/table tools by focusing on the attachment 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?

Explicitly contrasts upload paths with cost trade-offs: inline for small assets, fetch for URL-reachable bytes, presign+finalize for out-of-band PUTs, and notes Azure backend requirement. This is precise when-to-use guidance beyond a simple action list.

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?

This description is exceptionally transparent about side effects and preconditions. It discloses privacy consequences ('seed data in a published app must be example-only'), idempotency ('unpublishing an already-unpublished template is a no-op'), and nuanced failure behavior ('a snapshot that does not exist or belongs to someone else reads as not found'). Annotations (destructiveHint=true) are consistent, but the description adds rich context about what gets destroyed and what remains unaffected (existing installs).

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 by action but quite verbose, repeating key points (e.g., the privacy warning appears in both the main description and the action parameter description). It front-loads the action list, which helps, but several sentences could be tightened without loss of meaning. The length is justified by the tool's complexity, but it does not earn a higher conciseness score.

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

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

For a complex tool with 23 parameters, no output schema, and multiple distinct operations, the description is remarkably complete. It covers return values ('returns the new app's id, slug, and url'), edge cases (idempotency, not-found behavior), permissions (relay-operator-only), and side effects (superseding prior versions). It leaves very little for the agent to infer.

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, but the description adds meaningful cross-parameter logic beyond the schema—for instance, explaining how slug and version interact ('a republish under the same slug must bump the version') and what attest_example_only actually records. It also clarifies the semantic role of config values ('a 'config' value is a string and an 'upload' value is a pre-uploaded attachment id'). This elevates the value over the raw schema.

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

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

The description opens with a clear list of distinct actions ('publish, unpublish, get_config_contract, install, list_pending, get_submission, approve, reject, set_trust_level') and ties them to a specific resource ('community template'). It also distinguishes the tool from siblings by clarifying scope (e.g., 'for relay operators', 'install creates a fresh private copy'), so an agent can confidently select it for template publishing/installing operations.

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 strong contextual guidance: it explains when each action is appropriate (e.g., publish vs unpublish, install vs upgrade) and includes explicit exclusions like 'works only on your own submissions' and 'limited to the relay's configured community reviewers'. It also references companion tools (attachments, ingest) for related steps. It stops short of explicitly naming sibling tools as alternatives (e.g., 'publisher' vs 'community'), so it misses a 5.

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

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

Beyond annotations (readOnlyHint=false, destructiveHint=true), the description reveals critical behavior: create "returns its metadata, never the secret," list returns a "non-reversible fingerprint, never any secret," delete is idempotent, and oauth2 connections start in `pending_auth` until consent. It also explains the host-binding failure mode, providing substantial 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 long, but it is well-structured and information-dense, covering all major actions and edge cases. It fronts the core concept, then follows with the no-update caveat and action breakdown. While not maximally concise, every sentence contributes useful context.

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 (4 actions, 18 params, no output schema), the description is remarkably complete. It explains return values (metadata vs secret/fingerprint), the pending_auth state, the consent flow, idempotency, and the host-binding security model. No major behavioral gaps remain.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add significant per-parameter meaning beyond what the schema already provides; it summarizes high-level behavior but points to the schema for field-level semantics.

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

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

The description clearly states the tool's purpose and differentiates its actions: "Actions: create stores...; list returns...; delete is idempotent; consent_url builds..." Each action has a specific verb and resource, making the tool's role unambiguous. It also distinguishes connections from generic credentials by emphasizing the host-binding exfiltration defence and webhook authentication context.

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 actionable when-to-use guidance, notably "There is no update action: change a connection by deleting and recreating it" and the note that consent_url is for a "human-in-a-browser step an agent key cannot complete." It does not explicitly compare against sibling tools like 'credentials', but the context is sufficient for most use cases.

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 readOnlyHint annotation, the description discloses the countRead opt-in mechanism, independence from read list permissions, the exact error condition (collection_count_forbidden), and the return shape. This is rich behavioral context far exceeding 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 sentences and front-loaded with the core purpose. While dense, it includes relevant behavioral details like opt-in gating and error semantics. Minor extras like 'spec B4, issue #1056' add reference context but are not strictly necessary, so not a perfect 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?

Despite having no output schema, the description explicitly states the return value. It covers permission gating, error cases, and the precise collection scope semantics. For a tool with nuanced authorization behavior, this is thorough and complete.

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

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

Schema description coverage is 100%, and the parameter descriptions are already clear ('The app id.', 'The collection name declared in the app's manifest'). The tool description adds no extra semantics beyond what the schema provides, so baseline 3 applies.

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

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

The description clearly identifies the tool as returning 'the live row count of a v2 app's collection' and distinguishes it from list/get operations by emphasizing 'no filter and no paging' and returning '{ count }'. This separates it from sibling tools like list_rows and get_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?

It provides clear context on when to use (whole-scope count) and describes the countRead opt-in gating, but does not explicitly name alternative tools. The phrase 'no filter and no paging' implies when it's appropriate, and the '3 spots left' shape gives a concrete 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?

Beyond the annotations (readOnlyHint=false, destructiveHint=true), the description discloses rich behavioral details: the raw token is shown only once and never recoverable; pause is reversible, revoke is permanent; rotate keeps the old token working for an overlap window; effective permission is the intersection of allowlist and owner's authority; and typo in grants is rejected with a 400. These go far beyond what the annotations indicate.

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-structured and front-loaded with the core concept. Each sentence serves a purpose, and the 'Actions:' list is organized clearly. While slightly verbose, the complexity of six actions with distinct behaviors justifies the length. Nothing is redundant.

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

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

For a complex tool with no output schema, the description is exceptionally complete. It explains return behaviors (mint returns the token once; list returns metadata, never token material), error behavior (typo rejection with 400), security scope (owner-only, credential cannot self-escalate), and parameter applicability. All nine parameters are covered. It is fully self-sufficient 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 description coverage is 100%, so the baseline is 3. The description adds meaningful semantic context by grouping parameters per action (e.g., mode and grants are mint-only, overlap_seconds for rotate) and explaining how they interact (e.g., under 'following' mode, a zero-op grants entry narrows one collection). This elevates the contribution above 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 clearly states the tool's purpose: managing scoped service credentials for a v2 app. It not only names the resource ('credentials') but explains the concept of the bearer token and its role, and it distinguishes each of the six actions (mint, list, pause, resume, rotate, revoke) with specific verbs and outcomes, effectively differentiating it from sibling tools like 'key' and 'grants'.

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 context for when to use each action, such as mint for creating a credential, rotate for issuing a fresh token with overlap, and revoke for permanent deletion. It also notes a key constraint: every action is owner-or-owning-agent only. While it does not name alternative tools, the clear per-action scenarios give strong 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?

Despite annotations like destructiveHint=true, the description clarifies this is a soft delete (tombstoned, recoverable), which is critical behavioral context. It also discloses change feed semantics (op:delete) and the return value, going beyond what annotations alone 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 three concise sentences that front-load the primary action and then add recovery, feed, and locking details. Every sentence provides essential information 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?

The description covers the tool's purpose, recovery window, related tools, change feed visibility, optimistic locking, and return value. Despite no output schema, the return value is stated, making the description complete for this simple delete operation.

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 thoroughly (100% coverage), so the baseline is 3. The description adds meaningful context for if_match as an 'optimistic-locked delete' and implicitly ties key to the row being deleted, 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 'Soft-delete a row from a v2 app's collection,' which clearly identifies the verb (soft-delete), resource (row), and scope. It distinguishes from sibling tools like restore_row and list_deleted_rows by explaining recoverability.

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 recovery context: 'restore_row brings it back for 30 days (see list_deleted_rows)' and advises when to use if_match for optimistic locking. However, it stops short of explicitly stating when not to use the tool or comparing with all possible 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 minimal annotations (readOnlyHint=false, etc.), the description discloses many non-obvious behaviors: omitted fields keep live values and cost no tokens, `assets: []` clears the set, redeploys are refused unless `force:true` under certain conditions, and access removal never prompts. It also specifies exact return shapes on create vs redeploy, and describes the dry_run side-effect-free behavior. This is far richer than the annotations alone and helps the agent predict side effects accurately.

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 earns its place given the tool's complexity (10 params, nested assets, create vs redeploy modes, dry_run, manifest grammar). It front-loads the core contract (deploy = html + manifest) and then systematically covers redeploy semantics, parameter specifics, and edge cases. The structure flows from high-level purpose to detailed parameter behavior, with no filler or redundant 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?

The description is complete for a tool of this complexity. With no output schema, it explicitly states the return values for both create and redeploy ('{ app_id, slug, url, version, visibility, created }' and '{ app_id, version, compat, breaks? }'). It covers error conditions (413, manifest_incompatible_redeploy), asset validation, host-specific behavior for `html_path`, and the exact effect of dry_run. Everything an agent needs to decide when to call and what to expect is present.

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

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

Although schema coverage is 100%, the description adds substantial meaning beyond the schema. For example, it explains the cost model of omitted parameters, the interaction between `html` and `html_path` (inline wins), the semantic difference between `assets` omission vs `[]`, and the meaning of `force` with respect to the compat gate. It also enumerates common manifest keys and clarifies `check` as an alias for `dry_run`, making the parameter semantics far more actionable than 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 clear, specific verb and resource: 'Deploy a v2 app: an HTML document plus a capability manifest, hosted at its own URL.' It immediately distinguishes create vs redeploy and the overall scope. This differentiates it from sibling tools like `apps` or `attachments` by naming the core output (hosted app) and the two required/typical inputs.

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

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

The description provides explicit guidance on when to use each mode: 'Pass no `app_id` to create... or pass `app_id` to redeploy.' It also explains `dry_run` for validation-only, when to use `html_path` vs inline `html` (hosted vs local connector), and when to use `attachment_id` vs `content_base64` (referencing `attachments fetch`). It even cross-references `get_skill` for manifest grammar, offering a clear path to more details.

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 well beyond the sparse annotations by disclosing that there is no reply channel, that list returns only the agent's own submissions, and that an unreported failure is invisible to the operator. Also explains duplicate handling and action details, making behavioral expectations clear.

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 lengthy but every paragraph serves a purpose: scope, exclusions, duplicate warning, actionable message structure, and type semantics. It is front-loaded with the core purpose and well-paragraphed, though slightly dense for a fast scan.

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

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

For a tool with two actions, six parameters, and nuanced scope, the description covers all necessary context: purpose, usage boundaries, duplicate handling, message composition, type meanings, app_id, lack of reply channel, and pagination. There is no output schema, but the description explains what list returns and how paging works.

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 the schema has 100% coverage, the description enriches each parameter with practical meaning: type definitions (bug/feature/note), app_id scoping, message actionability requirements (surface, location, expected vs. observed, reproduction steps), and pagination via `before`. This goes far beyond the schema's bare 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 opens with a specific verb and resource: 'Reports a problem with homespun itself to the relay operator, and lists what this agent has already reported.' This clearly distinguishes feedback from sibling tools like taste or review by scoping it to platform-level issues.

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 in-scope and out-of-scope guidance, naming alternatives (e.g., presentation preferences belong in `taste`, documentation issues best filed as a `note`). Also clarifies when to use list vs. create and warns that duplicates are counterproductive.

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?

Adds significant behavioral context beyond annotations: the polling mechanism, cursor usage, long-poll behavior with wait, and error handling (resync_required). 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?

Medium-length paragraph with clear logical flow: purpose, usage pattern, parameter explanation, error handling, return shape. Every sentence adds value, no waste.

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 essential behaviors (polling loop, cursor, long-poll, error, return) but could mention retention floor details. Still complete enough for correct agent usage.

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 has 100% coverage, but the description adds practical usage guidance for each parameter (e.g., wait for long-poll, since as cursor, limit for pagination), enhancing understanding 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 clearly states it polls a v2 app's change feed for row creates, updates, and deletes, and distinguishes itself from siblings like list_rows.

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 describes the polling loop, when to use wait, and what to do on resync_required (re-list with list_rows), providing clear context for when to use this tool vs alternatives.

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

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

Annotations already declare readOnlyHint=true. The description adds that the tool uses a dedicated relay route (efficiency detail) and specifies the return format: { row } or an isError row_not_found. This provides useful behavioral context 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 two sentences long, front-loading the purpose and key behavioral details. Every word serves a purpose; no 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?

For a simple fetch tool with three parameters and no output schema, the description covers purpose, return format, and an implementation detail. It is mostly complete, though it could mention potential error scenarios beyond row_not_found (e.g., permissions).

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%, with each parameter described (key, app_id, collection). The description does not add further semantics beyond what the schema already provides, so baseline score of 3 is appropriate.

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

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

Description clearly states the tool fetches a single row by key from a v2 app collection, using an efficient relay route. It distinguishes itself from sibling tools like list_rows, delete_row, etc., by focusing on single row retrieval.

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 mentions using a dedicated relay route instead of client-side scan, implying efficiency when the exact key is known. However, it does not explicitly state when to use this tool versus alternatives like list_rows or other fetch methods.

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 adds that no API key is needed, confirming a safe read operation. It explains the return options (full guide or version string) and the caching optimization. Minor gap: could mention if the operation is fast or has side effects, but overall good.

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. The first identifies the tool and its content, the second gives usage context, the third explains the parameter. No wasted words.

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

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

Given the tool's simplicity (one boolean param, no output schema), the description covers all essential aspects: what it returns, when to use, how to use the parameter, and what the guide contains. No gaps for effective agent 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% for the single parameter. The description adds meaningful context by explaining the caching use case for version_only, going beyond the schema's basic description. It clarifies why one might use this parameter.

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 retrieving the relay's SKILL.md guide, explaining its content (Homespun workflow, events vs records, schema grammars, poll loop). The title 'Get Skill Guide' aligns well, and the description distinguishes the version_only parameter's 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?

Explicitly states when to use: 'when working out how the other tools fit together, or to refresh a cached copy.' Also mentions it needs no API key, and gives guidance on using version_only to check cache freshness.

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, etc.), the description discloses critical behaviors: the grant_url token is shown once and not recoverable, list never returns a token, revoke is idempotent, pins never widen access, and the write-only grant read-back caveat. This is far richer than the structured hints alone.

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 every sentence earns its place, covering definition, actions, modes, pin behavior, and a security-relevant caveat. It is well-structured, front-loaded with the core concept, and contains no filler or redundant 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 10-parameter, multi-action tool with no output schema, the description is unusually thorough: it describes mint/list/revoke, token handling, once/multi modes, pin narrowing, and a subtle security consequence. It stops short of fully describing return shapes for list/revoke and error behavior, but the schema and annotations fill some gaps.

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

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

The input schema already covers 100% of parameters with descriptions, so the baseline is 3; the description adds meaningful context on top—mode explanations, pin narrowing semantics, and the max_uses cap within expiry. It enriches the schema without replacing it, so 4 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 defines the resource ('A v2 app's grant links') and enumerates the three actions with specific verbs: mint, list, and revoke. It distinguishes itself from sibling tools by focusing on capability URLs and custom role grants, with a clear explanation of what a grant link is and does.

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 on when to use each action and explains key modes (once vs multi), but it does not explicitly name alternative tools or state 'use members instead.' It does provide a useful exclusion: 'A grant does not escalate to owner, member or agent,' which helps scope its 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?

The description adds behavioral context beyond the destructiveHint annotation: rotate invalidates the old URL immediately with no redeploy, set_signing_secret never echoes a stored secret, and 'Signature verification currently ships dark: nothing verifies a signature yet.' These are valuable, honest disclosures that the 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 a long, dense paragraph. While it contains important context, the action summary duplicates the schema's action enum descriptions almost verbatim, which is redundant for an agent that can already read the schema. The structure is not broken into bullets or sections, making it harder to scan.

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

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

For a tool with no output schema, the description covers return behavior well: list returns full URLs and settings, rotate returns a new URL once, set_signing_secret mints or stores a secret and never echoes it, and clear_signing_secret removes it. It also explains the overall relationship to manifests and deploys, making the tool's context complete for an AI 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?

The schema already provides 100% parameter coverage with detailed descriptions for action, name, secret, and grace_seconds. The description largely repeats the schema's action semantics (e.g., 'mint a fresh URL secret for one hook... invalidating the old URL immediately') rather than adding new parameter-level meaning. It adds contextual examples (Stripe, Zapier) but does not enhance parameter understanding beyond the schema.

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

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

The description clearly identifies the tool as managing a v2 app's inbound catch-hooks (inbound-webhooks), explicitly stating the three key operations: reading back the URL, rotating a leaked URL, and managing the opt-in signing secret. It distinguishes itself from sibling CRUD/row tools by stating it has no create or delete capability.

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 says when to use the tool: 'After deploying a manifest that declares a hook, list is what yields the exact URL to paste into the external system.' It also explicitly says 'this tool has no create or delete,' which is a clear when-not. However, it does not name specific alternative sibling tools, so it stops short of full explicit 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?

Discloses critical behavioral details beyond annotations: mint returns raw value only once and never again, sibling appears in later list, revocation is immediate and irreversible, and confirm:true is required. Also explains identity derivation from caller token. This goes well beyond the destructiveHint annotation.

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

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

The description is dense and information-packed, but it is a single run-on paragraph. It could be structured with bullet points for readability, but every sentence adds value with no fluff, so it remains 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?

Given the tool's security-sensitive nature (destroying credentials, minting keys), no output schema, and minimal annotations, the description is remarkably complete. It covers all actions, side effects, irreversibility, confirmation requirement, identity constraints, and the unique one-time retrieval of minted keys, leaving no major gaps.

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

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

Schema description coverage is 100%, and the schema parameter descriptions already contain most of the behavioral detail. The main description adds a little extra context (e.g., relay identity derivation) but does not significantly enhance understanding of parameters beyond what the schema provides, so baseline 3 applies.

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

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

The description clearly states the resource (the calling agent's API key) and lists three specific actions (list, mint, revoke), each with distinct behavior. It distinguishes itself from sibling tools by focusing on self-managed API key operations.

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 usage context for each action: list for key info, mint for creating a sibling key to hand to a CLI/child process, revoke for self-destruction with confirm required. It also explains identity constraints (cannot target another agent) and acts on the caller's own key, giving clear when/why 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, idempotentHint), the description discloses soft-delete behavior, the 30-day retention window, purged rows appearing with purged:true, and that purged rows cannot be restored. It also reveals the return shape, adding significant 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?

Multiple sentences, each conveys distinct information: purpose, restore behavior, permissions, purged handling, and output shape. No fluff; front-loaded with the core action.

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

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

No output schema exists, so explicitly stating the return object ({ rows, next_before }) is essential. The description also covers auth constraints and edge cases (purged rows), making it complete for a tool of this 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% with all four parameters described, including limit default and before cursor. The description doesn't add parameter-specific semantics beyond what the schema already provides, so the baseline 3 applies.

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

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

The description opens with a specific verb and resource ('List a collection's recently deleted rows') and names the 'recovery bin.' It also references restore_row and soft-delete semantics, distinguishing it from list_rows and other 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?

Clearly states when this is relevant: 'Deleting a row is a soft delete, so it can be restored with restore_row until recoverable_until passes.' It also notes permission requirements (owner/agent only) and independence from read permissions. It doesn't explicitly contrast with list_rows, but the context is clear.

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

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

The description adds behavioral details beyond the readOnlyHint annotation by explaining the non-streaming nature of MCP and the polling mechanism. It also discloses the return shape with rows, next_cursor, and has_more. It does not mention auth or rate limits, but those are not critical for a read-only operation.

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

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

The description is two sentences long, immediately states the core purpose, and includes the return shape and a key usage pattern. Every sentence earns its place with no 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 return structure and polling/pagination behavior, which is essential for this type of tool. The existence of a list_deleted_rows sibling implies this lists non-deleted rows, though that is not explicitly stated. Overall, it is sufficiently complete for a read-only list operation.

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?

All four parameters are described in the schema with 100% coverage, so the baseline is 3. The description reinforces the polling use of `since` but the schema already states it is a poll handle. No additional parameter semantics are 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 the tool lists rows in a v2 app's mutable collection, using a specific verb and resource. It distinguishes itself from sibling tools like get_row (single row) and delete_row/update_row/upsert_row (mutations).

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 that this tool is also the way to poll a collection's current state, and instructs passing the prior next_cursor as `since` for incremental fetching. This provides clear guidance on when to use this tool versus alternatives for tracking changes.

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 side effects beyond annotations: remove 'revokes the human's live sessions on this app', set_role 'leaves their sessions intact', add attaches immediately if a Human exists otherwise sends a magic-link invite, and the owner cannot be removed. This enriches the idempotent and destructive hints already present.

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 is organized by action and each clause earns its place given the tool's multi-action complexity. It could be more scannable with bullets, but it is not needlessly verbose.

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 explaining what list returns (owner + members) and what roles returns (effective access summaries and counts). It also covers constraints and side effects for add, set_role, and remove. It does not describe the exact return values for mutating actions, but that is a minor gap given annotations.

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

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

Schema description coverage is 100%, so the baseline is 3, and the description largely restates what the schema already explains (e.g., email invite-or-attach, custom_roles semantics). It adds a small extra by pointing to list's humanId as the source for human_id, but no significant new parameter-level meaning.

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

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

The description defines the tool as managing a v2 app's membership and enumerates each action with a specific verb (add, list, set_role, remove, roles), making it clear what the tool does and distinguishing it from sibling tools like grants. The scope is precise: 'who besides the owner can sign in to a private app and write to member-scoped collections.'

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 guidance, notably that set_role is 'the way to re-role someone rather than removing and re-adding them', and explains add's conditional invite-or-attach behavior. It does not provide explicit when-not-to-use guidance beyond the owner removal constraint, but the context is clear.

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

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

Beyond annotations, the description discloses important behaviors: claim is one-time permanent, refuses reserved/taken handles, requires verified email, and explains the provisional `maker-` handle. This is rich behavioral context not available from annotations alone.

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 actions clearly enumerated in a compact paragraph. It front-loads the core identity concept and each sentence provides necessary information 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?

Given the multi-action nature and lack of output schema, the description thoroughly covers return values for get, behaviors for claim/update, and prerequisites. It 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?

The schema already describes all parameters with high coverage, but the description adds critical meaning: the handle permanence after claim and the one-time use restriction. This extra context clarifies parameter semantics 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 clearly defines the tool as managing the caller's publisher identity, with distinct actions (get, claim, update) and specific resources (handle, profile fields). It differentiates from sibling tools like members or community 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 each action, including prerequisites like verified email for claim/update. It does not explicitly name alternative tools, but the scope is unambiguous and no sibling is a direct substitute.

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 annotation hints false, the description carries the full transparency burden. It discloses the mutation effects (original data, creator, version bump), authorization requirements (owner or agent), specific error conditions (restore_expired, restore_conflict), and return format ({ row }). This is rich behavioral context beyond what annotations provide.

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

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

The description is three sentences, front-loaded with the primary purpose, then behavior, then error handling. Every sentence earns its place with no redundancy or 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 moderate-complexity tool with no output schema, the description covers all essential aspects: what it does, prerequisites, failure modes, and return value. It references the relevant sibling tool for discovery, making it complete 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?

While schema coverage is 100%, the schema descriptions are minimal. The description adds meaningful semantics for the 'key' parameter by directing users to list_deleted_rows to find valid keys. App_id and collection remain basic, but the added key guidance raises the value above the baseline 3.

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: 'Restore a soft-deleted row, undoing delete_row.' It clearly distinguishes the tool from siblings like delete_row and list_deleted_rows, and explains that it reverses a prior soft delete.

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 by linking to list_deleted_rows for finding restorable keys, and implies the proper use case (restoring a soft-deleted row). The failure conditions for purge and conflict also implicitly tell the user when not to use it. This meets the standard for explicit alternatives and usage 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?

The description goes well beyond annotations, disclosing important behaviors such as auto-holding bodies containing links/contact emails, aggregate carry across template versions, one-review-per-install limit, deduplication of reports, and how remove adjusts the aggregate. These details are not present in annotations and meaningfully inform the agent about side effects and moderation flows.

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 front-loads the overall purpose before breaking down each action. It avoids filler, uses semicolons to pack related constraints efficiently, and every clause contributes unique information despite covering five actions in limited space.

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 covers all necessary facets: action-specific targets, permission restrictions, side effects on aggregates, and moderation workflow. The annotations and schema are rich, but the description fills in behavioral context that is essential for correct invocation, 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 each parameter already described in detail (e.g., 'create only', 'report only', null semantics for response). The description reinforces which parameters belong to which action but does not add new parameter-level meaning beyond what the schema already provides. Baseline 3 is appropriate given the schema's thoroughness.

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 community reviews with five distinct actions (create, respond, report, remove, unhold), each with a specific verb and resource. It distinguishes itself from sibling tools by explicitly covering ratings, publisher responses, and moderation, leaving no ambiguity about its 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 context for each action, including prerequisites (e.g., caller has installed the template for create, own template for respond, relay-operator status for remove/unhold) and constraints (one review per install, deduplication for report). It does not explicitly name alternative tools or state when not to use this tool, but the action-level guidance is strong and actionable.

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 (destructiveHint=true), the description discloses that set replaces the whole document (not appends) and clear discards it, aligning with destructive 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 concise, front-loaded with the purpose, and uses short sentences with no wasted words.

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

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

With only two parameters and annotations present, the description fully explains actions and scope, leaving no gaps.

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

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

Schema coverage is 100% and the description adds context that set requires a non-empty taste and performs whole-document replace, supplementing 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 clearly states the tool manages UI taste notes with specific actions (get, set, clear). It distinguishes from sibling tools like 'agent' or 'apps' by emphasizing presentation preferences.

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 read (before generating/revising an app) and scopes usage to presentation preferences, but does not explicitly list when not to use or provide direct 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?

Adds significant behavioral details beyond annotations: role-based access, optimistic locking with if_match, and retry behavior on version mismatch. 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?

Four sentences with no fluff. Purpose stated first, then authorization, then locking, then return. 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?

Covers all necessary aspects: purpose, authorization, parameter semantics (via schema and description), and special behavior (optimistic locking). No output schema, but description adequately describes the return value as { row } and mismatch behavior.

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 covers all 5 parameters (100% coverage). The description adds value by explaining the purpose of if_match (optimistic locking and retry flow) beyond the schema's minimal 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?

The description clearly states the verb-resource pair: 'Update an existing row in a v2 app's collection, replacing its data.' It distinguishes from siblings like delete_row and upsert_row by focusing on updating existing rows.

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 context on authorization gating and optimistic locking behavior, but does not explicitly state when not to use this tool or name specific alternatives like upsert_row for create-or-update 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?

Even though annotations already mark readOnly=false and destructive=false, the description goes far beyond them. It discloses dedupe behavior, retry safety, the duplicate-row risk when `key` is omitted, the manifest `write` list requirement, the `row_not_found` behavior when the `read` list does not reach the row, and the return shape `{ row, deduped? }`. This is exemplary behavioral 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 long but dense and well-structured. It front-loads the core purpose, then logically explains key semantics, retry behavior, permission requirements, and return shape. Every sentence contributes necessary behavioral or usage context without padding.

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

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

Given the tool's complexity and the absence of an output schema, the description is exceptionally complete. It covers prerequisites (manifest write list), edge cases (dedupe, retry, read-list limitations), and the return format. There are no significant gaps in what an agent needs to know to invoke this tool correctly.

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

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

The input schema already covers all four parameters with descriptions (100% coverage), so the baseline is 3. The description adds meaningful semantic detail beyond the schema, especially for `key`: omitting it creates a new row, passing it enables dedupe and retry safety. It also clarifies the `data` parameter as 'any JSON value valid against the collection's row schema'. This elevated value justifies a 4.

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 begins with a specific verb+resource: 'Create a row in a v2 app's collection, or return the existing row when `key` is already present' – clearly stating its upsert behavior. It distinguishes itself from sibling tools like get_row, update_row, and delete_row by emphasizing the create-or-return semantics and deduplication.

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 this tool: 'Row creation goes through this tool; there is no separate strict-create verb.' It also explains the key distinction between omitting `key` (new row with server-generated key) and passing `key` (dedupe/retry safety), which guides usage. It does not explicitly contrast with update_row or list other exclusions, so it stops short of a perfect 5.

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