Dock

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

With no annotations, the description carries the full behavioral burden and does so richly: server flattens nested replies to single depth, auto-unresolves a resolved parent, validates each mention's workspace access, and fires `comment.added` / `comment.unresolved` events. These are non-obvious side effects an agent could not infer from 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?

Purpose is front-loaded in sentence one; each subsequent sentence adds distinct operational information (threading, mentions, events, alternative tool, permission). No filler or restatement of the name.

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, polymorphic, nested-target mutation tool with no annotations and no output schema, the description covers the target model, threading semantics, mention validation, emitted events, and role requirements. Nothing needed to call it correctly is missing.

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 real meaning beyond the schema: it explains that parentId triggers flattening and parent-reopening, and that mentions are access-validated with inbox/email/webhook fan-out to newly-mentioned recipients only. It does not restate the target shapes, correctly leaving those to 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?

Opens with a specific verb+resource ('Post a new comment') and immediately enumerates the exact target kinds it supports (row, cell, doc text range, html element, surface, workspace). It explicitly distinguishes itself from the sibling reply_to_comment, so an agent can route without opening either schema.

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 both when to use it and when to prefer the alternative: 'For replies to existing comments where you don't want to reconstruct the target, prefer reply_to_comment which derives the target from the parent.' It also gives the prerequisite ('Editor or commenter role required'), covering the main gating condition.

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?

Since no annotations are provided, the description carries the full burden of disclosing behavior, and it does so thoroughly. It covers atomicity ('ALL-OR-NOTHING', rollback, safe resend), batch limits ('Up to 500 rows per call'), single-surface targeting, the auto_create_columns schema-extension behavior, and the return 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 dense but every sentence earns its place: purpose, when to use, payload shape, limits, atomicity, target surface, column behavior, and return value are all covered without redundancy. It is front-loaded with the core action and differentiator.

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 4-parameter tool with no annotation coverage and no output schema, the description provides everything needed to invoke it correctly: required vs optional parameters, batch constraints, rollback behavior, schema-extension side effect, and returned fields. No critical gap remains for the agent to infer.

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

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

Even though the schema already documents all four parameters, the description adds meaning beyond the structured fields: it clarifies the exact rows payload shape as `{ data: {...} }` maps, states the batch limit, explains the all-or-nothing failure semantics, and specifies that auto_create_columns performs 'one schema extension'. This materially helps an agent formulate correct calls.

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 action and resource: 'Append many rows to a workspace's table surface in ONE call.' It also explicitly identifies itself as 'the bulk version of create_row', which distinguishes it from the create_row sibling and makes its 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 direct usage guidance: 'Use this instead of looping create_row when ingesting more than a few rows (lower latency + token cost).' This names the alternative and the exact condition for choosing this tool, leaving no ambiguity about when it should be used.

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, 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?

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, the description carries the full load and does so: auth requirement (Editor role), side effects (result added as a new video labelled '<label> (edited)' or replaces the original with replace:true), a domain event (video.updated), hard limits (10 minutes, 1920px), and the timeline convention (all times in the ORIGINAL video's timeline).

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 dense, the purpose is front-loaded in the first sentence and every subsequent clause adds operational value: parameter semantics with worked examples, timeline convention, result naming, limits, and the verification step. No sentence is 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 14-parameter, no-output-schema mutation tool this is complete: it explains what each mode does, what happens to the output artifact, what the reply's summary contains, the permission required, and the operational limits. Nothing an agent needs to invoke it correctly is missing.

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 and the schema already documents all 14 parameters. The description still adds real meaning beyond the schema: interval semantics ('take ranges OUT and keep everything else' vs 'keep ONLY one span and drop the rest'), 'give one to keep the shape' for width/height, and the fallback behavior implied by passing or omitting label.

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?

States a specific verb and resource ('Make a new version of a video in a video surface') and enumerates the operations it supports (remove, keep, format, resize, aspect, fps, speed, mute). It distinguishes itself from watch_video by assigning that tool the time-finding role, but it never explicitly contrasts with the similarly named siblings update_video or add_video, so routing against those is left to inference.

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?

Gives explicit when/when-not and alternatives: use watch_video first to find exact start/end, use keep when you want only one span, use remove when you want to cut ranges out, and check the returned summary against the request. It also closes the loop with 'Watch the result with watch_video before telling anyone it's done.'

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?

Although no annotations are provided, the description fully discloses the behavioral aspects: it explains that returned caps are live and enforced, and importantly, it warns that price-shaped fields are retired and must never be quoted, directing to `currentPlans.tiers` for actual charges. This is critical behavioral disclosure that prevents misuse of the tool's output.

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-loading the core purpose and the key actionable insight ('caps are live and enforced'), then delivering the critical pricing caveat. Every sentence serves a purpose, with no filler. It is succinct while covering essential information.

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

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

Given the tool has zero parameters and no output schema, the description fully compensates by detailing the scope of the response (resources and billing info) and the crucial caveat about retired prices. It also implicitly guides the agent on how to use the data (for caps and actual pricing). There is no missing information that would impede correct invocation or interpretation.

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 schema offers no hints. The description compensates by thoroughly describing what the response contains (active counts, caps, card-on-file, next invoice date) and the critical distinction between usage and pricing. Since there are no parameters, the description's role is to clarify the output semantics, which it does well.

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 that the tool retrieves the caller's org resource caps and usage, listing specific resources (agents, members, workspaces, etc.) and includes billing details like card-on-file and next invoice date. This is a specific verb ('get') and resource ('billing'), and it stands out among siblings because no other tool retrieves billing/caps information.

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 mentions that the caps are 'live and enforced' and instructs the agent to 'use them,' implying this tool is for checking current usage against limits. It also explicitly states what the tool does NOT do ('This tool does NOT price anything') and warns against quoting retired prices, instead directing to `currentPlans.tiers` for actual charges. This provides clear when/when-not 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 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?

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, the description carries the full burden and does disclose key behavior: transcription happens on first use, results are cached on the video until the file changes, refresh overrides the cache, and a Viewer role is required. It omits failure/edge behavior (e.g., videos with no audio or unavailable transcripts), which keeps it below a 5.

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 short sentences, each earning its place: return shape first, then caching/refresh behavior, then the span hint, then the permission requirement. Nothing redundant and the most decision-relevant 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?

For a read tool with no annotations and no output schema, the description covers return shape, caching, span control and auth. It is largely complete; only edge-case behavior for videos without transcribable audio is unaddressed.

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

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

Schema description coverage is 100% and all six parameters are documented there, including the flexible time format for start/end and the refresh semantics, so the schema does the heavy lifting. The description restates the start/end span idea and adds caching context but no syntax or defaults 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?

States a specific resource (the transcript of a video in a video surface) and the return shape (timestamped segments), so the agent immediately knows this is a transcript-retrieval tool rather than a video-metadata tool like list_videos or watch_video. It does not explicitly name a sibling it must not be confused with, so it stops short of a 5.

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?

Usage is implied rather than instructed: the agent can infer it should call this when it needs spoken content, and the description notes start/end for spans and the Viewer role prerequisite. There is no explicit when-to-use/when-not or pointer to list_videos for resolving video_id (that hint lives only in the schema).

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 provided, the description carries the full burden and does so thoroughly: it discloses read-only behavior, visibility limits across persons and orgs, current-org behavior, newest-first ordering, a 100-ticket cap, output fields, and an explicit exclusion of the staff queue. This is rich, non-obvious 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 longer than average, but every sentence adds critical context: identity scoping, org scoping, order/cap, filter syntax, return fields, and an explicit non-goal. It is front-loaded with the core purpose and then builds outward 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?

Given the lack of annotations and output schema, the description is remarkably complete: it covers what is returned, how results are ordered and capped, how filtering works, visibility boundaries, the relationship to create_support_ticket, and the key alternative it is not. An agent has enough context to invoke this tool correctly and interpret its results.

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 `limit` and `status`. The description adds ordering behavior and a cap of 100, but most parameter-level meaning is already present in the schema. The description reinforces but does not substantially extend the structured parameter documentation.

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

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

The description clearly states the tool lists support tickets filed by the caller, is read-only, and explicitly differentiates itself from create_support_ticket and the separate support-staff queue. The verb, resource, and scope are all specific and actionable.

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

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

It explicitly says when to use this tool (e.g., to check on a ticket after filing it) and when not to use it (the support-staff queue is a separate, staff-only tool). It also clarifies scoping to the current org and to tickets filed by the user or their owned agents, leaving no ambiguity about fit versus alternatives.

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

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

With no annotations, the description 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 usefully discloses the authorization requirement ('Viewer role required'), the read ordering, and the exact shape of each returned record — more than most list tools. It is silent on pagination, result caps, and behavior on an empty surface, so it is not fully 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?

Three tight sentences, front-loaded with the core action and scope, then the parameter rule, then the prerequisite. The enumerated field list is long but justifies itself because there is no output schema; nothing is padded.

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

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

With no annotations and no output schema, the description compensates well by naming the return fields, the play ordering, and the role requirement. It leaves minor gaps around pagination and edge cases (empty surface, invalid slug) but is otherwise sufficient to call the tool correctly.

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

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

Schema description coverage is 100%, so both parameters (slug and surface_slug) are already documented in the schema; baseline is 3. The description restates the surface_slug omission rule, adding emphasis but no new syntax, format, or default detail 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?

States a specific verb and resource ('List the videos in a video surface') plus the ordering ('in play order') and the returned fields, so the agent knows exactly what it gets back. It does not, however, name or contrast any sibling (e.g. list_surfaces) to disambiguate the surface-vs-workspace boundary, which the rubric reserves for a 5.

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?

Gives a concrete usage rule for the optional parameter ('Omit `surface_slug` for the workspace's first video surface') and a prerequisite ('Viewer role required'). It stops short of naming alternatives or stating when NOT to use this tool, so it is clear context without full when/when-not routing.

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?

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 carries the full burden and does real work: it discloses the required Editor role (auth) and the emitted `video.updated` event (side effect). It leaves gaps on reversibility and whether removal detaches versus permanently deletes the video, which matters for a destructive operation.

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

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

Three short sentences, no filler, with the core purpose front-loaded and prerequisites/effects following. 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?

For a destructive, annotation-free mutation with full schema coverage and no output schema, the description covers purpose, id source, authorization, and event emission. It is nearly complete, missing only reversibility/detach-vs-delete semantics.

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 all three parameters are already documented in the schema; the description only reinforces the video_id source. Baseline 3 applies since the schema does the heavy lifting and the description adds no format or constraint detail.

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

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

States a specific verb and resource with scope: 'Remove one video from a video surface.' An agent can immediately distinguish this from add_video, update_video, and list_videos without opening any schema.

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

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

Provides clear prerequisite context ('Get video_id from list_videos') and access requirements ('Editor role required'), which tells the agent how to prepare and when it is permitted. It does not name alternative tools or any when-not condition, so it falls short of the explicit routing seen in 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 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 provided, the description carries the full burden and does so thoroughly: it discloses that the tool does not actually connect or grant access, reports state, behaves differently per state, and that the result is a user-facing approval card. It even warns about the API-key alternative, giving strong 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 the description is long, every sentence earns its place: the tool's nuanced states, required user actions, and don'ts all need explanation. The purpose is front-loaded in the first sentence, and the formatting (including the warning marker) makes critical behavior easy to spot.

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 there being no output schema, the description names the exact response keys an agent needs ('connection_required', 'already_connected', 'you_have_access', 'ask_with_marker') and explains what to do in each case. Given the tool's complexity and lack of annotations, this is fully complete for correct invocation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces toolkit_slug significance with examples and notes that only Dock-supported apps are accepted, but it does not add substantial new parameter-level 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 uses a specific verb and resource: 'Ask your owner to connect a third-party app... so you can use its tools.' It also explicitly differentiates this tool from a direct connection by stating 'It does NOT connect anything and does NOT give you access,' which clearly sets it apart from sibling request and access 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 gives explicit when-to-use guidance: 'Call it when a task needs an app you cannot currently reach.' It also provides exclusions and alternatives by warning against repeated calls, distinguishing the two response states, and explicitly forbidding asking for API keys instead.

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 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 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?

With no annotations, the description carries full burden. It discloses the move behavior (position recompute, tail unless position set, same-surface no-op), unmapped fields storage without rendering, response containing unmapped_fields and warning, and the atomic auto-create behavior with created_columns. This is exceptional transparency.

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

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

The description is dense but well-organized, using bold headers to separate core update behavior from unmapped data handling. No redundant sentences; all information is essential.

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

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

Given the tool's complexity (6 params, no output schema, no annotations), this description covers edge cases, return values, and interactive behaviors comprehensively. It's complete for an agent to use correctly.

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

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

Schema already covers all 6 parameters with 100% coverage. The description adds extra semantic context beyond schema, such as the unmapped_fields response array, the atomic behavior of auto_create_columns, and how position interacts with surface_slug moves. This adds value over 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 'Update specific fields of an existing row,' clearly identifying the verb and resource. It distinguishes from siblings like create_row and delete_row, and even addresses the row-moving overlap with move_rows by explaining when surface_slug moves a row and when it's a no-op.

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 explains partial update semantics ('Only the fields provided in data are updated; others are preserved') and gives guidance on auto_create_columns default being 'safe choice for explicit schema management.' However, it doesn't explicitly name alternatives like 'use move_rows for bulk moves' or state when not to use this tool, so it's clear but lacks 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, the description carries the full burden and does well: it discloses the required authorization level ('Editor role required'), the side effect emitted ('Emits video.updated'), and PATCH-style merge semantics. It omits reversibility and whether a file swap is destructive to the prior asset.

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 dense sentences with the core action front-loaded, followed by the ID source, merge semantics, permission requirement, and event. Every clause carries information; nothing is padded.

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 and no annotations, so the description must cover behavior — it does so with auth, partial-update semantics, event emission, and the ID source. It leaves the response shape and the effect of swapping a file's underlying asset unstated, but an agent has enough 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?

Schema description coverage is 100%, so the baseline is 3. The description loosely maps 'swap its file (`url`)' and 'rename/relabel' to parameters, but adds no syntax, constraints, or format detail beyond the schema's own per-field documentation (URL types, char limits).

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?

States a precise verb and resource ('Change one video in a video surface') and enumerates the concrete mutations (swap file, rename, relabel). An agent can distinguish this from add_video and remove_video without opening any schema.

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?

Gives explicit sourcing guidance ('Get video_id from list_videos') and clarifies partial-update behavior ('Omitted fields stay as they are'), which tells the agent it need not supply every field. It stops short of naming when-not-to-use or pointing at an alternative 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 burden of behavioral disclosure. It explains that inactive webhooks are skipped at delivery time, produce no retry queue or log row, and that the config is preserved, making the toggle reversible in one call. This gives meaningful side-effect awareness beyond the schema.

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

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

The description is two succinct sentences. The first sentence states the action clearly; the second adds behavioral consequences and a practical use case. Every sentence earns its place without redundancy.

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

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

For a simple three-parameter tool with no output schema, the description fully covers purpose, behavior, side effects, and when to use it. There are no obvious gaps in what an agent needs to know 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?

Parameter schema coverage is 100%, with each parameter having a description. The tool description adds contextual meaning to the `active` parameter ('Toggle... on or off') and clarifies the preservation of endpoint config, but it doesn't add significant new info about `org_slug` or `webhook_id` 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 states a specific verb+resource: 'Toggle a webhook's `active` flag on or off.' It clearly distinguishes this from destructive alternatives like delete_webhook by noting that the endpoint config is preserved and flipping back is one call.

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 use case: 'Use to silence a noisy receiver during maintenance without losing its URL + secret + event subscription.' It implies when to use this versus deleting/recreating a webhook, though it doesn't explicitly name alternative sibling 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 provided, the description fully carries the behavioral burden. It discloses authentication requirements (Editor/owner), the sole-owner protection rule, no-op behavior, and the emitted event `member.role_changed` with from/to roles. This significantly goes beyond the structured schema, offering complete transparency about side effects and constraints.

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, with five short sentences each delivering distinct, high-value information: operation, permission requirements, edge case, no-op behavior, and event output. No filler or repetition of schema details; 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?

For a mutation tool with only three parameters, no output schema, and no annotations, the description covers all critical contextual aspects: required permissions, owner-specific restrictions, success semantics (no-op), and the resulting event. This is complete enough for an agent to invoke the tool safely and effectively, including knowing when to avoid it (sole-owner demotion).

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

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

The schema already provides 100% parameter descriptions, including the slug format, member_id source, and role enum. The tool description does not add new parameter-level meaning beyond the schema, though it does contextualize role transitions. This is a case where the structured data covers the semantics, and the description adds no extra parameter detail.

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

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

The description opens with 'Change an existing workspace member's role,' naming a specific verb, resource, and operation that distinguishes it from sibling tools like remove_workspace_member (removal) and share_workspace (inviting/sharing). This clear action and resource scope leaves 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 explicit usage conditions: caller must have Editor role, owner-tier transitions require an owner caller, demoting the sole owner is blocked with a concrete workaround ('promote someone else to owner first'), and the operation is a no-op when the role is unchanged. These are precise when-to-use and when-not-to-use instructions.

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

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

With no annotations present, this description carries the full behavioral burden, and it delivers: it discloses the consent-gated flows, the two surfaces (chat/web) with their exact first-call responses and follow-up steps, expiration times, polling behavior, and the no-card/same-plan immediate-execution paths. It also flags the 'scale' name collision across the two systems and that adding agents doesn't change the bill.

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 given the tool's complexity; the retired-plan warning is front-loaded, and the flow details are logically ordered. It could be broken into sections for readability, but it remains appropriately sized.

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 fully compensates by specifying the exact response shapes for each branch (confirmation_required, approval_required, and the immediate-execution cases) and the consent token requirements. It also covers the key edge cases (no card, same plan, expiry) and the warning about the retired system, so an agent has everything needed 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 coverage is 100% and the input schema already comprehensively describes each parameter, including `confirm_token` semantics (single-use, 60s TTL, binding). While the description weaves these into the flow narrative, it adds little beyond what the schema's parameter descriptions already state, so a 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?

States a specific verb ('Moves') and resource ('the caller's org') and precisely defines the target plans (Pro and Scale) with their caps. Explicitly distinguishes itself from Dock's live product (Dock Tokens) and from get_billing's currentPlans, making its 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?

Provides an explicit warning that this is a retired system and should not be offered as current pricing, and points to get_billing's currentPlans as the alternative for live pricing. Also gives concrete direction on selecting `mode`: chat for interactive round-trip, web for headless or click-to-approve flows.

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 discloses that it 'NEVER writes anything; pure parse + analysis' and details the return structure (ok, errors, warnings, parsed counts), including non-blocking warnings like unresolved cross-refs. This fully covers side effects and output 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 dense but front-loaded with the primary purpose and usage. It lists many parsed field names and warning types, which is useful but slightly verbose. Every sentence contributes relevant information, though a more concise version could omit some enumerated counts.

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 no annotations, the description fully explains the return value shape, the read-only safety profile, the usage context, and a key behavioral constraint (workspace-gated resolution). This is exceptionally complete for a validation tool of this complexity.

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

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

The input schema provides 100% coverage with a clear description of the markdown parameter, so the baseline is 3. The main description adds no additional parameter-specific details beyond referencing the same markdown surface, so no extra credit is warranted.

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 'Pre-flight check on markdown BEFORE writing it via update_doc / append_doc_section' and explicitly says 'NEVER writes anything; pure parse + analysis.' This specific verb and resource distinction sets it apart from sibling write tools and other validators.

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

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

It explicitly says to use it 'when iterating on rich-format markdown to catch problems before burning a write' and positions it as a precursor to update_doc/append_doc_section. It also notes that cross-ref resolution is gated on the caller's accessible workspace set, which informs when and how to use the tool.

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

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

With no annotations, the description carries full transparency burden and excels. It discloses non-mutation ('without writing anything'), explains return fields (ok, error?, rewrittenFormula?, etc.), details what unknownFunctions and referencedFunctions mean, and warns about cells storing invalid formulas. It also notes cost and auth characteristics, all beyond any structured data.

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

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

The description is front-loaded with the core purpose, then returns, then usage guidance, then internals. Every sentence adds value: the failure-mode example, the explanation of return fields, and cost/auth notes. No fluff or repetition despite covering multiple aspects.

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

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

With no output schema, the description fully explains return values and their semantics. It also covers when to use the tool, side-effect-free behavior, environment requirements, and failure scenarios—complete for a single-parameter validation 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 schema already covers the single parameter fully (example, max chars, leading '='). The description adds context about the parameter's role in validation but does not introduce new format or syntax details beyond the schema, so the baseline of 3 applies.

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

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

The description opens with 'Parse-check a formula expression server-side without writing anything', a specific verb and resource that clearly distinguishes it from evaluation tools. It also explicitly references update_row/create_row, making its role distinct from siblings like evaluate_formula.

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 BEFORE update_row / create_row when the formula references functions or syntax you're not 100% sure of'. It includes concrete examples of failures and clarifies prerequisites ('no auth, no workspace context needed'), leaving no ambiguity about appropriate invocation.

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

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

Despite having no annotations, the description fully discloses behavior: returns structure, error codes, sanitizer specifics (accepts script/link, strips on* attributes, etc.), and the no-write guarantee. It even explains the v2 change and isolation rationale, providing extensive transparency beyond minimal requirements.

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

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

The description is detailed but each sentence earns its place. It is logically structured: purpose, return shape, error codes, sanitizer behavior, no-write guarantee, and use case. Information-dense without being bloated.

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

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

Given no annotations, no output schema, and the tool's complexity, the description covers all essential aspects: return format, error semantics, sanitizer rules, and intended usage. Completely adequate for an agent to understand and invoke the tool correctly.

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

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

Schema coverage is 100% with basic descriptions, but the description adds meaning by explaining how the html parameter is validated against sanitizer rules (dropped flag), cap breaches, and error codes. It enhances understanding of parameter purpose beyond the schema's minimal 'HTML to validate (optional)'.

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 performs a pre-flight check on html/css/js before writing via update_html. It uses a specific verb and resource, and the context distinguishes it from sibling validation tools like validate_doc_markdown and validate_formula.

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

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

Explicitly says 'Use when iterating on a payload so you don't burn a write on something the surface would reject.' This provides clear when-to-use context, though it doesn't mention alternatives like validate_doc_markdown or validate_formula. The 'NEVER writes anything' statement adds important 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 does well: it discloses that transcripts are cached on first use, that the call is capped at 32 frames, that a viewer role is required, and that `comment_id` overrides surface_slug/video_id/position args and outlines the drawn box in red. It stops short of describing error conditions or performance/staleness trade-offs.

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?

Front-loaded with the core behavior in sentence one, then modes, then limits and prerequisites. Dense with parentheticals but each sentence is functional; appropriate length given 13 parameters and no annotations to lean on.

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 convey return shape, which it does (frames as time-labelled images plus spoken span), along with limits, prerequisites, override semantics, and default behavior. An agent can call this tool correctly from the description alone.

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

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

Schema coverage is 100% so baseline is 3, but the description adds real meaning: it explains the interaction of `at` vs `start`/`end` vs `times`, that `frames` counts while `fps` sets a rate, that the video's own fps reveals every frame, and that `comment_id` overrides other position args. This improves on the schema without contradicting 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?

States a specific verb+resource ('Look at a video in a video surface') and immediately defines the output ('returns frames as images, each labelled with its time, plus what is said in that span'). This distinguishes it clearly from siblings like get_video_transcript (transcript only) and edit_video/update_video (mutations).

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

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

Gives explicit mode selection: no position = whole-video overview, `at` for around a moment, `start`/`end` for a range, `times` for exact moments, plus the workflow 'Look at the overview first, then zoom in' and the 'Viewer role required' prerequisite. It does not, however, explicitly name alternative siblings such as get_video_transcript for the text-only case.

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