Dock

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

With no annotations, the description reveals behaviors: auto-computed position, key collision 409 error, editor role requirement, and surface targeting logic. These provide useful context beyond the schema, though idempotency or success behavior isn't detailed.

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 paragraph of 4 sentences, front-loading the core action and sequentially covering position, error, role, alternatives, and surface handling. No superfluous 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?

For a tool with 8 parameters and no output schema, the description covers the purpose, usage guidelines, error scenarios, role requirements, and multi-surface nuance comprehensively. It is complete for an AI agent to correctly invoke.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the position auto-computation, key collision, editor role, and surface_slug fallback behavior, which are not in the 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 'Append a single column to a workspace's table schema,' providing a specific verb and resource. It distinguishes itself from sibling tools like update_workspace_columns and get_workspace_schema by mentioning alternative use cases.

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 says 'Use this for per-column additions; use get_workspace_schema + update_workspace_columns (PUT on /columns) for full schema replacement or reordering.' It also notes the editor role requirement and key collision error, guiding appropriate 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?

With no annotations, the description fully discloses behaviors: threading behavior (flattening nested replies, auto-unresolving parent), events fired (comment.added, comment.unresolved), mention validation (access check), and role requirement. 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 concise (4 sentences) and well-structured: first sentence for purpose, second for threading details, third for mentions, fourth for alternative tool. Every sentence adds value 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 tool's complexity (5 parameters, no output schema, many siblings), the description covers all essential aspects: purpose, usage guidelines, behavioral traits, parameter details, and role requirements. It is complete for correct 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?

Although the input schema covers 100% of parameters with descriptions, the tool description adds significant context: it explains the threading effect of parentId (re-opens resolved parent), the fan-out behavior for mentions, and the polymorphic nature of target. This enhances the schema's 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 clearly states the tool's action: 'Post a new comment on any target in a workspace'. It lists all possible target types (row, cell, doc_range, html_element, surface, workspace) and distinguishes from the sibling tool 'reply_to_comment', making the purpose unambiguous.

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

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

The description explicitly advises when to use an alternative: 'For replies to existing comments where you don't want to reconstruct the target, prefer reply_to_comment'. It also mentions the required role ('Editor or commenter role required'), providing clear 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?

With no annotations, the description fully details the tool's behavior: it lists every agent signed by the owner, explains the online status implications, and specifies scope. No assumptions left unstated.

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 verbose but every sentence adds value, explaining output fields and usage context. It could be slightly more concise, but it is well-organized and front-loaded with the main 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?

Given no output schema, the description comprehensively explains every field in the response and the tool's owner-scoped behavior. No additional context is needed for this simple list 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?

No parameters exist, so the schema coverage is 100%. The description doesn't need to add parameter info, and it correctly conveys the tool takes no arguments. A score of 4 is appropriate for zero-parameter tools.

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 'List the agents you can message' and explains each field in the response. It distinguishes from sibling 'send_message' by focusing on listing rather than sending. No confusion about what the tool 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 provides clear context: use to get addresses and online status before messaging, and it notes owner-scoping. It doesn't explicitly list alternatives or when not to use, but the purpose is self-evident.

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 no annotations, the description fully discloses behavior: non-idempotent, dedupe responsibility, mention firing rules (only new mentions trigger events), editor role requirement, surface_slug option, and supported markdown elements including file size limits for video embeds.

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

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

The description is front-loaded with the core purpose. It is dense with information but not verbose for the complexity covered. Minor repetition of 'same markdown surface as update_doc' could be tightened, but overall 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?

Given no output schema, the description explains the append mechanism (fetch, splice, write), mentions auth, events, and guard limits. It also covers special behaviors like mention firing and surface targeting, making it highly complete for a complex tool.

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

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

Schema coverage is 100%, but the description adds valuable context beyond schema: slug accepts bare or org-prefixed forms, markdown becomes new blocks, surface_slug is optional for multi-doc workspaces. However, the extensive list of supported markdown is not parameter-specific.

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 appends Markdown to the end of a workspace doc body, using specific verbs and resource. It distinguishes from siblings like update_doc by focusing on append behavior for cron/ingest agents.

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 indicates it's designed for crons and ingest agents, implying a batch/timestamped context. It mentions non-idempotent nature and deduplication responsibility but does not explicitly contrast with alternative tools like update_doc for replacement 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?

No annotations provided, so description carries full burden. Discloses behaviors: unmapped keys stored but not rendered, response includes unmapped_fields and warning, auto-create columns atomic operation, auto-seed on first row if empty, and error condition for invalid surface_slug.

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-structured with clear paragraphs for unmapped fields and auto-create columns. Front-loaded with core purpose, then detailed. Every sentence adds value 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?

Covers all scenarios: empty table, multi-surface, unmapped storage, auto-create. Context signals indicate no output schema, but description hints at response fields (unmapped_fields, created_columns). Complete for a creation tool.

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

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

Schema coverage is 100%, but description adds semantic details: explains data keys mapping, auto_create_columns behavior and response, and surface_slug fallthrough. Goes beyond schema to clarify edge cases.

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 'Append a new row to a workspace's table surface' with a specific verb (append) and resource (row). It distinguishes this creation action from siblings like update_row and delete_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 explicit guidance: when to use surface_slug (multi-surface workspaces), when to use auto_create_columns (machine-emitted rows), and when to omit it (explicit schema control). Offers alternatives like list_surfaces for enumeration.

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?

No annotations exist, so the description carries full burden. It discloses that the ticket mirrors to a GitHub issue in Dock's support repo and appears in the user's dashboard. It provides details on attachment URL requirements (must be from Dock blob store via upload endpoint). While it doesn't mention rate limits or permissions, the behavior is well-explained for a support ticket tool.

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

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

The description is very concise: two sentences plus a brief list of use cases. Every sentence adds necessary information with no waste. It is front-loaded with the primary purpose, followed by practical usage guidance.

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 there is no output schema, the description sufficiently explains the outcome (mirrors to GitHub issue, appears in dashboard). It covers the main use cases, parameter tips, and attachment process. The tool does not require complex contextual details beyond what is provided.

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 parameters documented. The description adds value beyond the schema by clarifying the 'kind' enum categories, providing tips for title specificity ('Table view loses focus on cell edit' beats 'broken'), and explaining the 'attachmentUrls' prerequisite (must be hosted on Dock blob store via upload). This enhances understanding.

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

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

The description clearly states the action ('File a support ticket') and the resource (support ticket/GitHub issue). It lists specific use cases (bugs, feature requests, billing, questions) and explicitly distinguishes itself from the sibling 'request_limit_increase' by stating when to prefer that alternative.

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

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

The description provides explicit guidance on when to use this tool (bugs, feature requests, billing, questions, etc.) and when not to ('Prefer request_limit_increase when the user is simply hitting a plan cap'). This clearly differentiates from the sibling 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?

No annotations are provided, so the description fully discloses behaviors: slug auto-derivation and collision handling, column default behavior for table kind, html starting empty, emission of surface.created event, and the role requirement. This is comprehensive for a creation tool.

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

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

The description is concise yet informative, using clear sentences that front-load the main action. Every sentence adds value without unnecessary 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?

The description covers creation behavior, parameter details, and event emission. However, it lacks explicit information about the return value of the tool (likely the created surface object). For a tool with no output schema, this is a minor gap in an otherwise complete description.

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

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

Schema description coverage is 100%, so the schema already documents all 5 parameters. The description adds value by explaining auto-derived slug behavior, column defaults for table, that columns are ignored for doc/html, and that editor role is required. This goes beyond what the schema provides.

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 'Create a new surface (tab) inside a workspace' using a specific verb and resource, and distinguishes this creation tool from sibling tools like update_surface, delete_surface, and list_surfaces.

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 specifies when to use each kind (table/doc/html) and explains optional parameters like slug and columns. It also mentions the required Editor role. However, it does not explicitly state when not to use this tool or suggest 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?

With no annotations provided, the description thoroughly covers behavioral traits: URL validation at create-time and DNS re-validation at delivery, the 'none' behavior for empty events, and the one-time return of the signing secret.

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

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

A single paragraph that is concise and front-loaded with key info. While dense, it is well-organized and earns each 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?

Given the tool's complexity (3 required params, no output schema, no annotations), the description adequately covers URL constraints, event behavior, and secret handling. It is complete for guiding 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?

The input schema already has 100% coverage with descriptions. The description adds minor nuance (e.g., empty events means 'none', store the secret), but does not significantly extend beyond schema.

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

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

The description clearly states it registers a new webhook endpoint on an org, with specific details like URL constraints and event filtering. It distinguishes from sibling tools like delete_webhook or update_webhook.

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 specifies that the URL must be public and events array cannot be empty, providing clear context for use. However, it does not explicitly mention when not to use or alternatives.

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

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

With no annotations provided, the description carries the full burden. It discloses many behavioral traits: how agent-created workspaces differ (attribution, co-owner enrollment), seeding of primary surface based on mode, fallback logic, org-visibility default for agents, and server-side markdown conversion. No contradictions with any implicit assumed 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 relatively long but every sentence adds value. It is front-loaded with the core purpose. Minor redundancy could be trimmed (e.g., repeated advice to pass mode), but overall it is 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?

Given the complexity (4 parameters, no output schema, no annotations), the description is very complete. It covers purpose, usage, behavioral details, and parameter semantics thoroughly. However, it does not describe the return value (e.g., workspace ID or shape of created workspace), which would be expected since there is 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?

Although schema coverage is 100% (baseline 3), the description adds substantial meaning beyond the schema: it explains the mode enum in context of use cases (prose vs records vs html), the fallback rule, the purpose of initial_markdown to avoid empty defaults, and the auto-derivation of slug with collision handling. This compensates richly.

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 starts with 'Create a new workspace in the caller's org', which is a specific verb+resource. It clearly distinguishes from sibling tools like create_surface by noting that additional tabs can be added later via that tool, and from delete_workspace and update_workspace by focusing on creation.

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

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

The description provides explicit when-to-use guidance, including choosing mode based on content type (prose, records, html), instructions to pass mode or initial_markdown rather than relying on fallback, and advice to use create_surface for additional tabs. It also states agent-created workspaces default to org-visibility to avoid 403 errors.

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?

No annotations provided, but description fully discloses soft-delete nature, trash lifecycle, quota refund, restore endpoints, role requirement, and feature flags. Comprehensive 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?

Four sentences, each dense with information. Front-loaded with primary action, then critical lifecycle details. 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?

Fully explains the delete lifecycle, restore process, prerequisites, and feature gating. For a delete tool with no output schema, no 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?

Input schema covers both parameters with 100% description coverage. Description doesn't add new meaning beyond 'by id' for file_id; baseline 3 is appropriate as schema does the heavy lifting.

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 'Soft-delete a file by id.' Distinguishes from sibling tools like list_files and get_file by specifying the action and mentioning restore alternatives.

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

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

Specifies when to use (to soft-delete), the 30-day trash window, restore options via REST and future MCP tool, required Editor role, and feature gating. Provides clear context for selection.

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 the irreversible nature of the deletion ('cannot be undone'), which is a key behavioral trait. However, it does not mention required permissions, side effects, or other behavioral aspects, leaving some gaps.

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 extremely concise, containing only two sentences with no redundant information. It is front-loaded with the core purpose and follows with a critical warning.

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 deletion tool with two parameters and no output schema, the description is largely sufficient. It states the action and its permanence. A minor gap is the lack of mention of the return value, but this is not critical for selection or invocation.

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

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

Schema coverage is 100%, so the baseline is 3. The description does not add any meaning beyond the schema; both parameters are adequately described in the schema, and the tool description repeats none of that detail.

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 'delete' and the resource 'a row from a workspace', making the action unambiguous. It distinguishes itself from sibling tools like create_row, update_row, and delete_workspace.

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 no guidance on when to use this tool versus alternatives. It lacks explicit context or exclusions, merely stating the action and its permanence without directing the agent away from similar tools.

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?

No annotations provided, so description carries full burden. It fully discloses soft-delete nature, idempotency, preservation, constraint on last surface, required permission, and event emission. 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?

Five focused sentences, each adding critical information. Front-loaded with purpose, 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 no output schema and no annotations, the description covers all necessary behavioral aspects: idempotency, permissions, constraint, event, and data preservation. Complete for an agent 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 coverage is 100%, so baseline is 3. Description does not add extra meaning beyond what schema already provides for the two parameters (slug, surface_slug).

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 'Archive' and resource 'surface', using 'soft-delete' to distinguish from hard deletion. It highlights preservation of rows and doc body, setting it apart from sibling delete tools.

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

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

Provides explicit context: idempotent behavior, constraint against archiving the only live surface, required editor role, and emitted event. This gives clear when-to-use and when-not-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?

No annotations provided, so description carries full burden. It discloses that deletion is permanent, URL stops immediately, secret is destroyed, and recreation is needed. This covers the key behavioral traits for a destructive 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?

Three sentences: first states purpose, second details consequences, third offers alternative. Front-loaded and efficient 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?

Given no annotations, no output schema, and simple parameters, the description covers purpose, behavior, and alternative. Missing explicit return value or confirmation, but deletion tools typically return success status, and the description is adequate for an agent 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% with both parameters already described ('Org slug', 'Webhook id'). Description does not add additional meaning beyond what the schema provides, meeting 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 'Permanently delete a webhook endpoint' with a specific verb and resource. It distinguishes from siblings like create_webhook, update_webhook, and list_webhooks by emphasizing the permanent nature and providing alternative for pausing.

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?

Description explicitly says when to use (permanent deletion) and when not to (to pause, use update_webhook with active:false instead). It names the alternative tool and 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?

No annotations provided, but the description thoroughly discloses soft-delete preservation, immediate member access loss, idempotency, role requirements, and the two execution modes with their return formats. This fully compensates for missing 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 detailed but well-structured, starting with the core purpose and then expanding on behavior, idempotency, role, and mode workflow. Every sentence adds value, though it could be slightly more concise without losing clarity.

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 fully explains return values for both modes (immediate success or approval flow). It covers prerequisites, side effects, and idempotency, making it complete for an AI agent 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?

Both parameters have 100% schema description coverage, and the description adds significant value: explains the 'mode' enum behaviors and 'slug' format flexibility (bare vs org-prefixed). This goes 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?

Description clearly states 'Archive a workspace' and uses 'soft-delete' to distinguish from permanent deletions. Among sibling tools like 'delete_row' and 'delete_file', this tool's archival purpose is unique and well-defined.

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 for when to use the tool (archiving a workspace) and recommends 'mode: web' for non-trivial workspaces. However, it does not explicitly state when not to use it or list alternatives, though none exist among siblings.

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

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

With no annotations provided, the description fully discloses the tool's behavior: it is not immediate, it is consent-gated, requires two calls in chat mode with a 60s timeout, and in web mode requires browser approval and polling. Also notes no-op condition. 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 well-structured, starting with the core action, then detailing the two modes. Every sentence provides unique value without unnecessary verbosity. For the complexity of the tool, it is appropriately concise.

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

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

Given the tool has no output schema and involves a two-step consent process, the description fully covers the workflow: scheduling behavior, no-op, consent modes, token management, and polling. It is 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?

The input schema covers 100% of parameters, but the description adds crucial context beyond the schema: it explains the entire round-trip flow for each mode, the role of confirm_token, and the difference between chat and web surfaces. This significantly aids correct usage.

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 schedules a downgrade to Free at the end of the billing period, distinguishing it from the sibling 'upgrade_plan'. The verb 'schedule' and resource 'downgrade to Free' 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?

Explicitly explains when to use (to downgrade to Free), when not to (already on Free is a no-op), and provides detailed guidance on the two consent modes (chat vs web), including multi-step call sequences, confirm_token usage, and polling instructions.

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 no annotations provided, the description carries the full burden of behavioral disclosure. It explains the two execution modes, the return format ({ ok, displayValue, error? }), and access requirements. It could be more explicit about read-only nature and any limits (e.g., character max mentioned in schema), but overall it is transparent.

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 separates the two modes with clear labels (STANDALONE, IN-WORKSPACE). Every sentence adds value, no 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?

Given the tool's complexity (two modes, parameter interactions), the description covers all essential information: return format, mode selection, parameter roles, access prerequisites. Without an output schema, it still specifies the return shape, making it 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?

Since schema description coverage is 100%, baseline is 3. The description adds meaning by explaining how workspace_slug and at interact, providing examples (e.g., standalone formula =SUM(1,2,3)), and clarifying that at is only relevant in workspace mode. This goes beyond the 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 evaluates a formula expression against a workspace or empty grid, returning the display value. It explicitly distinguishes two modes (standalone vs in-workspace) and differentiates from siblings like validate_formula by emphasizing execution against actual data.

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

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

The description provides explicit guidance on when to use each mode: omit workspace_slug for standalone formulas without cell references, pass workspace_slug for workspace-dependent evaluation. It also mentions access requirements (read access for workspace mode, public for standalone) and explains the optional at parameter's role.

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?

No annotations are provided, so the description carries the full burden. It implies read-only behavior ('Get'), but does not explicitly state no side effects, auth requirements, or rate limits. The note about humans and agents hints at accessibility but lacks depth.

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, but the first is a long list. It is efficient but could be more structured. Every sentence adds value, 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?

Given no output schema, the description thoroughly explains the return values (plan, caps, counts, price, card, next invoice) and provides usage context. It is complete for a parameterless info 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?

There are no parameters, and schema coverage is 100%. Per guidelines, baseline is 4. The description adds value by listing the returned fields, which compensates for the lack of output 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 gets the caller's org billing summary with a specific verb and resource. It lists the exact fields included (plan, caps, counts, price, etc.) and explicitly ties it to sibling tools like upgrade_plan, distinguishing its 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?

Explicit guidance is provided: use before upgrade_plan to check caps, and after to confirm plan change. Also states both humans and agents can call. While it doesn't state when not to use, the context is clear enough.

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

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

In the absence of annotations, the description discloses key behavior: fetches thread in one round trip, accepts any comment id, returns structured data with aggregated reactions. Does not mention errors or rate limits, but covers primary behavior well.

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

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

Two sentences, zero fluff, front-loaded with purpose. 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?

Given low complexity (1 param, no output schema), the description explains return shape and use case. Missing error handling info, but acceptable for a simple retrieval tool.

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

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

Schema coverage is 100% with a single parameter already described. The description adds no new parameter info beyond the schema, but does provide usage context. 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 tool fetches a single comment with replies and reactions in one round trip, using a specific verb and resource. It distinguishes from sibling tools like list_comments and reply_to_comment.

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

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

Explicit guidance is given: use when an agent receives a comment.added webhook with a parentId and needs full context before replying. No explicit when-not-to-use, but context implies it's for retrieving a specific thread, not listing.

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 no annotations, the description fully discloses behavior: format negotiation, default markdown with rationale, empty returns for unwritten docs, and 404 for invalid surface_slug. 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 a single paragraph that is information-dense but slightly verbose. However, it is front-loaded with the main purpose and each sentence contributes value. Could be more structured but 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?

Given no output schema, the description thoroughly explains return values for each format, behavior for missing docs, and error conditions. It covers all necessary context for an agent to use 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%, but the description adds significant meaning: explains each format's use case, slug resolution, and surface_slug purpose. This goes well 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 'Read a workspace's doc (TipTap rich-text) body.' using a specific verb and resource. It distinguishes from sibling tools like get_html, get_row, etc. by focusing on TipTap rich-text content and listing format options.

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 advises when to use each format: 'Pass format: "content" only when you're round-tripping into update_doc for a structural edit.' It also instructs to omit surface_slug for primary doc or use list_surfaces to enumerate, and explains behavior for missing docs and invalid slugs.

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 no annotations, the description discloses URL validity (until hard-delete), future plan for signed URLs with TTL, and access control (FILES_SURFACE_ENABLED + per-user allowlist). Does not mention side effects (none expected).

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, first sentence provides the primary action, no unnecessary words. Information is well-organized and front-loaded.

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

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

Explains return value (metadata + download URL) and URL behavior, plus feature gates. Lacks detail on exact metadata fields returned, but adequate for a simple tool with 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?

Schema descriptions already cover 100% of parameters; the description adds a note about file_id being a cuid from list_files and that slug can be prefixed, but this is mostly redundant. Maintains baseline of 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?

Clearly states the tool fetches metadata and a download URL for a single file by id, distinguishing it from sibling tools like list_files (which lists files) and delete_file (deletes). The verb 'Fetch' and resource 'file' are specific.

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 usage context: useful for reading file contents server-side or surfacing download links. Mentions feature gating but does not explicitly compare to sibling tools or state when not to use.

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 the three text fields (html, css, js), sandboxed iframe rendering, empty surface behavior, 404 error condition, and required role. No annotations present, so description carries full burden and meets it well.

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

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

Four sentences, each serving a distinct purpose: purpose, definition, usage, edge cases/errors. No redundant information, front-loaded with 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?

For a simple read tool with no output schema, the description covers response structure, error conditions, prerequisite enumeration tool, and role requirements. No significant 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?

Input schema has 100% description coverage. Description adds value by explaining behavior when omitting or providing surface_slug, linking to list_surfaces, and clarifying the primary surface concept.

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 'Read an HTML surface's body' with a specific verb and resource. Distinguishes from sibling tools like list_surfaces (enumeration) and update_html (write).

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: mentions list_surfaces for enumeration, explains omitted surface_slug for primary surface, and specifies viewer role requirement. No explicit when-not-to-use, but sufficient 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?

No annotations are provided, so the description must fully disclose behavioral traits. It only mentions 'get' and 'activity events', but does not state that the operation is read-only, what types of events are included, or any permissions required. This leaves significant gaps for the agent.

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 extremely concise with only two sentences, front-loading the core purpose. Every word earns its place, 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?

Given the tool retrieves a list of events and has no output schema, the description should clarify what fields are returned (e.g., user, action, time). It only vaguely mentions 'who did what, when', which is insufficient for complete understanding. However, the tool is simple with only 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?

Schema coverage is 100%, with both parameters already described in the schema. The tool description adds no additional parameter meaning beyond what the schema provides, 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 tool retrieves recent activity events for a workspace, using specific verb 'Get' and resource 'recent activity events'. It distinguishes from sibling tools like 'list_workspace_members' and 'get_workspace' by focusing on activity events.

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

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

The description implies usage for 'understanding what's happened since you last looked', providing context but no explicit guidance on when not to use or alternatives. No exclusions or sibling comparisons are mentioned.

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?

No annotations provided, but the description clearly indicates a read operation with no side effects, and states the output shape matches list_rows. However, it could explicitly mention idempotency or lack of mutation.

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 concise sentences: first states purpose, second provides usage context and output behavior. No unnecessary words.

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

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

For a simple fetch tool with 2 required parameters, full schema descriptions, and no output schema needed, the description provides sufficient context: purpose, when to use, and return type.

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 minimal extra meaning beyond what the schema already provides for the two parameters.

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' and the resource 'a single row by id', and distinguishes itself from the sibling 'list_rows' by noting it does so 'without listing the full table'.

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

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

The description explicitly states when to use this tool: 'when a cue payload carries a row id and the agent only needs that one record', which helps differentiate from alternatives like 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?

No annotations are provided, so the description carries full burden. It transparently describes the tool as a read operation that returns workspace details, columns, member count, and row count. While it doesn't explicitly state 'read-only', the behavior is clear. It also explains workspace structure, which adds context beyond simple functionality.

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 plus a parenthetical, front-loaded with the core purpose. Every sentence adds value: first states function, second provides context about the data model and related tools. 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 one required parameter, no output schema, and moderate complexity (workspace structure explained), the description is complete. It tells the agent exactly what the tool does, what it returns, and how it fits into the broader API ecosystem (e.g., surfaces, list_surfaces). 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?

There is only one parameter ('slug'), and its schema description already covers the accepted formats (bare slug or org-prefixed). The tool description does not add any additional meaning beyond the schema. With 100% schema description coverage, 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 starts with 'Get details about a specific workspace by its slug, including columns of its primary table surface, member count, and row count.' This is a specific verb+resource+scope, clearly distinguishing it from siblings like list_workspaces (list all) and get_workspace_schema (schema only).

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 tells when to use this tool vs alternatives: 'Use list_surfaces to enumerate every tab; fetch /rows or /doc to read or write a specific one.' This provides clear guidance on context 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?

Discloses return format (key, label, type, position, options), behavior on doc-only workspaces (empty array but writable), and multi-surface scoping. No annotations provided, so description fully covers behavioral traits.

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?

Single paragraph packs substantial information without redundancy. Slightly long but efficient; each 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?

Covers edge cases (doc-only workspaces, multi-surface), explains return values despite no output schema, and provides sufficient detail for an agent 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?

Adds significant meaning beyond schema: explains slug accepts two forms, surface_slug optional with fallback to primary table, and references list_surfaces for discovery. Schema coverage is 100%, and description enriches both parameters.

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 'Return a table surface's column definitions' and explains the purpose ('so an agent knows what keys create_row/update_row will accept'). Distinguishes itself from sibling tools focused on data 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 context on when to use the optional surface_slug parameter and mentions list_surfaces for enumeration. Implicitly guides usage before row operations, but does not explicitly state when not to use this tool or compare to alternatives.

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

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

No annotations provided, so the description carries full burden. It discloses that agent callers see only their key, user callers see all keys for agents they own, plaintext is never returned, and key body is only shown at create/rotate time.

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 main action, and provides essential details without unnecessary 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 no parameters and no output schema, the description fully explains the tool's behavior, including caller type differences and security aspects.

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?

No parameters in schema (0 params, 100% coverage). Baseline is 4, and the description adds no parameter info as none exist.

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 'List API keys' and provides specific details on what data is returned for different caller types, distinguishing it from sibling tools.

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

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

The description explains behavior for agent vs user callers but does not explicitly state when to use this tool over alternatives or when not to use it.

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 details return limits (up to 200 comments ordered by createdAt asc), denormalization of surfaceSlug, and pagination (limit, offset). It implies read-only behavior but does not explicitly state it. No annotations are present, so the description carries the burden.

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 but packed with information. It is front-loaded with the main purpose, then details filters and return behavior. While slightly dense, 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?

Given the tool has 9 parameters and no output schema, the description covers all key aspects: filtering options, pagination, ordering, special behaviors (archive handling), and mentions a sibling tool. It is complete for an agent to use the tool effectively.

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 context beyond the schema, such as the 'surface' filter being useful for 'open threads on this tab' and that it returns 404 silently if archived. It also explains the 'author' filter as useful for agent loops.

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 'List comments in a workspace,' with a specific verb and resource. It distinguishes itself from sibling tools like `get_comment_thread` by noting its broader listing 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 explicitly tells when to use this tool (listing comments with various filters) and points to an alternative: 'Use `get_comment_thread` to pull a single comment plus its replies + reactions.' It also explains filter 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?

No annotations provided, but the description fully discloses behavioral traits: sorting, return structure, default root behavior, and gating conditions (feature flag, allowlist, error code).

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-structured with clear, front-loaded sentences. No wasted words; each sentence adds 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?

Given no output schema, description explains return structure (folders[], files[] with cuids) and covers parameters, sorting, and gating. Complete for a list 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 has 100% coverage, but description adds meaning: slug accepts bare or org-prefixed form, surface_slug from list_surfaces, parent_folder_id omission for root. Adds value beyond schema.

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

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

Clearly states the tool lists folder and file children of a Files surface, specifies sorting order, and distinguishes from sibling tools like get_file and delete_file.

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 context on when to use (listing children of a Files surface) and defaults (parent_folder_id null for root). References list_surfaces for enumeration but lacks explicit exclusions or alternatives for non-Files surfaces.

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 no annotations provided, the description carries the full burden. It discloses key behavioral traits: returns only 50 files, sorted descending, flat view, folders omitted, gated access. Missing a statement about read-only nature, but that is implied by listing.

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 compactly deliver purpose, sorting, scope, use cases, and access constraints. No fluff; 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?

Given no output schema, the description effectively explains the output (50 files, sorted, no folders) and parameter behavior. It fully equips 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% and the description adds value beyond the schema, e.g., explaining that `slug` accepts either bare or org-prefixed form and that `surface_slug` is for a 'Files-kind' surface.

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 it lists the 50 most recently updated files, sorted by `updatedAt` descending, as a flat surface-wide list ignoring folder structure. This specific verb+resource combination distinguishes it from siblings like `list_files` which may offer folder-aware navigation.

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 useful scenarios ('what changed lately', 'show me yesterday's uploads') and mentions it avoids paging. Also notes gating (FILES_SURFACE_ENABLED + per-user allowlist). Could improve by directly naming an alternative for folder-aware access, but the current guidance 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?

With no annotations, the description fully covers return format, edge cases (empty array), parameter interactions (surface_slug scope), and error conditions (400 for invalid surface_slug). It is transparent about all critical behaviors.

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 paragraph but is front-loaded with the core purpose and uses subsequent sentences efficiently to add details. Could be slightly more structured, but 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?

Given 4 parameters, no output schema, and no annotations, the description covers paging, multi-surface behavior, return structure, and error handling. It is complete for an AI agent 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 coverage is 100%, so baseline is 3. The description adds value by explaining slug formats (bare vs prefixed) and surface_slug behavior in multi-surface vs legacy mode, enhancing beyond schema.

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

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

The description clearly specifies the action (list rows), the resource (workspace table surface), and what is returned (data, creation time, creator/updater, surface_slug). It distinguishes from siblings like get_row by focusing on listing multiple 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 context for using the surface_slug parameter in multi-surface workspaces and behavior when omitted. Does not explicitly contrast with alternatives like get_row, but the usage 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?

Despite no annotations, the description fully discloses behavioral traits: it is a public read-only operation with no auth or rate limiting, returns detailed data including worked examples, and has optional filters. No contradictions exist.

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 thorough but slightly lengthy. It is well-structured with front-loaded purpose and clear details. Could be marginally more concise but effectively communicates all necessary information.

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

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

With no output schema, the description comprehensively explains return values (canonical name, signature, description, category, slice, worked examples, alias map). It covers all relevant aspects for an agent to effectively use the 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?

Input schema has 100% coverage with descriptions, but the description adds extra meaning (e.g., 'name' matches names, descriptions, and signatures; 'category' and 'slice' narrow results). This goes beyond schema explanations, earning 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 uses specific verbs ('List the Dock Sheets formula functions') and a clear resource, distinguishing it from sibling tools like update_row, create_row, evaluate_formula, and validate_formula. It conveys exactly what the tool does and why it's useful.

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 the tool: 'Use this before writing a formula via update_row / create_row so you only reference functions that actually exist (no #NAME? errors).' It also mentions the alias map, guiding the agent to pick canonical names. This provides clear context for appropriate 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?

No annotations are provided, so the description carries the burden. It explains that surfaces can be table or doc, each has a slug, order matches the tab strip, and archived surfaces are hidden by default. It does not explicitly state the tool is read-only or mention permissions, but the listing nature is implied. The description adds value but could be more explicit.

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, well-structured, and front-loaded. Every sentence adds value without redundancy. It is appropriately sized for the tool's simplicity.

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

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

Given no output schema, the description hints at the return (tells you what surfaces exist, each has slug, order) but does not specify the exact format. It covers the essential aspects of what the tool does and its parameters, making it sufficiently complete 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%, baseline 3. The description adds meaning by clarifying that 'slug' accepts either bare or org-prefixed forms and explaining the 'archived' parameter's default behavior. This enhances 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 states the tool lists surfaces (tabs) inside a workspace, explains what surfaces are (table and doc types), and mentions slug usage and order. It distinguishes from sibling tools like 'create_surface' or 'list_workspaces' by focusing on listing existing surfaces.

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 (to know what surfaces are in a workspace), mentions archived surfaces are hidden by default with an option to include them, and implies it's for exploring workspace contents. It lacks explicit when-not-to-use or direct comparisons to siblings, but 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?

No annotations provided, so description carries full burden. Discloses return fields (id, url, subscribed events, active flag, secretPreview), clarifies full secret only at create/rotate, and states org-scoping versus workspace-scoping.

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: purpose, return details, usage note. No wasted words, front-loaded with 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?

Fully describes input, output, and usage context despite no output schema. Sibling tools exist, but description sufficiently differentiates.

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 100% of params (org_slug). Description adds significant value: explains that the collection is org-scoped, not workspace-scoped, and one URL receives events from all workspaces.

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?

Clear verb+resource: 'List webhook endpoints'. Specifies scope ('on an org') and return fields. Distinct from sibling tools like create_webhook or delete_webhook.

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 usage: 'Use to audit what's subscribed before adding or removing endpoints.' Also notes any org member can list. Lacks explicit when-not, but context implies it's for read-only auditing.

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 no annotations, the description carries full burden. It discloses that email visibility depends on org membership, and that it returns only explicit access members. It does not cover auth requirements or rate limits, but for a simple list tool, this is adequate.

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 main purpose, and consists of two efficient sentences with no unnecessary 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 list tool with one parameter and no output schema, the description is complete. It explains the output structure, a usage scenario, and parameter details, leaving no obvious 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 parameter 'slug' has 100% schema coverage, but the description adds valuable detail: it accepts both bare and org-prefixed forms, and notes they resolve to the same workspace. This goes beyond the schema's description.

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

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

The description clearly states it lists principals with explicit access to a workspace, including the returned fields (users, agents, roles) and a specific use case for agents. This distinguishes it from sibling tools like share_workspace, list_workspaces, and member management 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 a clear context for when to use the tool: to list members and verify workspace sharing before writing output. While it does not explicitly state when not to use or list alternatives, the context is sufficient for appropriate tool selection.

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?

No annotations are provided, so the description must carry the full burden. The description implies a read-only operation by stating 'List all workspaces', but does not explicitly confirm idempotency, lack of side effects, or any rate limits. For a list tool, the description is adequate but not exhaustive.

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 with the main purpose upfront. The additional context about workspace definition is useful but slightly extends the length. Overall 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 has no parameters, no output schema, and no annotations, the description adequately covers the return fields and directs to a related tool. It could mention pagination or ordering, but that is optional for a simple list.

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?

There are no parameters (schema coverage 100%), and the description correctly indicates no input beyond authentication is needed. Per scoring guidelines, baseline for 0 parameters is 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 clearly states the verb 'List' and resource 'workspaces', specifying scope ('authenticated principal has access to') and return fields. It distinguishes from siblings like list_surfaces, which lists contents of a workspace.

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 directs to 'Use list_surfaces to see what a given workspace actually contains', providing clear guidance on when to use an alternative tool. However, it does not cover other sibling tools like get_workspace or create_workspace.

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 no annotations, the description fully discloses critical behavioral traits: atomicity (all-or-nothing), idempotency (skips existing rows), order preservation, event emission, and workspace validation. It also specifies the max row limit and error handling for invalid row IDs.

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 uses six concise sentences, front-loading the core action and constraints. Every sentence adds unique value: atomicity, use cases, idempotency, ordering, events, and limit.

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

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

Given no output schema, the description adequately covers return values (mentions skipped count), effects (events), errors, and limits. It provides sufficient context for the agent to invoke the tool correctly without needing additional documentation.

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% description coverage for all parameters. The description adds minimal additional meaning beyond repeating schema information (e.g., slug forms, target error). Baseline 3 is appropriate as the schema carries the semantic load effectively.

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 atomically moves rows between sheets within the same workspace. It provides specific use cases like data migration and reorganizing content, distinguishing it from sibling tools like create_row, delete_row, and 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 explicitly states when to use it (programmatic data migration, reorganizing content) and key constraints (atomic, idempotent, order preserved, max 500 rows). However, it lacks explicit guidance on when not to use or alternatives, leaving some implicit inference.

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

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

Discloses idempotency for add, row deletion for remove, per-principal uniqueness, and event firing. Since no annotations are provided, the description fully carries the burden of behavioral disclosure.

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 with no fluff, front-loaded with main purpose, efficient and informative.

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

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

Covers use cases, behavioral details, parameter semantics, and events; no output schema needed, and description is complete for the tool's 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?

Adds meaning beyond the schema by explaining idempotency, uniqueness, and example emojis, even though schema coverage is 100%.

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?

Explicitly states 'Add or remove an emoji reaction to a comment' with specifics about uniqueness per principal, clearly distinguishing from siblings like add_comment or reply_to_comment.

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 use cases for lightweight agent acknowledgement (👍, 👀, ✅) and states it's cheaper than a full reply, but does not explicitly mention when not to use the tool.

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

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

With no annotations, the description carries full burden. It comprehensively discloses required role (editor), owner-tier constraints, sole-owner block, org-visibility effect on virtual access, and the two-step consent process. 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?

Though lengthy, every sentence provides necessary behavioral context. Front-loaded with core action. Minor verbosity justified by 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?

Covers all critical aspects: role requirements, edge cases (sole owner, org visibility), consent flow details, and return shape. No output schema needed as description handles return information.

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

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

Schema coverage is 100%, and description adds significant value: slug accepts org-prefixed form, member_id sourced from list_workspace_members, confirm_token explained with consent flow and TTL.

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 'Remove a workspace member,' a clear and specific verb-resource pair. It distinguishes from sibling tools like update_workspace_member and list_workspace_members by focusing on removal.

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 not to use (sole owner removal blocked) and provides detailed consent-gated flow instructions. However, it does not directly compare with alternatives like update_workspace_member for membership changes other than removal.

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 no annotations provided, the description carries full burden. It discloses that the tool is a wrapper, re-opens resolved parents, and flattens nested replies (reply-to-reply re-points at the root). It also references 'same threading rules as add_comment' which is adequate given the tool is a convenience wrapper. However, it does not fully detail the threading rules, but the key behaviors are covered.

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

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

The description is concise (three sentences), front-loaded with purpose, and each sentence adds unique value: purpose, convenience aspect, and edge cases (re-opening parent, threading rules). There is no redundant or extraneous 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 convenience wrapper with 3 parameters and no output schema, the description covers the core functionality and important behavioral details (re-opening resolved, flattening). It references add_comment for additional threading rules, which is sufficient. A minor gap is the lack of explanation about the mental parameter, but it is optional and described in 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?

Schema description coverage is 100%, so baseline is 3. The description mentions passing 'parent comment id and the body' which corresponds to required params, but adds no new semantic detail beyond what the schema already provides. The mention of 'mentions' is not described in the description, but the schema covers it. The description does not enrich parameter understanding.

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 is a 'convenience wrapper around add_comment for the common reply case.' It specifies the action (reply), the resource (comment), and distinguishes from add_comment by noting that it reconstructs the target from the parent, eliminating the need for the agent to know the parent type. This differentiates it from sibling tools like add_comment and react_to_comment.

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 this tool: for replying to comments. It mentions that it re-opens a resolved parent and has the same threading rules as add_comment. It does not explicitly state when not to use or provide alternatives, but as a convenience wrapper, the context is clear. The mention of 'no need for the agent to remember whether the parent was a row, cell, etc.' provides implicit 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?

Discloses the one-way nature and that it records a signal on admin side. With no annotations, this adds value, though it could mention potential side effects or processing guarantees.

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, no wasted words, front-loaded with the action and scope.

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?

Adequately covers the purpose and usage for a simple request tool. Could mention the return value (e.g., confirmation) but not critical given 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?

Schema coverage is 100%, so the description adds only marginal context. It repeats the enum values but doesn't elaborate 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 states the tool requests a plan limit increase, lists the specific limits (agents, workspaces, rows, other), and distinguishes from upgrade_plan by giving an example (already Pro needing custom limit).

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

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

Explicitly tells when to use ('when you hit a cap you can't resolve with upgrade_plan') and what to expect ('no reply loop', 'record the signal'). Provides a concrete scenario.

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?

No annotations are provided, so the description carries the full burden. It discloses the return value shape, approval gate (owner must match), and polling mechanism. It also mentions that the reason appears verbatim on the consent card. However, it does not discuss error cases (e.g., non-existent target agent) or rate limits, which would improve completeness.

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

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

The description is front-loaded with the core purpose and differentiation. Each sentence adds meaningful information without redundancy. It is appropriately sized for the tool's complexity, and the structure flows logically from purpose to behavior to parameter hints.

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 moderate complexity and lack of output schema, the description covers all essential aspects: purpose, usage triggers, return format, approval mechanism, and parameter guidance. It leaves no major gaps for an agent to make a mistake.

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% (both parameters documented in schema). The description adds value by explaining that `reason` 'surfaces verbatim on the consent card' and that `target_agent_id` can be obtained from `list_workspace_members` or `list_workspaces`. This extra context helps the agent understand how to populate the parameters correctly.

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 action: 'Ask the human owner to revoke ANOTHER agent's active API key (sibling agent).' It immediately distinguishes itself from the sibling `revoke_api_key` tool by noting that tool is self-only. This provides a specific verb and resource with clear differentiation.

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

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

The description explicitly states when to use this tool: 'when you've spotted credential leakage, misbehaviour, or a stuck sibling that needs a clean kill.' It also contrasts with `revoke_api_key` by calling it 'self-only by design,' making the alternative clear. This provides both context and exclusion criteria.

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

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

Discloses critical behaviors: human owner must click approval, returns an approval_url, the new key plaintext is intentionally not returned to the requesting agent, and it is surfaced only to the human owner via Settings. Since no annotations are provided, the description fully carries the burden.

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

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

The description is front-loaded with core purpose and action, followed by important caveats. It is a few sentences long but not overly verbose. Could be slightly more concise, but overall 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?

Despite no output schema, the description explains the return value (approval_url) and the workflow. It covers the purpose, usage, behavior, and parameter rationale completely for a tool that initiates an approval flow.

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

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

Input schema covers both parameters with descriptions. The description adds context: reason is surfaced on consent card and capped at 500 chars, target_agent_id is a sibling agent. It also explains the rotation process (mint new + revoke old), adding value beyond schema.

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

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

The description clearly states it rotates another agent's API key with human owner approval. It distinguishes from sibling tools like request_revoke_agent_key and rotate_api_key by specifying the rotation action and the requirement of human involvement.

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

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

Explicitly specifies when to use: 'Use when you've spotted leakage and the target needs a clean credential without going dark mid-task.' It contrasts with similar tools by noting it requires human owner approval and does not return the new key.

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 idempotency and fired event 'comment.resolved' without annotations. Could mention auth requirements but adequate for a simple action.

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 concise sentences, each serving a distinct purpose: action, idempotency/event, and usage context with sibling.

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 purpose, behavior, parameter semantics, and usage context completely. No output schema needed; idempotent return value mentioned.

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?

Adds meaning beyond schema by clarifying thread root vs reply behavior for comment_id, which is not in the schema description.

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

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

Clearly states the action 'Mark a comment thread resolved' with specific verb and resource. Distinguishes from sibling 'unresolve_comment' and explains usage 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?

Explicitly mentions pairing with unresolve_comment, idempotency behavior, and the use case of closing a feedback thread after iterating on 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?

With no annotations, the description fully discloses behavior: it's a soft-delete via revokedAt, subsequent requests return 401, calling is effectively a self-destruct for agents, and the response completes but the next request fails. This is comprehensive.

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 and front-loaded, but slightly verbose with multiple clauses. Each sentence adds value, so it's still efficient. A minor trim could make it more concise.

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 optional param, no output schema, no annotations), the description covers all essential aspects: purpose, usage, behavior, and parameter semantics. It is complete and leaves no ambiguity.

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

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

The schema has one optional parameter 'id' with 100% coverage. The description adds crucial context: 'Omit when called by an agent; defaults to the agent's own current key.' This explains the default behavior, which is not obvious from 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 'Revoke an API key (soft-delete via revokedAt)' and distinguishes it from the sibling tool 'rotate_api_key'. It uses specific verb 'revoke' and resource 'API key', making the purpose unambiguous.

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

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

The description explicitly says 'Agents may revoke ONLY their own key' and 'Users may revoke any key they own'. It also provides a clear alternative: 'To swap creds without going dark in the gap, use rotate_api_key instead.' This gives complete when-to-use and when-not-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?

With no annotations, the description carries full burden. It discloses that revocation is 'soft' (implying possible reversibility), idempotent with a specific return field, requires editor role, and is gated behind feature flags. It does not detail error cases for invalid tokens, but the idempotent nature implies graceful handling.

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 essential: the action and effect, the idempotency behavior, and the access requirements. No unnecessary words, and the most critical information comes first.

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

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

Given no output schema, the description adequately explains the return behavior (idempotent with alreadyRevoked: true) and prerequisites. It could mention that the token must exist, but the idempotency statement covers the case of already revoked. Overall, it provides sufficient context for an agent to use 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 has 100% coverage, but the description adds critical context: the token_id must be the internal id from share_file or list_file_shares, not the URL token. This prevents misuse and adds 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 clearly states the tool soft-revokes a share token, specifies the immediate effect (URL stops resolving), and distinguishes itself from share_file (which creates tokens) and list_file_shares (which lists tokens). The mention of 'idempotent' further clarifies behavior.

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 prerequisites (Editor role, feature flags, allowlist) and mentions idempotency, which guides correct usage. However, it lacks explicit guidance on when not to use this tool or alternatives beyond the implied context of revoking a previously shared token.

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

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

Discloses atomicity, return of new plaintext only once, invalidation of old key (401), and authorization constraints. No annotations provided, so description fully carries the transparency burden 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 sentences with front-loaded core action. Every sentence adds value: atomic operation, return handling, behavioral warning, authorization rules, and use cases. 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?

Covers all necessary information for safe tool invocation: what it does, side effects, return value handling, caller permissions, and when to use. For a single-parameter tool with no output schema, this is comprehensive and leaves no critical gaps.

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

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

The input schema already provides a complete description for the single `id` parameter (100% coverage). The tool description adds no new information about the parameter beyond the schema, so it meets the baseline but does not enhance 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 defines 'rotate' as atomically minting a new API key and revoking the old one, specifying preserved attributes (agent, workspace, scopes, name). This distinguishes it from sibling tools like 'revoke_api_key' which only revokes, and 'request_rotate_agent_key' which is a request action.

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: use for routine credential hygiene or after a suspected leak. Specifies who can use it (agents vs. users) and how to handle the `id` parameter. Includes practical guidance on storing the key and swapping credentials before retrying due to 401 on old key.

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 no annotations, description fully discloses behavioral traits: secret returned exactly once, must copy to receiver before next event, after call new secret only, old receivers will 401 until updated. Covers single-use nature and authentication implications.

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 concise sentences with no redundancy. Front-loaded with action, then critical usage details, then use case examples. 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?

For a tool with no output schema, description explains return value ('new secret returned exactly once'), behavior, and consequences. Covers all necessary context for an agent 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?

Input schema already describes both parameters (org_slug, webhook_id) with 100% coverage. Description adds no additional semantic meaning beyond what schema 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 starts with 'Mint a fresh signing secret for a webhook,' clearly stating the verb and resource. It distinguishes from sibling tools like create_webhook or update_webhook by focusing specifically on secret rotation.

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: 'after a suspected leak or as part of routine rotation hygiene.' Also explains consequences of use (new secret only, old rejects). No explicit when-not-to-use or alternatives, but context 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?

No annotations provided, so description carries full burden. It discloses that results are ranked (score 0-1), include navigable URLs, and are access-gated (no results from inaccessible workspaces). Lacks mention of whether it's read-only (implied) or any rate limits, but covers key behaviors.

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: first defines scope, second explains output and access, third gives use case and comparison. 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?

Given no output schema, description adequately explains return format (ranked hits with score and URL) and covers all parameter semantics. Combined with schema, it provides a complete picture for an agent to use the tool effectively.

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%, baseline 3. Description adds value by explaining the use cases for each 'kind' enum ('workspace is fastest when naming something', 'row targets table data') and clarifying default behavior for 'all'. This goes beyond the schema's brief descriptions.

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

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

The description clearly states the tool's verb ('Search') and resources ('workspace names, row cell values, and doc sections/paragraphs'). It distinguishes itself from sibling tools by emphasizing speed and scope, avoiding tautology.

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 the user references something by keyword') with concrete examples. Contrasts with listing tools by claiming it's faster than iterating, providing clear guidance on 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?

With no annotations, the description carries the full burden. It comprehensively discloses behavioral traits: sender identity follows caller, body cap of 32,000 chars, return format, recipient resolution scope, and error condition for pre-deploy environments. 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 thorough but slightly verbose. It front-loads the main purpose and usage guidelines, but includes details like pre-deploy behavior that could be in a separate note. Still, 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?

Given the complexity (4 parameters, no output schema, no annotations), the description fully covers the tool's behavior, error handling, and return value. No gaps remain for the agent to guess.

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

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

Schema coverage is 100%, but the description adds significant context: explains address format in detail, mentions scheduling alias, and specifies where to get thread IDs. This goes beyond the 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 action ('Send a direct message'), the target ('another agent or human'), and the medium ('messaging substrate'). It uniquely identifies the tool's purpose among siblings, as no other tool handles direct messaging.

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 the tool ('legitimately needs to ask a teammate for help, hand off work, follow up async') and when not to use it ('don't use it as a chat-ops side-channel for things that belong in workspace events'). This helps the agent select appropriately.

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 no annotations, the description fully covers behavioral traits: public access, high-entropy token, editor role requirement, feature flag gating, and revocation via sibling tool.

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

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

Five concise sentences with no redundancy, each serving a distinct purpose: action, output, security, lifecycle, and prerequisites.

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 needed aspects despite no output schema: explains the return URL format, prerequisites, and security. Comprehensive for a 2-parameter tool.

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

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

Schema coverage is 100% and both parameters are well-described in the schema. The description adds no additional meaning beyond what is already 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 clearly states 'Mint a public share token for a file.' with a specific verb and resource, and distinguishes from siblings by mentioning revocation and referencing external system handoff.

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 use case: 'when a workflow needs to hand the file off to an external system that can't authenticate.' Does not include when not to use, 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?

With no annotations, the description fully discloses behavioral traits: immediate invite for existing users with notification, 7-day token for new users, emitted events (member.joined or member.invited), and required editor role.

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 4 sentences, moderately concise, and well-structured: main action first, then behavior details, prerequisites, events, and alternative tools. Slightly verbose but effective.

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?

While it covers main business logic and events, it lacks explanation of return value or error conditions (e.g., invalid email, duplicate invite). For a medium-complexity tool with no output schema, this is adequate but not fully 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%, baseline 3. The description adds value by noting that role defaults to editor and that owner-tier requires owner caller, and that slug accepts both bare and org-prefixed forms. This enriches 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 states the tool invites a human by email to a workspace at a specified role, and distinguishes itself from sibling tools by mentioning update_workspace_member and remove_workspace_member for subsequent actions.

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 says when to use this tool (to invite) and when to use alternatives (update_workspace_member for role changes, remove_workspace_member for revocation). Also specifies required editor role, providing clear 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?

Given no annotations, description fully discloses side effects: fires 'comment.unresolved' with 'reason: manual'. Also notes idempotent behavior and explains difference from auto-unresolve on reply. 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?

Two sentences with zero wasted words. First sentence states primary action and target state. Second sentence adds idempotency and event details 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?

For a simple tool with one required parameter and no output schema, description covers all essential aspects: action, idempotency, event firing, and distinction from related tools. Avoids unnecessary detail.

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?

Single parameter 'comment_id' with schema description 'Comment id to re-open.' Description adds no additional meaning beyond schema. Schema coverage is 100%, 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?

Description clearly states verb ('re-open') and resource ('previously-resolved comment thread'). Contrasts with sibling tool 'resolve_comment' by being the inverse operation.

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?

Mentions idempotency on already-unresolved comments, which guides safe usage. Also distinguishes auto-unresolve on reply from manual unresolved, directing agent to use other tools for reply context. Lacks explicit when-not-to-use scenarios but sufficient for most 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?

Discloses last-write-wins, no CRDT merge, events emitted (doc.updated, etc.), editor role requirement, format caps (e.g., max images, videos), cross-ref and mention behavior, and conflict handling with if_unmodified_since. No annotations provided, so description carries full burden and does so comprehensively.

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?

Despite length, the description is well-structured with bullet points and clear sections. Front-loaded with purpose and usage, then detailed feature explanations. Every sentence adds necessary information for a complex 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?

Given 5 parameters, no output schema, and many sibling tools, the description is thoroughly complete. Covers input formats, features, limitations (caps), side effects (events, notifications), permissions, and conflict handling. 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 significant value beyond schema: explains markdown vs TipTap usage context, details supported markdown features (images, videos, diagrams, etc.), cross-ref syntax, mention behavior, if_unmodified_since conflict resolution, and surface_slug purpose.

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 replaces a workspace doc body, provides two input formats (TipTap JSON or Markdown), and distinguishes from the sibling tool 'append_doc_section' which is for append-only updates.

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

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

Explicitly tells when to use markdown (prose from scratch) vs TipTap JSON (structural edits from get_doc), mentions the dedicated append_doc_section tool, and advises on if_unmodified_since for multi-agent flows, with explicit when-not-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?

With no annotations, the description fully discloses behavioral traits: section semantics (first heading match, replacement range to next same/shallower heading), error for missing heading (404), behavior for empty markdown (deletes section), note about @-mention events, and permission requirement (editor role). It also clarifies multi-surface workspace optionality. This is comprehensive.

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 sentence earns its place, providing essential details. It is front-loaded with the core purpose and use case. A minor deduction because it could be slightly tighter (e.g., combining the section semantics and markdown notes), but overall 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?

Given four parameters, no output schema, and no annotations, the description covers all needed context: purpose, when to use, behavioral details (section replacement boundaries, error handling, deletion behavior), parameter specifics (heading matching, markdown requirements), event behavior (@-mention events), and permissions (editor role). It is thoroughly 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%, so baseline is 3, but the description adds significant meaning: it explains how `heading` is compared (case-sensitive, trimmed, hash marks stripped), that `markdown` must include the heading line, that empty string deletes the section, and that `surface_slug` is optional. It also suggests using `get_doc` to enumerate headings. This goes well beyond the 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 starts with a clear verb-object pair: 'Replace a single section of a workspace's doc body, identified by its heading text.' It explicitly names sibling tools (`update_doc`, `append_doc_section`) and explains how this tool differs as 'the targeted edit complement.' This meets the 5-criterion of specific verb+resource and sibling differentiation.

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

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

The description provides explicit when-to-use advice: 'Use this when the agent maintains a recurring section ... and only needs to refresh that one piece.' It also explains why alternatives are worse (token cost, latency, race condition with concurrent edits). This exceeds the 5-criterion of explicit when/when-not/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?

With no annotations, the description thoroughly covers behavioral traits: sandboxed iframe, origin isolation, supported web technologies, per-field caps, sanitization rules, and required role. It does not mention error handling or output format, but overall provides strong 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 dense yet well-structured, front-loading the core action and proceeding logically through fields, security, capabilities, limits, and requirements. 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?

The description covers all key aspects: parameters, limits, security, and prerequisites. It lacks explicit mention of the return value or success indication, but given the standard nature of update tools, it is reasonably complete. Sibling tool overlap is not addressed.

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

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

Schema coverage is 100%, and the description adds meaningful context beyond the schema, such as v2 usage tips for js and css fields, external stylesheets, and pre-flighting with validate_html. This enhances the agent's understanding of parameter usage.

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 writes an HTML surface's body, specifying the verb and resource. However, it does not explicitly distinguish this tool from sibling tools like update_surface or validate_html, leaving some ambiguity.

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 that omitted fields stay unchanged and empty strings clear fields, providing usage context. It also mentions using validate_html first. But it lacks explicit guidance on when to use this tool versus alternatives like update_surface or create_surface.

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 no annotations, the description fully discloses behavioral traits: only provided fields are updated, move behavior with position recomputation, unmapped field storage, auto_create_columns behavior, response fields (unmapped_fields, warning, created_columns), and events (row.moved_surface). 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?

Every sentence serves a purpose. The description is front-loaded with the core update purpose, then explains move behavior, then unmapped data details. No redundant or unnecessary text. Concise yet comprehensive.

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 6 parameters, no output schema, the description explains expected response fields (unmapped_fields, warning, created_columns) and events. Covers error conditions (400 for invalid surface_slug). For a mutation tool with complex behavior, this is complete and actionable.

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%, baseline 3. The description adds significant behavioral context for each parameter: 'data' explicitly allows empty object for moves, 'slug' explains prefix forms, 'position' clarifies default placement, 'surface_slug' details move conditions and errors, 'auto_create_columns' explains effect and defaults. This goes beyond the 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 'Update specific fields of an existing row' with a specific verb and resource. It distinguishes from siblings like 'create_row' and 'delete_row' by detailing update-specific behaviors (field preservation, move semantics, unmapped data handling). No ambiguity.

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 auto_create_columns, when to pass empty data for a pure move, and conditions for surface_slug (400 errors). It does not explicitly compare to alternatives like 'move_rows', but the context is clear enough for most agents. Slight deduction for lack of direct alternative mention.

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 no annotations, the description discloses key behaviors: atomic column replacement, position normalization, event emission, error for wrong surface kind, and data preservation. It does not cover rate limits or idempotency but is otherwise thorough.

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-organized, starting with a summary then detailing column schema specifics. It is slightly lengthy but every sentence adds value, earning a high 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?

Given the tool's complexity (multiple update types, column schema replacement), the description covers prerequisites, error cases, and behavioral details. No output schema exists, but the description suffices for correct 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?

Schema coverage is 100%, and the description adds significant context beyond the schema, such as replacement semantics for columns, position normalization, and uniqueness requirement for new_surface_slug. This greatly aids correct invocation.

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 does multiple operations: 'Rename, reslug, reorder, OR replace the column schema of a surface.' This is specific and distinguishes it from siblings like create_surface or add_column.

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 guidance on passing a subset of fields, role requirement ('Editor role'), and a recommended workflow ('Use get_workspace_schema first'). However, it does not explicitly contrast with sibling tools like add_column, though the differentiation is implicit.

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

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

With no annotations, the description carries full burden. It discloses that inactive webhooks are skipped, no retry queue, no log row, and endpoint config preserved. This provides behavioral context beyond the parameter schema, though it doesn't mention any potential side effects beyond what's intended.

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 adding value: first states the action, second explains the effect when inactive, third gives a concrete use case. No wasted words, front-loaded with primary 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 toggle tool with 100% schema coverage and no output schema, the description is complete. It covers purpose, effect of both states, and a recommended use case, making it fully actionable 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?

Schema coverage is 100% with clear parameter descriptions. The description reinforces the meaning of active flag (enable/silence) but doesn't add new information beyond what 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 clearly states the tool's action: 'Toggle a webhook's `active` flag on or off.' This is a specific verb+resource pair that distinguishes it from siblings like create_webhook, delete_webhook, and rotate_webhook_secret.

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

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

The description provides explicit usage guidance: 'Use to silence a noisy receiver during maintenance without losing its URL + secret + event subscription.' It explains effect of toggling off (no retry, no log row) and that config is preserved, making it easy to flip back. It does not explicitly mention when not to use, but the use case is clear.

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