Dock

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

With no annotations, the description carries the full burden and does so thoroughly. It discloses the auto-computed position, the 409 key collision error, the editor role requirement, and the surface fall-through behavior. These go well beyond the basic mutation and give the agent critical operational context.

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

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

Every sentence earns its place: purpose, positional invariant, collision error, permission, alternative usage, and surface behavior are each addressed without redundancy. The description is front-loaded with the primary purpose and remains tight despite the complexity.

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

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

Given 8 parameters, no annotations, and no output schema, the description is remarkably complete. It covers purpose, error handling, permissions, alternatives, and an edge case (multi-surface workspaces). The only minor omission is the return format, but that is not essential for tool selection.

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, but the description adds meaningful semantics beyond the schema. It explains that surface_slug targets a specific table sheet and falls through to the primary surface when omitted, and that position is auto-computed. This enriches parameters not fully captured in the schema.

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

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

The description states 'Append a single column to a workspace's table schema' with a specific verb and resource. It distinguishes this per-column addition from full schema replacement or reordering, making its purpose clear relative to 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?

Explicit guidance is given: 'Use this for per-column additions; use get_workspace_schema + update_workspace_columns (PUT on /columns) for full schema replacement or reordering.' It also mentions the editor role requirement and surface_slug targeting for multi-surface workspaces, covering when and 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 provided, the description fully carries the behavioral disclosure burden. It reveals nested reply flattening, auto-unresolving of resolved parents, mention access validation, fired events (comment.added, comment.unresolved), and the required role—all critical side effects beyond a simple 'post' 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?

Four sentences, each dense with value: purpose, target scope, threading rules, mentions, events, alternative guidance, and role requirement. No wasted words, and the most important information is front-loaded.

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

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

Given the tool's high complexity (polymorphic targets, threading, mentions, events) and no output schema, the description covers all essential aspects: what it does, how to use it, behavioral consequences, prerequisites, and sibling alternatives. It is fully sufficient for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds semantic value by explaining the polymorphic target shapes mirror the REST endpoint, detailing mention triples and their validation, and clarifying parentId's threading behavior—context beyond the schema's parameter descriptions.

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

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

The description opens with 'Post a new comment on any target in a workspace' and enumerates specific target types (row, cell, doc range, html element, surface, workspace). This specific verb+resource+scope clearly identifies the tool's function and distinguishes it from sibling tools like 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?

Explicitly states when to prefer a sibling tool: 'For replies to existing comments where you don't want to reconstruct the target, prefer reply_to_comment.' It also provides usage context with role requirements and threading behavior via parentId, giving clear when-to-use guidance.

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

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

With no annotations provided, the description fully carries the behavioral disclosure burden. It explains semantic nuances beyond a simple list: `address` can change due to renames, `agentId` is stable, and `send_message` can strand messages because it doesn't wake the recipient. It also discloses what the tool returns (status fields, brandKey, ownerAddress) and explicitly states it takes no arguments. This is rich, honest behavioral context.

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

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

The description is long but every sentence serves a purpose — no filler. It is front-loaded with the core function, uses bullet points for the three identity fields, and ends with a clear rule of thumb. The length is justified by the need to explain subtle identity semantics and cross-tool warnings.

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 compensates by detailing the returned fields: identity fields (`name`, `address`, `agentId`), status indicators (`online`/`alive`/`listening`), `brandKey`, and `ownerAddress`. It also covers usage context, cross-tool interactions, and storage best practices. The tool is simple (no args) and the description fully equips an agent to use it 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 tool has zero parameters and the schema is an empty object. The description explicitly states 'Takes no arguments,' which is the only relevant semantic. Per the rubric, 0 params gets a baseline of 4, and this description adds an explicit confirmation, so a 5 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 opens with a specific verb and resource: 'Lists the agents you can reach — your own agents AND agents shared to you from other owners.' It clearly distinguishes itself from messaging tools by directing users to `message_teammate` for messaging, and it explicitly contrasts with `send_message`. The scope is unambiguous, covering both own and shared 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?

Provides explicit when-to-use guidance: to see reachable agents. It also gives concrete alternatives and exclusions: 'To MESSAGE any of them, use the `message_teammate` tool' and 'Do NOT use send_message for an agent — that path does not wake them.' Additionally, it prescribes which identity field to use for different purposes ('read the name, use the `agentId` to message and to store'), which is actionable usage direction.

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 transparency burden and delivers extensively. It discloses non-idempotency, same auth/events/guards as update_doc, the @-mention firing behavior (only newly-added mentions), the editor role requirement, and multi-surface handling via surface_slug. This goes well beyond a minimal 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?

The description is front-loaded with the core action, then the use case, then details. The markdown feature list is long but each item is specific and relevant to the tool's behavior. Every sentence earns its place, and there is no redundant repetition of schema 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 tool of this complexity, the description covers all critical aspects: purpose, use cases, supported markdown features, implementation mechanics, safety guards, non-idempotency, @-mention behavior, auth requirements, and multi-surface handling. No output schema is provided, but the description sufficiently covers what the operation does without needing to specify return values.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning by clarifying that the markdown 'becomes one or more new blocks at the end' and that surface_slug is for 'multi-surface workspaces' to append to a specific tab. It also enriches the markdown parameter by listing supported markdown features, giving the agent a clearer sense of what can be passed.

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

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

Opens with a specific verb+resource+location: 'Append a chunk of Markdown to the END of a workspace's doc body.' This clearly distinguishes it from siblings like update_doc and update_doc_section, which modify rather than append. The mention of 'changelog updates, daily standups, batch summaries' further contextualizes its intended use.

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

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

States it is 'Designed for crons + ingest agents that produce content in timestamped chunks,' providing clear when-to-use guidance. It references the 'same markdown surface as update_doc' and warns that 'Append is non-idempotent by design,' implying when not to use it (e.g., when idempotency is required). However, it does not explicitly name alternatives for other use cases, so it falls short of a 5.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It reveals that unmapped fields are stored but not rendered, that auto-create columns happen atomically with humanised labels, and that responses include unmapped_fields, warning, and created_columns. It also discloses fallback to the primary table surface and auto-seeding on empty tables.

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 structured into three targeted paragraphs with bold headers, leading with the core action. Each paragraph earns its place by covering primary behavior, unmapped-field handling, and the auto-create option without 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?

Even without an output schema, the description covers return values (unmapped_fields, warning, created_columns) and error contexts (invalid surface_slug yields 400, noted in the schema). It fully explains edge cases like empty tables, multi-surface workspaces, and unmapped data, providing everything an agent needs 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?

The input schema documents all four parameters, but the description adds substantial meaning: data keys map to column names, status accepts a fixed set, surface_slug has explicit fallback behavior, and auto_create_columns is explained with atomic creation and return metadata. This goes far beyond the schema's simple property descriptions.

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

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

The description opens with 'Append a new row to a workspace's table surface,' a specific verb+resource that clearly distinguishes it from siblings like update_row and delete_row. It also identifies the data field as a JSON object with column-name keys and lists allowed status values, making the tool's purpose unmistakable.

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

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

The description explicitly instructs when to use surface_slug (multi-surface workspaces) and points to list_surfaces as the enumeration method. It differentiates when to use auto_create_columns (machine-emitted rows) versus omitting it for explicit schema control, and names add_column as an alternative for handling unmapped fields.

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 for behavioral disclosure. It discloses that the ticket creates a GitHub issue and appears in the user's dashboard, which are important side effects. However, it does not mention any permissions or rate limits, though these are less critical for a support ticket creation tool. The disclosed side effects go beyond basic semantics.

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

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

The description is three sentences and every sentence provides necessary information: the action and side effect, the list of use cases, and the explicit alternative. It is front-loaded with the verb and resource, and contains no filler or redundancy.

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

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

Given the tool's complexity (5 parameters, nested object, no output schema), the description covers the core purpose, use cases, side effects, and an alternative. It does not explain return values, but the lack of an output schema makes that less critical. The attachment URL requirement is covered by the schema, so this is reasonably complete.

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

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

Schema description coverage is 100%, so each parameter is already documented in the schema. The description adds general guidance about what kinds of tickets to file, but it does not add detail about parameter formats or constraints beyond the schema. This meets the baseline expectation but does not exceed it.

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

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

The description uses a specific verb ('File a support ticket') and clearly identifies the resource, then elaborates on the side effects (mirrors to GitHub issue, appears in dashboard). It distinguishes from the sibling tool request_limit_increase by name, so there is no ambiguity about what this 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 explicitly lists when to use this tool (bugs, feature requests, billing, questions, anything else) and explicitly says to prefer request_limit_increase for plan cap issues. This provides clear guidance on alternatives and exclusions, far beyond a vague 'use when needed'.

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 and does so richly. It discloses auto-slugification and collision handling, columns being ignored for doc/html, html surfaces starting empty, files starting empty with a note about human file upload, the editor role requirement, and the emitted surface.created event. This is far beyond a minimal 'creates a surface.'

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

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

The description is a single dense paragraph that front-loads the purpose, then systematically covers kinds, optional parameters, and per-kind behavior. Every sentence contributes useful, non-redundant information, and there is no fluff or repetition.

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

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

The description covers many behavioral aspects (roles, events, kind-specific details) but misses a critical piece: how to specify the target workspace. The required `slug` parameter is not addressed at all, and the misnamed `slug`/`surface_slug` confusion further harms completeness. With no output schema, the description also does not state what the API returns, though the emitted event is 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?

The description uses `slug` to refer to the optional surface slug but the schema's `slug` parameter is required and is the workspace slug, while the actual optional surface slug parameter is `surface_slug`. This misnaming directly contradicts the schema and can mislead an agent into thinking the required `slug` is optional. It also fails to mention the required workspace slug parameter at all, offering no guidance on how to specify the workspace. Despite 100% schema coverage, the description's parameter explanation is actively harmful.

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

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

The description opens with a clear imperative 'Create a new surface (tab) inside a workspace,' specifying the verb and resource. It also differentiates from siblings like 'update_surface' and 'create_workspace' by enumerating the four surface kinds and their distinct behaviors.

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 tool and gives tool-specific alternatives for downstream actions: html surfaces should be written via update_html, files surfaces browsed via list_files/get_file/list_recent_files. It also notes the editor role requirement and the agent byte-upload limitation. However, it does not explicitly state 'use this instead of update_surface for creation,' though that is implied.

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 important behaviors: URL validation at creation and DNS re-validation at delivery, empty events array semantics, and the one-time return of the signing secret for HMAC verification. These are critical operational details beyond a basic 'create' 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?

The description is three sentences, front-loads the purpose, and packs in essential details (URL constraints, events filter, secret handling) without any 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 the tool's complexity and the absence of an output schema, the description is complete: it covers the return value (secret), the URL validation behavior, events filtering semantics, and hints at the HMAC verification workflow. No obvious gaps remain for an agent to use it 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 meaningful context beyond the schema: it explains the events array behavior (empty means none, must pass at least one) and the URL delivery-time DNS validation, which are not in the schema's field descriptions. This raises the score.

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

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

The description opens with 'Register a new webhook endpoint on an org,' which is a specific verb+resource statement. It clearly distinguishes this creation tool from siblings like update_webhook, delete_webhook, and list_webhooks.

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 purpose clearly implies when to use the tool (creating a new webhook). It provides guidance on the events array (must pass at least one) and URL requirements. However, it does not explicitly name alternatives or state when not to use this tool versus update/delete/rotate counterparts.

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 carries the burden and does so richly: agent-created workspaces attribute to the agent and enroll the owning user as co-owner, default to org-visibility to avoid 403s, seed different tab types per mode, resolve mode from initial_markdown, and return a guided error when neither is provided. It also explains html is only picked when explicitly requested and that markdown is converted server-side.

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

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

The description is a single dense paragraph, but each sentence contributes a distinct piece of context (caller types, seeding behavior, mode selection, error fallback, markdown handling). It could be split into bullets for readability, but it is not wasteful; it front-loads the core creation purpose.

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

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

The description covers creation behavior, mode resolution, error cases, visibility defaults, and markdown conversion. With a fully described schema and no output schema requirement, this is complete for a creation tool. It leaves no ambiguity about what happens when mode is omitted or when html is chosen.

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, but the description adds meaning beyond the schema by explaining the decision logic between mode, initial_markdown, and the guided error. It also expands on when to choose each mode based on the content type (prose vs records vs mockup), which the schema only hints at.

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

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

The description opens with a specific verb+resource: 'Create a new workspace in the caller's org.' It clearly distinguishes from siblings like delete_workspace, update_workspace, and list_workspaces by focusing on the creation act and initial surface seeding.

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: 'Decide the surface before you create' with prose→doc, records→table, and html opt-in only. It also names alternatives: 'Add more tabs of any kind later via create_surface' and advises using initial_markdown 'instead of create + update_doc with hand-built JSON.' The guided-error fallback is a clear when-not-to-use signal.

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 and does an excellent job. It discloses that the deletion is soft, moves to a 30-day trash window, and that a cleanup cron will eventually hard-delete and refund storage quota. It also states the restore path, permission requirement (Editor role), and feature gating (FILES_SURFACE_ENABLED + allowlist). This gives the agent a complete picture of side effects and prerequisites.

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

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

The description is three sentences, each adding significant value. It front-loads the primary action, then provides crucial details about retention, restoration, permissions, and feature gating. There is no redundancy or filler, making it highly concise and well-structured.

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

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

Given the tool's complexity (soft-delete lifecycle, restoration, permissions, feature flag), the description covers all essential aspects. There is no output schema, but for a delete operation the return format is low-value; the description focuses on the behavioral nuances that matter. It even mentions the future PATCH-equivalent MCP tool, showing forward-looking completeness.

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

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

Schema description coverage is 100%, so the schema already documents both parameters ('slug' and 'file_id') with descriptions. The tool description adds minimal extra meaning to the parameters beyond saying 'by id', which maps to 'file_id'. Therefore, the baseline of 3 is appropriate; the description does not need to add more, and it does not.

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 specific verb+resource: 'Soft-delete a file by id.' This clearly distinguishes it from sibling delete tools (delete_workspace, delete_surface, etc.) and from hard-delete operations. The additional detail about the 30-day trash window and restoration reinforces the exact 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 clear context for when to use this tool: to soft-delete a file with a recovery window. It explicitly mentions the REST PATCH endpoint for restoration and a future MCP tool, indicating when an alternative should be used. However, it does not explicitly say when not to use this tool versus other delete operations, but the soft-delete vs. hard-delete distinction is implied.

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 transparency burden. It explicitly states 'Permanently delete' and 'This action cannot be undone,' clearly conveying the critical behavioral trait of irreversibility. However, it does not disclose other potential behaviors such as permission requirements or cascading effects, leaving minor 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 two sentences, each with clear purpose. The first states the action and target, the second emphasizes irreversibility. There is no filler or redundant information, making it both concise and well-structured.

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

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

For a simple deletion tool with two well-documented parameters and no output schema, the description covers the essential behavior and the irreversible nature. It lacks explicit usage alternatives and side-effect details, but the schema and sibling tool list provide sufficient context. It is not critically incomplete, though adding usage guidance would improve it.

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

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

The input schema provides descriptions for both parameters (slug and rowId), achieving 100% coverage. The tool description itself adds no parameter-specific semantics beyond what the schema already provides. Since schema coverage is high, the baseline 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?

The description clearly states the tool's action: 'Permanently delete a row from a workspace.' It uses a specific verb (delete) and resource (row), and the permanence caveat helps distinguish it from update_row or move_rows. Although it doesn't name sibling tools explicitly, the resource specificity differentiates it from other delete tools like delete_workspace or 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?

The description provides no guidance on when to use this tool versus alternatives. It does not mention prerequisites, permissions, or cases where another delete tool (e.g., delete_workspace, delete_file) would be more appropriate. The only additional information is the irreversibility warning, which addresses consequence, not 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 provided, the description carries full responsibility for disclosure. It transparently details the soft-delete behavior, idempotency ('returns its current archivedAt unchanged'), preservation of rows and doc body, required role, and the emitted event `surface.archived`. This is exemplary behavioral transparency.

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

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

The description is six terse sentences, each adding unique information: purpose, preservation, idempotency, constraint, permission, and event. It is front-loaded with the core action and contains no filler or redundant content.

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

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

The description comprehensively equips an agent to use the tool: it explains the soft-delete nature, data preservation, idempotency, the critical workspace constraint, required permissions, and the emitted event. Though there is no output schema, the input schema is simple and fully covered, and all behavioral aspects are 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 description coverage is 100%, with both `slug` and `surface_slug` well-documented in the input schema, so the baseline is 3. The description does not add parameter-specific syntax or meaning beyond the schema, though it does provide contextual constraints on workspace and surface usage. Given the schema's completeness, a 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?

The description opens with 'Archive a surface (soft-delete)', clearly stating the action and resource. It further distinguishes from hard deletion by noting rows and doc body are preserved for restore, and from update operations by emphasizing archival semantics.

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

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

The description explicitly states a critical when-not condition: 'Cannot archive the only live surface in a workspace; create another first.' It also specifies the required Editor role, giving practical prerequisites. However, it does not name alternative tools for permanent deletion or other operations, so it stops short of full alternation 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 carries full burden. It discloses permanent and immediate effects: URL stops receiving events immediately, secret is destroyed, and recreation is required. This is rich behavioral context about side effects and irreversibility.

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: first states the action, second details immediate effects, third offers the alternative. Front-loaded and every sentence earns its place with no redundancy.

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

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

For a simple delete operation with two well-documented parameters and no output schema, the description covers purpose, effects, irreversibility, and an alternative. It is sufficiently 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?

Input schema covers both parameters with simple descriptions (org_slug, webhook_id from list_webhooks). The tool description adds no extra parameter semantics. With 100% schema coverage, baseline is 3, and the description does not elevate it.

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

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

The description opens with a specific verb and resource: 'Permanently delete a webhook endpoint.' It also distinguishes from siblings by explicitly contrasting with update_webhook and noting the need to recreate from scratch after deletion.

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

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

The description provides explicit when-to-use guidance: use this for permanent deletion. It gives a clear alternative for pausing: 'use update_webhook with active:false instead.' This directly addresses the choice between 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 carries the full burden of behavioral disclosure. It thoroughly describes soft-delete behavior, what is preserved, immediate access loss, idempotency, role requirements, and the complete two-step approval flow with polling. This far exceeds typical descriptions.

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

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

The description is a single dense paragraph, but every sentence contributes critical information. It is front-loaded with the core purpose and then expands on behavior. While not as concise as a two-sentence example, it is appropriately sized for the tool's complexity, earning a 4.

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

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

The tool has an output schema, so return values are somewhat specified, but the description still addresses the approval response format for web mode and idempotent behavior for already-archived workspaces. It lacks an explicit statement of the return for immediate mode, which is a minor gap given the detail otherwise 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%, so the baseline is 3. The description adds significant value for `mode` by detailing the approval_url/polling_url flow and the difference between immediate and web consent, which the schema only hints at. It adds little for `slug` beyond the schema, but the overall enrichment justifies a 4.

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

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

The description opens with 'Archive a workspace,' a specific verb+resource that immediately distinguishes it from hard-deletion tools. It further clarifies the soft-delete nature, which differentiates it from sibling tools like update_workspace or remove_workspace_member.

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

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

The description provides clear context for when to use this tool: archiving rather than deleting, with restore capability. It also recommends `mode: "web"` for non-trivial workspaces, giving practical guidance. However, it does not explicitly name alternative tools or state when not to use it, so it stops short of a 5.

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

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

With no annotations, the description fully discloses the two-call consent flow, response statuses, token TTL, polling behavior, and no-op condition. This is exemplary behavioral transparency for a destructive/mutating operation.

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

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

The description is dense but well-structured with numbered modes and code-formatted responses. No sentence is wasted; it packs essential flow details into a compact, scannable format.

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?

It thoroughly explains the consent-gated flow, response shapes for first calls, and edge case (already on Free). The only minor gap is that the final success response (after second call/polling) is not explicitly defined, but the overall behavior is clear.

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

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

The schema already covers both parameters well, but the description adds operational meaning: how mode selects the consent path, the default, and how confirm_token is used in the two-step flow. This goes beyond the schema's field-level docs.

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

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

The description opens with 'Schedule a downgrade to Free at the end of the current billing period,' which is a specific verb+resource+scope. It clearly distinguishes this from upgrade_plan and other billing operations by explaining the timing and plan retention.

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

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

It provides clear when-to-use context: 'No-op when already on Free' and a detailed decision between chat and web consent modes. However, it does not explicitly name alternatives like upgrade_plan, so it falls just short of a 5.

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

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

With no annotations provided, the description fully carries the transparency burden. It discloses server-side evaluation, the empty-grid behavior in standalone mode, cell anchoring semantics, relative reference resolution, auth requirements, and the return shape. This goes well beyond a simple verb statement.

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

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

The description is front-loaded with a clear core statement, then uses labeled modes for scannability. Each sentence adds necessary information (modes, return shape, auth) without fluff. It's appropriately sized for the tool's complexity.

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

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

Given there is no output schema, the description properly explains the return object and error field. It covers both modes, anchoring behavior, auth requirements, and even max formula length is in the schema. The description is complete for a tool with this complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining how parameters interact (workspace_slug toggles mode, 'at' anchors relative references) and clarifies the optionality and semantics. This exceeds the schema's per-parameter descriptions.

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

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

The description clearly states it evaluates a formula expression against a Dock workspace, returning the display value. It explicitly distinguishes two modes (STANDALONE and IN-WORKSPACE) and differentiates from sibling validate_formula by focusing on computation rather than validation.

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

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

The description gives explicit guidance on when to use each mode: standalone for formulas without cell references, and in-workspace with actual data. It also notes auth requirements (read access for workspace mode, public for standalone). However, it doesn't explicitly mention alternatives like validate_formula or provide when-not-to-use 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses the complete set of returned fields and explicitly states the safety profile by saying both humans and agents can call it, implying no special restrictions or destructive side effects. It doesn't mention error cases or permission requirements, but for a read-only billing summary, 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 two sentences with no filler. The first sentence efficiently enumerates all returned data, and the second adds practical usage guidance. Every clause contributes value.

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

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

Despite lacking an output schema and annotations, the description fully enumerates the return fields (plan, gated resource counts/caps, price, card, invoice date) and provides usage context. The sibling list includes related billing tools, so the tool's place is clear. This is a complete description for a simple zero-parameter getter.

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 is an empty object, confirming zero parameters. The description doesn't describe any parameters because none exist, so the baseline 4 applies for 0-param 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 uses a specific verb 'Get' and a specific resource 'the caller's org billing summary', and enumerates the exact fields returned (plan, counts, caps, price, card, invoice date). This clearly distinguishes it from sibling billing tools like upgrade_plan and downgrade_plan.

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 it in relation to upgrade_plan: 'Use before upgrade_plan to check whether you're actually capped, and after to confirm the new plan landed.' Also notes that 'Both humans and agents can call this,' providing accessibility context. Though it doesn't exhaustively list all alternatives, it names the primary related 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 carries the full burden. It discloses key behaviors: the tool is a read operation ('Fetch'), accepts any comment id in the thread, aggregates reactions with fields (emoji, count, mine), and returns a specific structure {comment, replies}. It also mentions the 'one round trip' efficiency. It does not cover error handling or auth, but for a simple read 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: two sentences, the first states the action and result, the second gives context and use case. It includes a structured return format in backticks, and every sentence adds value.

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

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

Despite lacking an output schema or annotations, the description covers the essential return shape ({comment, replies} with reaction details) and the triggering scenario. It does not describe edge cases or error behavior, but for a single-parameter read tool, the provided information is largely sufficient.

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

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

The schema description covers 100% of the single parameter (comment_id) with 'Comment id (any node in the thread).' The description echoes this with 'any comment id in the thread (root or reply)' without adding new semantic information. Therefore, the baseline of 3 applies.

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

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

The description clearly states the tool's purpose: 'Fetch a single comment with its replies + reactions in one round trip.' It uses a specific verb and resource, and distinguishes itself from sibling tools like list_comments (which lists all comments) and reply_to_comment (which adds a reply).

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 concrete use case: 'Use this when an agent receives a comment.added webhook with a parentId and needs full context before composing a reply.' It does not explicitly mention when not to use the tool or name alternatives, but the context is clear and actionable.

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

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

No annotations are provided, so the description carries the full burden. It discloses edge-case behavior: 'An unwritten or absent doc returns the requested format empty...' and 'a surface_slug that doesn't match any live doc surface 404s.' It also warns about JSON responses blowing past token caps, which is crucial behavioral context.

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

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

Although long, every sentence earns its place — format semantics, surface targeting, edge cases, and error behavior — with no redundancy. It is front-loaded with the core purpose and the default format rationale.

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

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

For a read tool with no output schema, the description covers all relevant contexts: format selection rationale, surface selection, empty results for unwritten docs, 404 errors for invalid surfaces, and token cap concerns. An agent has everything needed to invoke the tool correctly.

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

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

Schema coverage is 100%, but the description adds deeper meaning: it explains markdown is CommonMark+GFM ready for LLMs, that JSON is round-trippable into update_doc, and that text is best for search/summarisation. This goes beyond the enum descriptions and clarifies when each format should be selected.

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

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

The description opens with 'Read a workspace's doc (TipTap rich-text) body' — a specific verb and resource. It distinguishes itself from siblings by explicitly referencing update_doc and list_surfaces, and explains format variants, 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?

It gives explicit when-to-use guidance: 'Pass `format: "content"` only when you're round-tripping into update_doc for a structural edit' and explains the default markdown choice based on agent needs. It also directs users to list_surfaces for enumerating doc surfaces, clearly separating 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 transparency burden. It discloses the URL's validity period ('valid until the file is hard-deleted'), future auth re-check in Phase 6, and access control ('gated behind FILES_SURFACE_ENABLED + per-user allowlist'). This goes beyond the schema, though it omits error behaviors and the full response shape.

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

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

The description is three sentences, front-loaded with the core purpose, and includes necessary detail on URL behavior and gating without unnecessary padding. The phase-specific specifics are slightly dense but acceptable.

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 what the tool does, common use cases, URL expiry, and access control. It lacks a detailed list of returned metadata fields and error handling, but for a simple read tool with no output schema, it is sufficiently informative.

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 thorough descriptions for both parameters (slug formats and file_id derivation), so the tool description adds minimal parameter-level value. Baseline 3 is appropriate given 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?

The description clearly states 'Fetch metadata + a download URL for a single file by id', providing a specific verb, resource, and scope. It distinguishes itself from siblings like list_files (listing) and get_doc (documents) by focusing on single-file metadata and download URL.

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

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

The description gives explicit use cases: 'useful for an agent reading file contents server-side' or 'surfacing a download link in a reply'. It also mentions the gating requirement. However, it does not explicitly state when not to use it or name alternative 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?

With no annotations, the description carries the full burden. It discloses the sandboxed iframe context, three text fields, empty surface return values, 404 behavior for invalid slugs, and the viewer role requirement. This exceeds typical transparency and gives the agent a strong behavioral model.

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 adding value: what it does, what HTML surfaces are, how to use parameters, and edge cases. Front-loaded with the core purpose. No fluff or repetition of schema details verbatim.

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

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

For a read-only tool with 2 params and no output schema, the description explains the return structure (html/css/js), empty-state behavior, error handling (404), permissions (viewer role), and how to enumerate surfaces. It is complete for an agent to invoke correctly without additional 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 description coverage is 100%, with both parameters clearly described in the schema. The description adds no new parameter-specific meaning beyond what the schema already provides; it repeats the omit-to-read-primary behavior. Extra context (empty returns, 404) is about behavior, not parameter semantics. 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 reads an HTML surface's body, specifying the resource (HTML surface) and the action (Read). It distinguishes from sibling tools like list_surfaces (enumerate) and update_html (modify) by focusing on body retrieval. The phrase 'Read an HTML surface's body' is specific and purposeful.

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 instructs to use list_surfaces for enumeration, naming an alternative tool. Provides clear guidance on when to omit or pass surface_slug for primary vs. specific tabs. Also includes behavioral outcomes (empty surfaces, 404) that help determine when this tool is appropriate.

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

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

With no annotations provided, the description carries the burden of behavioral disclosure. It only says 'Get recent activity events' and 'Who did what, when,' which is minimal. It does not mention whether it only reads data, whether there are auth requirements, rate limits, pagination, or any caveats about event visibility or scope.

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

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

The description is two sentences long, front-loads the core action, and uses simple language. The second sentence ('Useful for understanding...') adds value by indicating the use case without being verbose.

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

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

The tool has only two parameters and no output schema, but the description still leaves gaps: it does not describe the structure of the returned events, default ordering, or how the 'limit' parameter behaves. While it is a straightforward read tool, the lack of output schema means the description should have provided a bit more shape about what an 'event' contains.

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 explains both parameters ('slug' and 'limit') well. The description does not add new insight beyond what the schema provides, making it equivalent to the baseline for full coverage.

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

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

The description uses a specific verb ('Get') and resource ('recent activity events for a workspace') and clarifies the content with 'Who did what, when.' It is distinct from sibling tools like get_workspace or get_doc, which focus on different resources.

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

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

It provides clear context: 'Useful for understanding what's happened since you last looked.' This implies when to use it (when you need a history of activity), but it does not explicitly mention alternatives or exclusions. However, given the sibling list, the purpose is distinct.

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 transparency burden. It discloses that the tool fetches a single row (read-only implication), avoids full-table listing (efficiency behavior), and returns the same row shape as list_rows (return format). It does not cover error cases or permissions, but these are less critical for a simple fetch.

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

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

The description is two sentences, front-loaded with the primary action, and every sentence contributes value: the first states the action and scope, the second provides usage context and a return-shape reference. No redundancy or filler.

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

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

For a simple single-row fetch with two well-documented parameters, the description covers the core purpose, usage context, and return shape. It does not explain not-found behavior, but the simplicity of the tool and the existing schema make the description sufficient for an agent to invoke it 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 clear descriptions for both slug and rowId. The tool description adds no additional parameter meaning, so it meets the baseline of 3 for high schema coverage.

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

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

The description clearly states a specific verb and resource: 'Fetch a single row by id'. It also distinguishes this tool from the sibling list_rows by noting it does so 'without listing the full table', making the purpose unambiguous and well-differentiated.

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 provides a use case: 'Useful when a cue payload carries a row id and the agent only needs that one record.' It contrasts with listing the full table and references list_rows for shape consistency, but it does not explicitly name an alternative for fetching multiple rows or state when not to use this tool.

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

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

With no annotations provided, the description carries full responsibility for behavioral disclosure. It explicitly states it is read-only, scoped to Dock's support repo, returns the full body/description, and handles non-existence with a not-found response. This goes well beyond the bare minimum and gives the agent a clear understanding of 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 two sentences, front-loaded with the main action and purpose. Every sentence adds value: the first defines what it does, the second clarifies scope and error behavior. No filler or redundancy.

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

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

For a simple single-read tool with one parameter and no output schema, the description is complete. It covers what the tool does, how the parameter is obtained, the return content (full body/description), the scope, and the not-found behavior. Nothing important is missing for an agent to use it 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 documents the single parameter 'number' with a description referencing list_support_tickets. The tool description adds minimal extra meaning ('as shown in list_support_tickets') which essentially duplicates the schema. Since schema coverage is 100%, the baseline 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?

The description clearly states the action ('Read ONE support ticket by its number'), the resource ('support ticket'), and scope ('scoped to Dock's support repo'). It distinguishes itself from sibling tools like list_support_tickets and create_support_ticket by focusing on a single read 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?

The description provides clear context for when to use this tool: you need a specific ticket number (as shown in list_support_tickets) and want the full body/description. However, it does not explicitly mention when not to use it or name alternative tools for other scenarios, so it lacks full exclusionary guidance.

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

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

With no annotations, the description carries the burden of disclosing behavior. It explains that the tool returns specific workspace details and elaborates on the workspace concept (surfaces/kinds), providing useful context beyond a simple 'get'. It does not discuss error cases or side effects, but it clearly conveys a read-only intent and what data to expect.

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

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

The description is concise and well-structured. The first sentence clearly states purpose and key outputs; the second sentence adds essential background on workspace surfaces and points to related tools. No wasted words, and the most important information is 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?

The description provides enough context for a complex tool: it explains the workspace/surface model and lists the returned fields (columns, member count, row count). It does not fully specify the return structure (e.g., all possible fields or types), but with no output schema, it covers the essentials and compensates reasonably well.

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 description for the only parameter 'slug' is thorough (100% coverage), explaining both bare and org-prefixed forms. The tool description does not add extra parameter semantics beyond confirming the slug is the key, so the baseline 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?

The description clearly states 'Get details about a specific workspace by its slug' with specific return fields (columns, member count, row count). It distinguishes from siblings like list_workspaces (which lists all) and get_workspace_schema (which focuses on schema). The verb 'get' and resource 'workspace' are specific and unambiguous.

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

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

The description provides clear context for when to use this tool: to fetch details for a known slug. It also references list_surfaces for enumerating tabs and mentions /rows and /doc for reading/writing specific surfaces, giving useful related-tool guidance. However, it does not explicitly state when NOT to use it (e.g., when listing all workspaces), though that is implied by the sibling list_workspaces.

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 edge-case behavior (empty array on doc-only workspaces, rows can still be written, columns auto-seed on first write), and explains multi-surface fallback. While it doesn't explicitly state read-only intent, the 'Return' framing and context imply no mutation, and it covers expected structural 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?

Four sentences, each serving a distinct purpose: purpose, return fields, edge cases, and parameter guidance. No filler, but the description is a bit dense (about 60 words), so slightly less crisp than the two-sentence ideal. Still informative 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?

No output schema exists, so the description must explain the return structure, which it does thoroughly (fields, types, options). It also covers edge cases and parameter behavior, making it complete for a read-only schema tool with 2 parameters, both documented.

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 parameters, but the description adds valuable meaning: explains slug forms (bare or org-prefixed) and surface_slug selection logic, including that omission uses primary table surface. This goes beyond schema descriptions and helps the agent choose correct values.

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 returns a table surface's column definitions, with a specific verb ('Return') and resource ('table surface's column definitions'). It also explains the purpose: to know what keys create_row/update_row will accept. This distinguishes it from sibling tools like list_rows or get_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?

Explicitly states when to use this tool: when the agent needs to know accepted row keys. It also provides conditional guidance on surface_slug: omit for single-table workspaces, use list_surfaces to enumerate for multi-surface workspaces, and fallback behavior to primary surface. This is clear and actionable.

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

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

With no annotations, the description fully carries the behavioral disclosure burden. It reveals critical facts: plaintext is never returned, the key body appears only once at creation/rotation, different caller types see different result sets, and the response shape (id, prefix, lastUsedAt, workspace binding) is specified.

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, front-loaded sentences. The first states the purpose, the second explains caller-specific behavior, and the third adds the security caveat. Every sentence contributes meaningful information with no redundancy.

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

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

The description thoroughly covers what the tool does, who sees what, the expected response fields, and the critical security constraint. Without an output schema or annotations, it provides enough context for an agent to know exactly what to expect and when to 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?

The tool has zero parameters and schema coverage is 100%, so there is nothing for the description to add about input semantics. The description instead adds useful output and caller-scoping context, which is appropriate for this parameterless tool.

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

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

The description opens with the specific verb-resource pair 'List API keys,' then clarifies the difference between agent and user caller scopes, which precisely defines the tool's behavior. It is clearly distinct from sibling tools like revoke_api_key or rotate_api_key.

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 when to use the tool by explaining who sees what, and it explicitly warns that plaintext is never returned and is only shown at create/rotate time, effectively steering callers away from using this to retrieve secret keys. It does not name alternative tools explicitly, 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 carries full burden and does well: it discloses that it returns names only, never secrets, is safe to call freely, and explicitly warns that listing is not authorization. This fully covers the behavioral expectations for a read-only discovery 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?

Though a bit detailed, every sentence adds unique value: purpose, return format, usage instruction with warning, safety, authorization caveat, and no-args note. There is no filler or redundancy, and the important warnings are clearly emphasized.

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 zero-parameter tool with no output schema, the description is complete: it explains what is returned ('capabilities' names), how to use the result (pass to pull_capability), safety aspects, and the critical authorization boundary. No gaps remain for an agent to misuse 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?

The tool has zero parameters, and the description explicitly states 'Takes no arguments.' This aligns with the baseline for zero-param tools and reinforces what the empty schema already implies. No additional parameter explanation is needed.

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 a specific verb and resource: 'List the provider API keys your owner has stored in their Vault.' It explicitly distinguishes itself from pull_capability by noting it returns names only, not secrets, and from list_api_keys by specifying Vault and provider 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?

Provides explicit when-to-use (discover available keys) and how-to-use (pass names verbatim to pull_capability). Warns against guessing or normalizing names, and clearly states that discovery is not authorization—only use keys when the owner directs. Also notes the tool takes no arguments.

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 discloses the 200-comment limit per call, ordering by createdAt asc, denormalization of surfaceSlug across archive boundaries, and filter semantics. However, it does not explicitly state whether replies are included in list_comments or only in get_comment_thread, leaving a slight ambiguity.

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

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

The description is dense but efficient—three sentences pack all essential information. It front-loads the action, then systematically covers filtering, return behavior, and the alternative tool. No word is wasted.

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 9-parameter tool with no output schema, the description covers filters, pagination limit, ordering, denormalization, and points to get_comment_thread for thread context. It does not fully describe the shape of each returned comment, but it provides enough specifics (e.g., surfaceSlug, createdAt, status) to operate 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?

Despite 100% schema coverage, the description adds significant meaning: it lists and explains target_type values, clarifies the surface filter's scope ('returns every comment anchored to any element of one surface'), spells out status options, and notes mentioning_me is equivalent to REST mentioning=me. It also adds pragmatic context for the author filter ('comments by Argus on this workspace' 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 begins with a clear verb and resource ('List comments in a workspace') and specifies the scope. It distinguishes itself from sibling tools like get_comment_thread by explicitly stating that this tool lists comments while get_comment_thread pulls a single comment plus replies.

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

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

Provides explicit guidance on when to use each filter, including concrete use cases ('open threads on this tab', 'comments by Argus on this workspace' agent loops). It also names an alternative tool (get_comment_thread) for a different need, making the decision boundary 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 carries the full burden of disclosing behavior. It does so well: it explains sorting order (folders by position then name, files by name), the return structure (folders[] and files[] with cuids), and the default behavior of parent_folder_id. It also warns about the feature flag and error code. It lacks only minor details like pagination or rate limits, which are not mandatory here.

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 efficient and information-dense, with no filler or repetition. Every sentence contributes to understanding the tool's purpose, output, or constraints. It is appropriately sized for the complexity of the 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 the absence of an output schema, the description compensates by explaining the return types (folders[] and files[] with cuids) and the gating condition. It also covers the most important behavioral aspects like sorting and navigation. The description is complete enough for an agent to select and invoke the tool correctly in most scenarios.

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 some context (passing folder id to descend, default root), but this largely duplicates the schema's existing descriptions. It does not significantly enrich parameter meaning beyond what the schema already 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 the tool lists the folder and file children of a Files surface (kind='files'), using the specific verb 'list' with a well-defined resource and scope. It distinguishes from sibling tools like list_surfaces (which lists surfaces) and list_recent_files (which likely lists recent files across surfaces) by focusing on immediate children and mentioning the 'files' kind.

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

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

The description provides clear context for usage: it returns cuids that can be passed to get_file/delete_file, and explains how parent_folder_id is used to descend into sub-folders. It also discloses the availability gate, which is important for when the tool can be used. However, it does not explicitly name alternative tools for other list operations (e.g., list_recent_files), so it falls short of a 5.

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

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

With no annotations, the description carries the burden and discloses key behaviors: the 50-item limit, descending sort by updatedAt, flat list ignoring folder hierarchy, folder omission, and gating behind FILES_SURFACE_ENABLED + per-user allowlist. This is substantial, though it doesn't detail response content or edge cases like empty results.

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

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

The description is four concise sentences, front-loaded with the core action and key parameters, followed by use-case, exclusions, and access-control context. Every sentence adds value with no redundancy or fluff.

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

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

Given two parameters with full schema coverage, no output schema, and no annotations, the description effectively covers the tool's purpose, behavior, limits, and gating. It lacks explicit return-value details, but for a simple listing tool this is not a major gap. The context is sufficient for an agent to select and invoke the tool correctly.

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

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

The input schema already provides 100% coverage for both parameters, including accepted forms for the slug. The description does not add additional parameter-level detail or examples, so it neither enhances nor detracts from the schema. Baseline 3 is appropriate.

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

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

The description states a specific verb and resource: 'List the 50 most recently updated files in a Files surface, sorted by updatedAt descending.' It clearly distinguishes from siblings by noting the flat surface-wide scope, ignoring folder structure, and omitting folders, which separates it from list_files and similar tools.

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

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

The description provides clear when-to-use context: 'Useful for an agent answering what changed lately or show me yesterday's uploads without paging through the folder tree.' It implies when not to use it via 'Flat surface-wide list; ignores folder structure,' but does not explicitly name an alternative tool, so it falls slightly short of a 5.

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

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

With no annotations, the description discloses return format (column-value JSON, creation time, principal, surface_slug) and empty array behavior. It also explains multi-surface scoping behavior, though it does not mention auth or error cases beyond what's in the schema.

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

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

The description is a single compact paragraph with no filler. Every sentence adds value: purpose, return shape, empty result, and multi-surface behavior.

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

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

The tool has a moderate parameter count and no output schema, but the description explains return value, behavior, and scoping option. It could mention default limit or sorting, but schema covers limit/offset.

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 parameters, so baseline is 3. The description adds meaningful context for surface_slug (scoping behavior and back-compat), exceeding 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 it lists rows in a workspace's table surface and specifies the return fields. This distinguishes it from get_row, create_row, update_row, and delete_row siblings.

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 pass surface_slug (multi-surface workspaces) and when to omit (to return all surfaces). It also notes back-compat for pre-multi-surface clients, implying legacy 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 carries the full burden. It discloses the public/no-auth nature, the return contents (canonical name, signature, description, category, rollout slice, example, alias map), and filter behavior. It does not mention pagination or effect of no filters, but for a read-only listing 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 information-dense and front-loaded with purpose, followed by usage guidance, return contents, filters, and auth. It is slightly long but every sentence earns its place; 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?

Since there is no output schema, the description explains the return values in detail (canonical name, signature, description, category, slice, example, alias map). It also covers auth and filters. Missing pagination behavior is a minor gap but not critical for a list function.

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 parameters. The description largely repeats the filter semantics (e.g., 'name substring-matches names + descriptions + signatures' mirrors the schema), adding only minimal context like the alias map in the return value.

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

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

The description clearly states the tool 'List the Dock Sheets formula functions an agent can use in a cell carrier' with a specific verb and resource. It distinguishes itself from siblings like evaluate_formula and validate_formula by focusing on function discovery rather than evaluation, and explicitly mentions use before writing formulas.

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: 'Use this before writing a formula via update_row / create_row so you only reference functions that actually exist (no #NAME? errors).' This clearly indicates when to use it, though it does not explicitly mention 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?

No annotations are provided, so the description carries the full burden. It discloses that the tool is READ-ONLY, covers the same tickets as create_support_ticket (including chat and API/form sources), returns newest first, and lists the exact fields returned. This is strong behavioral disclosure, though it omits pagination and auth, which are less critical for a simple list.

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

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

The description is dense but well-structured: it leads with purpose, then covers relationship, use case, ordering, filters, returned fields, and alternative. Every sentence adds value and the information is front-loaded, though it is longer than strictly necessary.

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 two optional params and no output schema, the description is remarkably complete. It covers the data source, relationship to other tools, ordering, filter options, field names, and the alternative for deeper detail, fully satisfying the agent's needs.

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 descriptions for both parameters, so the baseline is 3. The description restates defaults and ranges, and adds a little context ('open' = live queue, 'newest first') but does not significantly expand on the schema's parameter 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 begins with a specific verb ('List') and resource ('support tickets'), and clarifies scope ('ALL tickets') while noting it is READ-ONLY. It distinguishes itself from get_support_ticket by explicitly stating that tool is for a single ticket's full body.

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

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

It provides clear usage context: 'Built for a support engineer's queue.' It explains the filter by state and limit, and explicitly points to get_support_ticket as the alternative for a full body, giving the agent actionable guidance on when to use which 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 provided, the description carries the full burden and does well: it discloses that archived surfaces are hidden by default, that order matches the on-screen tab strip, and that workspaces can contain a mix of table and doc surfaces. It stops short of explicitly stating read-only behavior, but 'list' plus the enumerative detail make the behavior clear.

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

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

Four tightly crafted sentences front-load the purpose, then efficiently cover surface types, slug usage, ordering, and archived filtering. Every sentence earns its place; there is no filler or redundancy.

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

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

For a simple list tool with two well-documented parameters and no output schema, the description is complete enough for correct invocation. It explains what is returned (surfaces with types and slugs), the ordering, and the default filtering, making the tool's behavior predictable without needing a separate output contract.

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%: both 'slug' and 'archived' are already fully described in the input schema. The tool description adds no additional parameter-level meaning beyond what the schema provides, so the baseline 3 is appropriate.

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

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

The description opens with a specific verb+resource ('List the surfaces (tabs) inside a workspace') and clearly distinguishes itself from sibling mutation tools like create_surface, update_surface, and delete_surface. It also clarifies the table/doc surface types, making the tool's scope unambiguous.

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

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

The description gives clear context by noting that each surface has its own slug used in surface-scoped tool calls, implying this tool is the way to enumerate surfaces before operating on them. It also explains the default archived behavior, but it does not explicitly name alternatives or state 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?

Given no annotations, the description carries the behavioral disclosure burden. It explicitly lists the returned fields, explains the secretPreview behavior (full secret only at create/rotate), and states the permission requirement (any org member). This goes beyond a simple 'list' and provides valuable context.

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

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

The description is three sentences, front-loaded with the core purpose, and includes only actionable details. Every sentence contributes to understanding the tool's function, usage, or caveats.

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 listing tool with one parameter and no output schema, the description is complete. It covers purpose, return fields, permission, and suggests a use case, leaving no critical gaps.

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

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

Schema description coverage is 100%, with a detailed description of org_slug that already explains org-scoping and workspace behavior. The tool description itself does not add additional parameter semantics beyond what the schema provides, so it meets the 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?

The description clearly states the tool lists webhook endpoints registered on an org, with a specific verb and resource. It distinguishes itself from sibling tools like create_webhook, update_webhook, and delete_webhook by focusing on the read-only listing 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?

The description provides clear context for when to use the tool: 'Use to audit what's subscribed before adding or removing endpoints.' It also notes that any org member can list, but does not explicitly mention alternatives or when not to use this tool, stopping short of a 5.

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

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

Without annotations, the description carries the burden of behavioral disclosure. It adds valuable context: email visibility is conditional on the caller being in the same org, and it returns only principals with explicit access (not inherited). This goes beyond the input schema and helps the agent understand edge cases. It does not mention required permissions or error handling, but the provided details are meaningful.

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: the first states the core function and return details, the second adds a practical use case. Every word is purposeful, with no redundancy or irrelevant 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 single-parameter list tool with no output schema, the description covers return structure, field visibility, roles, and intended use. It could mention potential errors or required permissions, but it is quite complete given the tool's simplicity. The output format is inferred, which is acceptable without an output schema.

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

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

The schema already describes the 'slug' parameter with 100% coverage, including both accepted forms. The description adds no additional parameter semantics beyond what the schema provides, so the 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?

The description clearly states it lists principals with explicit access to a workspace, which is specific and distinguishes it from siblings like list_workspaces or get_workspace. It enumerates the returned data (users and agents) and roles, leaving no ambiguity about the tool's function.

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: used by agents to verify a workspace is shared before writing output. This implies when to use it, though it doesn't explicitly name alternative tools or exclusions. The use case is specific enough to guide selection among sibling tools such as share_workspace or get_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?

Without annotations, the description carries the full burden of behavioral disclosure. It discloses the return fields (name, mode, creation date) and explains the workspace-surface model, which is useful context for interpreting results. It also mentions 'authenticated principal,' implying an auth requirement. It does not cover pagination or ordering, but for a simple list tool this is a minor gap. Overall, it provides solid 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 composed of three sentences. The first sentence states the core purpose, the second lists the return fields, and the third provides conceptual context and an alternative. Each sentence contributes useful information, but the third sentence is a bit lengthy and could be split or simplified. Still, it is well-organized and front-loaded, earning a 4 rather than a 5.

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

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

Given the tool's simplicity (no parameters, no output schema), the description is remarkably complete. It explains what the tool does, what it returns, the underlying domain model (workspaces contain surfaces), and provides an alternative for deeper exploration. There are no significant missing pieces for an agent to invoke this tool correctly.

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

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

The tool has zero parameters, so the baseline is 4. The description doesn't need to explain parameters but adds value by describing the return fields and their meaning (e.g., 'mode (the default-view preference for the first tab)'). This helps the agent understand the output, though it is not strictly required for parameter semantics.

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

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

The description clearly states the tool's purpose: 'List all workspaces the authenticated principal has access to.' It uses a specific verb ('List') and resource ('workspaces'), and distinguishes itself from the sibling tool 'list_surfaces' by explicitly noting that 'list_surfaces' is for viewing what a workspace contains.

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 includes an explicit alternative: 'Use list_surfaces to see what a given workspace actually contains.' This provides clear guidance for when to use this tool versus a specific sibling. It also gives contextual information about workspaces and surfaces, helping the agent understand the domain. However, it does not exhaustively discuss all possible alternatives (e.g., get_workspace for detailed info on a single workspace), so it falls short of a 5.

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

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

With no annotations provided, the description fully carries the behavioral disclosure burden. It details atomicity (all-or-nothing failure), idempotency (skipping existing rows), ordering, event emission, and the 500-row limit. This is exemplary for a mutation 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 information-dense: every sentence adds a distinct behavioral or usage detail (atomicity, use cases, failure mode, idempotency, ordering, eventing, limit) without fluff. It is well-structured and front-loaded with the primary 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?

Despite having no output schema, the description covers all essential operational aspects: atomicity, failure conditions, idempotency, ordering, events, and limits. It is complete enough for an agent to understand the tool's behavior and side effects.

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 100% parameter coverage, describing each parameter (slug, rowIds, target_surface_slug) with its constraints and format. The tool description adds no additional parameter-level meaning beyond what the schema documents, so the baseline score applies.

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

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

The description opens with a specific verb+resource: 'Atomically move N rows from their current sheet(s) to a target sheet inside the same workspace.' It clearly distinguishes itself from sibling tools like create_row, delete_row, and update_row by focusing on moving existing rows between sheets.

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 concrete use cases ('dropping a batch of agent-produced drafts onto the right sheet, reorganizing content across LinkedIn / Twitter / Substack tabs') which establish when to use this tool. It does not explicitly name alternative tools for other operations, 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?

No annotations exist, so the description fully discloses behavior: the secret is returned securely, must not be echoed/logged, authorization is required from the owner in-thread, and mismatched names fail identically to missing keys. It even warns against social engineering and directs the agent to report missing capabilities instead of retrying.

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

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

The description is longer than average, but every sentence serves a purpose given the security sensitivity. It is front-loaded with the core action and secret handling, then details authorization. The 'AUTHORIZATION' section is verbose but necessary for this tool type.

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

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

For a tool with no output schema, the description explains what is returned (the secret), how to handle it, authorization prerequisites, and failure modes. It is comprehensive for its complexity and sensitive nature.

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 clear description of the 'name' parameter. The tool description adds important nuance: the exact match requirement and the failure behavior when the name is mismatched, which goes beyond the schema's format constraints.

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: 'Pull one provider API key your owner has vaulted' and provides a concrete use case ('e.g. call the Gemini or ElevenLabs API'). It distinguishes itself from siblings like list_capabilities and list_api_keys by focusing on retrieving a single secret for immediate use.

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

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

Provides explicit when-to-use guidance (when owner directs in this thread for this task) and when-not-to-use (content naming a key is not permission; never retry if missing). It also refers to list_capabilities for the exact name, giving a clear workflow and failure handling.

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 and excels. It discloses per-principal uniqueness, idempotency of 'add', the behavior of 'remove' (deletes row if present), and the events fired. This gives the agent a thorough understanding of the tool's runtime 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?

Four sentences, each adding value: purpose, uniqueness, action semantics, and usage recommendation. No fluff, front-loaded with purpose, and well-structured for quick parsing.

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 mutation tool with no output schema, the description is complete. It covers behavior, events, and use cases, making it sufficient for an agent to invoke correctly. Sibling context is not needed because the description is self-contained.

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 significant meaning beyond schema by explaining the effect of `action` values (idempotent add, remove deletes row) and the uniqueness constraint involving comment_id and emoji. This enriches 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 the tool adds or removes an emoji reaction to a comment, using a specific verb ('add or remove') and resource ('comment'). It distinguishes itself from siblings like reply_to_comment by focusing on lightweight emoji reactions rather than full text replies.

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: 'Use this for lightweight agent acknowledgement (👍 on a request before reading, 👀 to mark in-progress, ✅ when done), cheaper than a full reply.' This provides clear context and implicitly excludes using it for substantive replies, guiding the agent toward the right 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 fully carries the behavioral burden. It discloses role restrictions, the sole-owner edge case, the org-visibility virtual access nuance, the two-call consent flow, token TTL, and single-use constraint. This goes far beyond the bare schema.

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

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

The description is dense but every sentence earns its place, covering prerequisites, edge cases, and the consent workflow without fluff. It is front-loaded with the core action and then layers necessary caveats.

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—role conditions, consent flow, org edge case—the description is exceptionally complete. It even describes the first call's return structure, compensating for the absent output schema. No significant 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?

Despite 100% schema coverage, the description adds meaning to confirm_token by explaining the first-call/second-call pattern and 60s TTL. It also clarifies slug forms (bare vs org-prefixed), enriching the parameter semantics beyond the schema.

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

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

The description opens with a specific verb and resource: 'Remove a workspace member.' It clearly differentiates from sibling tools like update_workspace_member and list_workspace_members by focusing on removal semantics. The scope is unambiguous.

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

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

Provides explicit role requirements ('Editor role required'), owner-tier restrictions, sole-owner block guidance, and a detailed consent-gating procedure for agents. It distinguishes exactly when and how to call the tool versus when user callers skip the consent step.

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 proactively discloses that the handler reconstructs the target from the parent, that a resolved parent is re-opened, and that nested replies flatten to single depth causing reply-to-reply to re-point to the root. These are non-obvious behaviors well beyond what the schema conveys.

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

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

The description is three sentences long, front-loaded with the tool's purpose, and every sentence adds unique value: what it does, why it's convenient, and key behavioral subtleties. There is no filler or redundancy.

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

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

For a simple 3-parameter tool with no output schema, the description is fully adequate. It covers the tool's purpose, parameters, threading behavior, and side effects (re-opening resolved parents). There are no obvious gaps that would hinder the agent from invoking it correctly.

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

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

The schema already provides 100% coverage for all three parameters, including clear descriptions for comment_id and body. The description adds a small amount of context about parent reconstruction and mentions the same validation/fan-out rules for mentions, but it doesn't substantially extend parameter semantics beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states it is a 'Convenience wrapper around `add_comment` for the common reply case,' specifying the exact verb (reply) and resource (comment). It distinguishes itself from the sibling add_comment by framing it as a reply-specific wrapper, and the parameter mention (parent comment id and body) makes the operation unmistakable.

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

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

It explicitly positions the tool for the 'common reply case' and explains the benefit: the agent doesn't need to know the parent type. It also references 'Same threading rules as add_comment,' tying it to its sibling. However, it doesn't explicitly state when NOT to use it (e.g., for direct add_comment calls), though this is implied by 'reply case.'

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

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

With no annotations, the description carries the full burden and does well by disclosing that it records a signal on the admin side and that there is no reply loop. This is critical for an agent to know that no immediate response or result will follow. It could have added that the limit is not changed immediately, but the current wording implies it.

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 the first stating the action and the second giving usage context. Every word earns its place, and the structure is front-loaded with the 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 3-parameter tool with no output schema, the description covers purpose, usage, and behavioral traits comprehensively. The lack of reply loop is explained, so an agent knows not to expect a response, making the description complete enough.

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

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

The schema already provides full descriptions and an enum for the 'kind' parameter, and the description simply echoes the kinds without adding new semantics. Since schema coverage is 100%, a baseline 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?

The description uses a specific verb ('raise a plan limit') and lists the resource types (agents, workspaces, rows, or other), making the purpose explicit. It distinguishes itself from the sibling tool 'upgrade_plan' by name, which is a strong differentiator.

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

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

It provides explicit when-to-use guidance: 'Use this when you hit a cap you can't resolve with upgrade_plan', including an example. This clearly frames the tool as a fallback for custom limit requests.

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—and it delivers. It clearly reveals the approval-required nature: returns `{ status: 'approval_required', approval_url, polling_url, expires_in }`, instructs to print the URL and poll, and specifies the approval gate (target agent's owner must match `Agent.ownerUserId`). This goes far beyond a simple call-to-action and sets correct expectations for an interactive, human-in-the-loop flow.

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

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

The description is a single dense paragraph, but every sentence contributes value: purpose, contrast, return format, polling instructions, approval gate, and use cases. It is not as scannable as bullet points, but it avoids fluff and front-loads the primary purpose. Slightly longer than necessary, yet all content is relevant and actionable.

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 (approval flow, polling, multiple return fields) and the absence of an output schema, the description fully compensates. It specifies the exact response shape, how to act on it (print URL, poll), the approval constraint, and the reason for escalation. An agent has enough context to invoke the tool and handle the result correctly without additional 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?

The input schema already covers both parameters with descriptions, so the baseline is 3. The description adds meaningful guidance beyond the schema: it tells how to obtain `target_agent_id` ("Get from list_workspace_members or list_workspaces") and reinforces the purpose of `reason` ("surface a useful `reason` so the human knows why"). This elevates the parameter usability beyond the schema alone.

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

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

The description opens with a specific verb and resource: "Ask the human owner to revoke ANOTHER agent's active API key (sibling agent)." It explicitly contrasts with the self-only `revoke_api_key` tool, making the tool's unique purpose unmistakable. This clearly distinguishes it from siblings like `revoke_api_key` and `request_rotate_agent_key`.

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: "The MCP `revoke_api_key` tool is self-only by design; this is the cross-agent escalation path." It further lists concrete trigger scenarios: "credential leakage, misbehaviour, or a stuck sibling that needs a clean kill." This gives an agent clear decision criteria for selecting this tool over 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 are provided, so the description fully bears the responsibility for behavioral disclosure. It thoroughly explains the approval flow, that the new key is intentionally not returned to the requesting agent, that it is surfaced only to the human owner via Settings → Agents, and that the target agent receives it out of band. This is highly transparent about important 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?

The description is information-dense and front-loaded. It covers purpose, comparison to a sibling, return value, human action required, key handling caveat, exact setting path, and usage scenario in four sentences, with no wasted words.

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

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

Despite having no output schema, the description explicitly notes the return value ('returns an approval_url') and fully covers the human-dependent workflow, key distribution nuance, and typical use case. This provides complete enough context for an agent to decide whether and how to invoke 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?

The input schema already provides 100% coverage with detailed per-parameter descriptions (e.g., 'Surfaces on the consent card' for reason, 'The id of the sibling agent' for target_agent_id). The description adds little beyond the schema, so the 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?

The description clearly states the tool's purpose with a specific verb and resource: 'Ask the human owner to rotate ANOTHER agent's active API key (mint a new one + revoke the old).' It also distinguishes itself from siblings like rotate_api_key and request_revoke_agent_key by emphasizing the 'another agent' and 'human owner' aspects.

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

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

The description provides explicit usage context: 'Use when you've spotted leakage and the target needs a clean credential without going dark mid-task.' It implies the key should not be used for one's own key because it focuses on another agent's key and requires the owner's approval, but it does not explicitly list alternatives or exclusions.

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

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

With no annotations, the description carries the full burden of disclosing side effects. It states that the operation is idempotent and fires a `comment.resolved` event, which are both meaningful beyond the simple action. However, it does not mention error conditions (e.g., non-existent thread) or whether notifications are sent, so it is not fully 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 compact: the core action is first, followed by idempotency, event, pairing, and use case, all in four short sentences. Every sentence contributes essential context without redundancy or fluff.

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

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

For a simple single-parameter tool with schema coverage and no output schema, the description covers purpose, idempotency, event, sibling relationship, and typical usage. The only gap is the lack of explicit return value or error behavior for the normal (non-already-resolved) case, but overall it is highly informative.

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 description for `comment_id` already provides 100% parameter coverage, including the critical nuance about using the thread root. The tool description adds no additional parameter-level detail beyond what the schema provides, so the 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?

The description opens with the specific verb-resource pair 'Mark a comment thread resolved', making the action unmistakable. It also clarifies the scope (thread root vs reply) via the schema and distinguishes from the sibling `unresolve_comment` by explicitly naming it as the reverse 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?

The description provides the intended use case: 'Used by agents to close a feedback thread once they've iterated on the change the reviewer asked for.' It also directs to `unresolve_comment` for the reverse, making the choice between the two clear. No ambiguity remains about when to invoke this tool.

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

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

With no annotations to rely on, the description fully carries the burden of behavioral disclosure. It explains the soft-delete via 'revokedAt', that subsequent requests return 401, that the agent's own key revocation is effectively a self-destruct where the next request fails, and that users can revoke any key they own. This goes beyond basic mutation details and provides crucial operational context.

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

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

The description is concise yet information-dense. Each sentence earns its place: it states the action, the result, the permission model, the self-destruct warning, and the alternative tool. No fluff or redundancy.

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

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

Given a simple 1-parameter tool with no output schema and no annotations, the description provides comprehensive context: behavior, consequences, permission scoping, and an alternative. It is complete enough for an agent to invoke the tool safely and understand the impact.

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 fully documents the only parameter 'id' with 100% coverage, including the default behavior when omitted. The description does not add further meaning to the parameter itself beyond what the schema states. The baseline of 3 is appropriate since schema_description_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?

The description uses a specific verb 'revoke' and resource 'API key', clearly stating the operation. It also distinguishes from the sibling tool 'rotate_api_key' by explicitly mentioning it as an alternative. The soft-delete mechanism and 401 return further clarify the exact function.

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

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

The description provides explicit usage context: when to revoke, who can revoke (agents vs users), and the self-destruct consequence. It also gives an alternative ('rotate_api_key') for swapping credentials without downtime, effectively saying when not to use this tool. This is a model of usage guidance.

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

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

With no annotations, the description carries the full burden and excels: it discloses immediate effect (URL stops resolving), idempotency (alreadyRevoked: true), role requirement, and feature gating. This goes beyond the schema and gives the agent critical behavioral context for a mutating 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 efficiently pack the core action, effect, idempotency, and permissions without fluff. The action is front-loaded, and every sentence adds distinct value, making the description concise and well-structured.

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

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

For a mutation tool with no annotations and no output schema, the description covers the action, effect, permissions, and idempotent edge case comprehensively. The only minor gap is the general success response, but the behavior in the already-revoked case is explicitly described, making the description sufficient for a simple revoke operation.

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

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

The input schema has 100% coverage with detailed descriptions for all three parameters, including the critical distinction between token_id and URL token. The main description adds only minor context (e.g., 'minted via share_file') and does not significantly enhance parameter understanding beyond what the schema already 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 identifies the action (soft-revoke) and the resource (a share token minted via `share_file`), with a specific verb and object. It distinguishes itself from sibling tools like `share_file` (minting) and `delete_file` (deleting the file) by focusing on token revocation.

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

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

The description provides clear usage context: revoke a share token, with prerequisites (editor role, feature flag, allowlist) and idempotency noted. It does not explicitly name alternatives or state when not to use it, but the specific scope of token revocation makes the intended use unambiguous.

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

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

With no annotations, the description carries full burden. It discloses atomicity, single-return of plaintext, 401 on old key after rotation, and the need to swap credentials before retrying. Also discloses ownership restrictions for agents vs users. This is thorough behavioral disclosure for a security-sensitive 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?

Four sentences, each earning its place: core action, return/urgency, security consequence, permission model, and use case. Information is front-loaded with the action, then consequences, then permissions.

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 one-parameter tool with no output schema, this description is complete. It covers what the tool does, what the caller receives, the failure mode with old keys, the permission boundary, and recommended usage triggers. 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?

Schema coverage is 100%; the id parameter is fully documented in the schema, including agent-omission semantics. The description's 'Agents may rotate ONLY their own key (omit id to default to it)' paraphrases the schema without adding new meaning beyond reinforcing the role distinction.

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 opens with 'Atomically mint a new API key... and revoke the old one' – a specific verb+resource+behavior. It clearly distinguishes from sibling revoke_api_key (only revokes) and rotate_webhook_secret (webhook secret) by naming the API key resource and the rotation semantics.

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: 'routine credential hygiene or after a suspected leak.' Also clarifies role-based invocation: agents rotate only their own key, users may rotate owned keys. Does not explicitly name alternative tools like revoke_api_key, but the use case and constraints are 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 are present, so the description carries full responsibility. It fully discloses critical behavioral facts: the secret is returned exactly once, deliveries immediately switch to the new secret, and receivers still using the old secret will get 401s. This is exemplary transparency for a security-sensitive 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?

Three sentences, each earning its place: purpose, immediate action, and post-condition/use case. No fluff, perfectly front-loaded with the main 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 two-parameter tool with no output schema, this description covers all essential context: the one-time return behavior, the timing of the switch, the impact on receivers, and the recommended use cases. Nothing important is left out.

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

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

The schema covers 100% of parameters with clear descriptions (org_slug, webhook_id; webhook_id even references list_webhooks). The description adds no additional parameter-level detail, matching the baseline of 3 for high schema coverage.

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

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

The description clearly states the action: mint a fresh signing secret for a webhook. It uses specific, action-oriented verbs and identifies the resource (webhook) and the operation (rotation). This distinguishes it from sibling tools like update_webhook or list_webhooks.

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

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

The description gives clear context on when to use the tool ('after a suspected leak or as part of routine rotation hygiene') and explains the required follow-up action (copy the new secret to the receiver). It does not explicitly state when not to use it or name alternative tools, but the provided context is strong.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly reveals that the tool is access-gated ('never returns hits from workspaces the caller can't open') and describes the return format (ranked hits with score 0-1 and navigable URLs). This is substantial, though it omits details like rate limits or error 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 four sentences, each earning its place. It front-loads the core function, then covers return values, access restrictions, and usage context without redundancy or filler. This 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 tool's moderate complexity and the absence of an output schema, the description is remarkably complete. It explains what gets searched, the ranking and URL details, the access-gating behavior, and when to use it. An agent can successfully select and invoke this tool based solely on this description and the schema.

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

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

The input schema already covers all four parameters with 100% description coverage, including defaults and enums. The tool description does not add meaningful parameter-level semantics beyond what the schema provides, so the 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?

The description clearly states what the tool does: it searches across workspace names, row cell values, and doc sections/paragraphs. It uses a specific verb ('Search') and enumerates the exact resources covered, distinguishing it from list-style sibling tools. The scope ('everything the caller can already touch') adds precision.

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

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

The description provides clear usage context: 'Use when the user references something by keyword' with concrete examples. It also contrasts with an alternative approach ('Faster than listing workspaces and iterating'), though it does not name a specific sibling tool. This is better than no guidance but stops short of explicit exclusions.

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

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

With no annotations provided, the description carries the full burden and succeeds: it discloses that the tool QUEUES without waking, refuses agent recipients with a specific error code, resolves against the substrate identity space, follows the caller's identity, enforces a 32k char cap, and returns a specific object. It also covers the pre-deploy 'cue_not_configured' error condition. No behavioral aspect is hidden.

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

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

The description is long, but every sentence adds critical operational context (queuing semantics, refusal behavior, sender identity, error handling). It is front-loaded with the core purpose and flows logically from usage to constraints to return value. It could be slightly tightened, but no sentence is wasted.

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 messaging tool with nuanced agent-vs-human behavior, the description covers every necessary aspect: API path, UI correspondence, address resolution, identity, message cap, return value, scheduling, error cases, and explicit alternatives. With no output schema, the description even provides the return shape. This is fully complete for an agent to select and invoke safely.

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

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

Although schema coverage is 100%, the description adds substantial meaning beyond the schema: it explains the address format ('<agent_slug>@<user_slug>') with concrete examples, the 'self@<user_slug>' convention for humans, mentions body semantics ('@<slug>' mentions CC), replyTo rendering behavior, and the send_at alias. This far exceeds the baseline.

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

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

The description clearly states the verb ('Send'), the resource ('a direct message to another agent or human in the messaging substrate'), and the scope (address format, examples). It explicitly distinguishes itself from the sibling 'message_teammate' by noting it refuses agent recipients, making its purpose and boundaries unmistakable.

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

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

Provides explicit when-to-use ('to message a HUMAN', 'when you deliberately want a human inbox drop without a wake'), when-not-to-use ('Don't use it as a chat-ops side-channel', 'send_message refuses agent recipients'), and names the alternative tool for agent teammates ('use message_teammate'). This is the gold standard for usage guidance.

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

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

With no annotations provided, the description carries full behavioral burden. It thoroughly discloses the security properties (32 random bytes, ~256 bits entropy), public access implications, ability to revoke, required role, and the gating condition (FILES_SURFACE_ENABLED + per-user allowlist). These go well beyond a minimal description.

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

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

The description is compact, front-loaded, and every sentence adds meaningful information: security, revocation, permissions, feature gate, and usage context. 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 the tool's simplicity (2 parameters, no output schema), the description is remarkably complete. It covers the return value format, security implications, revocation path, required role, and feature gating. There are no annotations, so this description fully compensates and provides all necessary context for safe invocation.

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

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

Schema coverage is 100% for both parameters (slug and file_id), so the baseline is 3. The description does not add parameter-specific details beyond what the schema already explains, but this is acceptable since the schema descriptions are comprehensive and the purpose of each parameter is clear from the context.

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

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

The description opens with 'Mint a public share token for a file', a specific verb+resource statement that clearly identifies the tool's purpose. It further distinguishes from siblings like revoke_file_share and share_workspace by describing the exact output (a public URL) and the security model.

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 an explicit use case: 'Use when a workflow needs to hand the file off to an external system that can't authenticate.' It also names the complementary revocation tool ('Revoke later with revoke_file_share') and specifies the editor role requirement, giving clear context for when this tool should be chosen.

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 richly details the behavior: immediate addition vs. 7-day invite token for new users, auto-accept on magic-link sign-in, editor role requirement, and emitted events (member.joined/member.invited). This goes well beyond typical descriptions.

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

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

The description is three sentences, front-loaded with the primary action, then explains edge-case behavior, prerequisites, events, and alternatives. Every sentence adds critical information without fluff or redundancy.

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

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

Despite having no output schema and 3 parameters, the description covers the full context: workflow differences for existing vs. new users, token expiration, prerequisites, emitted events, and explicit pointers to related tools. This is a complete operational guide within the 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?

The schema already provides 100% coverage of parameter descriptions (role default, slug formats, email purpose). The tool description does not add new parameter meanings beyond what the schema states; it focuses on behavioral aspects, so a 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?

The description uses a specific verb ('Invite') plus a clear resource ('a human (by email) to a workspace at a specified role'), making the tool's purpose unambiguous. It also distinguishes itself from sibling tools like update_workspace_member and remove_workspace_member by naming them explicitly as alternatives 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?

The description explicitly states when to use this tool (inviting a human) and names alternative tools for related operations ('Use update_workspace_member to change a role afterwards, remove_workspace_member to revoke'). It also specifies a prerequisite (Editor role required on the workspace), 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 carries full burden. It discloses idempotency, the side-effect of firing `comment.unresolved` with `reason: 'manual'`, and clarifies that reply-triggered unresolve is handled elsewhere. This is rich behavioral context.

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

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

The description is two sentences with no fluff. The core action is front-loaded, followed by idempotency and event details. 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 simple tool with one parameter and no output schema, the description covers purpose, idempotency, event side-effects, and relationship to sibling tools. This is complete for an agent to use it 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 the parameter `comment_id` is fully documented in the schema. The description doesn't add additional format or syntax details, but it doesn't need to; the baseline 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?

The description uses a specific verb and resource: 'Re-open a previously-resolved comment thread.' This clearly states the tool's function and distinguishes it from sibling tools like `resolve_comment`. The idempotency note further clarifies its 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 implies when to use it (manual reopen) and distinguishes from the auto-unresolve via `add_comment`/`reply_to_comment`. It could be more explicit about when not to use it, but the context provided is sufficient for most agents.

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 of behavioral disclosure. It discloses last-write-wins with no CRDT merge, event emissions (doc.updated, doc.heading_added, doc.mention_added), required editor role, data URI rejection (allowBase64: false), video auto-promotion rules, and per-format caps. This is exceptionally 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 long but exceptionally well-structured with bullet points for each markdown feature. It front-loads the core purpose and format-choice guidance, then provides concrete examples and constraints for each feature. Every sentence earns its place; the length is warranted by the tool's complexity.

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

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

For a complex write tool with 5 params, no output schema, and no annotations, the description is fully complete. It covers input format nuances, limits, events, permissions, conflict behavior, cross-tool alternatives, and even references the upload-image endpoint for attaching files. It leaves no practical questions unanswered.

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 substantial meaning beyond the schema. It explains markdown syntax (CommonMark + GFM), TipTap JSON structure, surface_slug default behavior, and the exact conflict error code (-32602) with data shape for if_unmodified_since. All five parameters are enriched with practical usage details.

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

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

The description opens with 'Replace a workspace's doc body' — a specific verb+resource. It clearly distinguishes between the two input formats (TipTap JSON vs Markdown) and explicitly names append_doc_section as the alternative for append-only updates, making it distinct from sibling tools like update_doc_section.

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

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

The description gives explicit when-to-use guidance: 'pass markdown when you're producing prose from scratch... pass TipTap JSON when you need structural edits'. It also points to append_doc_section for append-only updates and explains the if_unmodified_since precondition for multi-agent co-authoring flows, covering both alternatives and exclusions.

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

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

No annotations are provided, so the description carries the full burden. It thoroughly discloses section-boundary semantics (first exact heading match, replacement extends to next same/shallower heading), the failure mode (404 when no heading matches), the markdown contract (full replacement including heading line; empty string deletes), event behavior (doc.mention_added), and the underlying write path. This goes far beyond basic expectations.

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

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

The description is long but every sentence carries distinct value: purpose, alternatives, use cases, section semantics, markdown features, error behavior, event flow, role requirement, and surface slug. It is front-loaded with the primary purpose and maintains clear logical flow from what → when → how. No filler or redundancy.

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

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

Given the tool's complexity (section replacement, boundary resolution, markdown variants, event behavior), and the absence of annotations or output schema, the description is exceptionally complete. It even covers error behavior (404), role requirements, and multi-surface targeting, leaving the agent fully equipped 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%, so the baseline is 3. The description meaningfully supplements the schema by explaining how `heading` is interpreted (first exact match, case-sensitive, boundary at next same/shallower level) and how `markdown` governs the heading line (keep, rename, restructure, or omit). This adds semantic depth beyond the property descriptions.

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

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

The description opens with 'Replace a single section of a workspace's doc body, identified by its heading text' – a specific verb+resource+scope. It explicitly contrasts with `update_doc` (full replacement) and `append_doc_section` (append-only), making the tool's unique role unmistakable.

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

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

The description gives explicit when-to-use guidance with concrete recurring-section examples ('Status' block, 'Outcomes' block), names the alternative tools (`update_doc`, `append_doc_section`), and explains why this tool avoids GET→splice→PUT (token cost, latency, edit races). It also notes the editor role requirement, further clarifying 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It thoroughly details the sandboxed iframe on a separate origin, per-field caps, sanitizer rules, full-bleed layout constraints, injected design tokens/components, and role requirement. This is exemplary transparency for a mutation 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 lengthy but well-structured into labeled sections (Layout, DESIGN LANGUAGE) and stays dense with actionable info. It front-loads the core purpose and behavior before design aesthetics, and no sentence is wasted. Some expansion (e.g., listing every component class) could be seen as over-detailed, but it's appropriately sized for the complexity.

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

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

For a write tool with no output schema, the description covers input, safety boundary, size limits, styling guidance, and authorization. It explains partial updates and clearing semantics ('Pass empty string to clear'). The only minor omission is error handling, but that is not required for selection and 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%, and the description adds substantial semantic guidance: allowed CDN libraries, sanitizer stripping of inline on* attributes, per-field caps, and design-token usage. It tells the agent exactly what values to pass for html/css/js (e.g., 'use addEventListener instead of inline handlers'), exceeding the schema's field descriptions.

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

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

The description opens with 'Write an HTML surface's body' — a specific verb and resource that clearly distinguishes it from siblings like get_html, create_surface, and validate_html. It explicitly lists the mutable fields (html/css/js) and the partial-update semantics ('omitted fields stay unchanged').

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

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

It states 'Requires editor role' and recommends 'Use validate_html first for a pre-flight check', giving clear invocation context and a companion validation tool. The optional surface_slug is explained ('Omit to write the primary html surface'). It doesn't explicitly name alternatives for creating surfaces or updating metadata, but the context is sufficient.

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