Dock

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

No annotations, so the description carries the full burden, and it delivers real behavioral context: position is auto-computed as next-after-max to preserve a contiguity invariant, a 409 key collision surfaces if the key exists, and Editor role is required. It falls short of disclosing return value, rate limits, or what happens to existing rows when the column is added.

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 dense sentences, each carrying distinct value: purpose, position invariant, error behavior, auth requirement, sibling routing, and surface targeting. Front-loaded with the core action and no filler.

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

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

For a mutation tool with no annotations and no output schema, it covers purpose, permissions, error semantics, and targeting well. The main gap is what the call returns (the created column representation), which an agent might want given no output schema is defined.

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 8 parameters including surface_slug, options, and description. The narrative reinforces surface_slug's fallthrough behavior but adds little syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Append a single column to a workspace's table schema') and explicitly contrasts itself with siblings ('use get_workspace_schema + update_surface with `columns` for full schema replacement or reordering'). An agent can distinguish it from update_surface/add_column alternatives without opening a 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?

Names the alternative path and the condition that selects it (per-column additions vs. full replacement/reordering), plus routing guidance for surface_slug with a pointer to list_surfaces when multi-surface. Explicit when-to-use and when-to-use-something-else.

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

With no annotations, the description carries the full burden and does so well: it discloses the no-argument nature, the returned status fields (online/alive/listening, brandKey, ownerAddress), the stability semantics of each identity field, and a concrete warning that agentId is the messaging id and must not be joined against event logs. The only meaningful gap is auth/permission 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?

Front-loaded with purpose and routing before the field breakdown, and the bulleted structure maps cleanly to the return fields. It is dense and slightly long, with the 'Rule of thumb' line partly restating earlier content, but almost every sentence carries real 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?

No output schema exists, so the description must explain the return shape, and it does: identity fields, their mutability, and the status fields. Combined with the sibling routing guidance, an agent has everything needed to call and consume this tool correctly.

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

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

Zero parameters, so the baseline is 4. The description explicitly confirms 'Takes no arguments,' which is consistent with the empty schema and adds nothing to misread.

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 (Lists) and resource (agents you can reach), and immediately clarifies the scope: your own agents AND agents shared from other owners. It explicitly distinguishes itself from the messaging siblings (message_teammate, send_message), so an agent can tell what this tool is and is not.

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 routes: to message any returned agent use `message_teammate`, and 'Do NOT use send_message for an agent — that path does not wake them.' It names the alternative and the condition that selects it, plus the failure mode of the wrong choice.

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 behavioral burden. It discloses that Dock downloads and keeps its own copy (so expiring links keep working), requires the Editor role, and emits `video.updated`. Excellent transparency, though rate limits or failure modes aren't mentioned.

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 moderately long but front-loads the core purpose and then provides necessary context. Every sentence earns its place, though it could be slightly tighter without losing essential details.

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 6-parameter mutation tool with no output schema, the description covers the key behavioral aspects: storage semantics, prerequisites, alternatives, role requirement, and event emission. It's complete enough for an agent to call correctly, though it could note whether the added video is appended or replaces existing content (it says 'end of a video surface', which implies append).

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 parameters are already documented in the schema. The description adds context for `url` (expiring links), `content_type` (inference), and `label` (use case), but doesn't add meaning beyond what the schema provides. Baseline 3 is correct.

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 ('Add a video to the end of a video surface'), and names the accepted formats. It distinguishes itself from siblings like update_video and edit_video, which mutate existing videos rather than appending a new one.

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 names the prerequisite (create_surface with kind: "video"), the alternative for local files (create_video_upload), the content_type fallback condition, and the required role. This covers when to use and when-not to use clearly.

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 so thoroughly: it discloses the server-side fetch/splice/write mechanism, the shared auth path and byte/depth/node-count guard, that append is non-idempotent by design with dedupe left to the caller, that @-mentions fire doc.mention_added plus inbox/email fan-out only for newly added mentions, and that editor role is required. These are exactly the traits an agent cannot 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?

The core purpose and non-idempotency caveat are front-loaded, and the sentences are information-dense rather than padded. However, the long enumerated markdown surface (callouts, KaTeX, mermaid, embeds, mentions) is boilerplate-heavy and inflates the description well beyond what is needed to select and invoke a 3-parameter append tool.

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

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

For a no-annotation, no-output-schema mutation tool, the description covers auth requirements, side effects, event fan-out, and guard limits, which is substantial. It stops short of stating the return value or error behavior when the guard is exceeded, leaving a small gap.

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 it: it explains that markdown becomes one or more new blocks at the end, and that surface_slug selects a specific doc surface in multi-surface workspaces (omit for primary). It also documents markdown constraints such as HTTPS-only images and the 100 MB video limit, which are not in the schema.

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

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

States a specific verb and target ('Append a chunk of Markdown to the END of a workspace's doc body') and explicitly scopes the tool as append-only rather than replace. This cleanly separates it from siblings update_doc and update_doc_section. An agent can tell what it does without opening the 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?

Names the intended callers ('crons + ingest agents that produce content in timestamped chunks') with concrete examples (changelog updates, daily standups, batch summaries), which is strong when-to-use context. It does not, however, state when NOT to use it or explicitly route to update_doc/update_doc_section for full-body replacement, so the alternative-selection rule is left implicit.

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

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

Given the lack of annotations, the description performs critical behavioral disclosure, including the 500-row limit, the ALL-OR-NOTHING rollback on error, and the operational risks of batch processing. It also details how `auto_create_columns` modifies the schema in real-time.

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

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

The description is lengthy but highly effective, logically chunking information into use case, strategy, error handling (ALL-OR-NOTHING), and specific feature details (`auto_create_columns`). It is efficiently written, with zero wasted space.

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

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

It provides a comprehensive overview of the operational mechanics, explicitly stating the response payload structure and addressing the dual signaling of unmapped fields (warning vs. automated column creation).

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

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

While the input schema covers most parameters, the description clarifies the structure of the `rows` array (array of objects with a `data` field) and explains the scope of `surface_slug` (optional, defaults to primary surface), adding necessary context beyond simple schema definition.

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

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

The description clearly identifies the tool as the 'bulk version of create_row' used to append many rows to a workspace table surface in one call. It distinguishes its purpose by highlighting its use as a bulk operation to the user.

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 usage instructions, telling users to use it instead of looping create_row for performance (latency + token cost). It further advises on workflow strategy for large jobs, recommending batches of 25-50 rows sent progressively.

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 so: merge/last-write-wins semantics, a 500-row cap, all-or-nothing atomicity with the exact failure trigger (missing id or cross-workspace id), safe-resend guidance on error, type coercion, and the return shape. This is unusually complete behavioral disclosure.

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

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

Opens with the verb+resource and the sibling comparison, then layers payload shape, merge rules, limits, and failure semantics. Every sentence carries a distinct behavioral fact; there is 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?

Despite having no output schema, the description names the return value (`{ updated, rows }`) and covers atomicity, limits, coercion, and error recovery. For a 2-parameter bulk-mutation tool with no annotations, nothing an agent needs 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 goes further by explaining the merge semantics of `data` (only send changed cells, last-write-wins per field), the provenance of `id` (from list_rows / get_row), and the 1-500 range. It adds genuine meaning beyond the schema's field descriptions.

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

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

States a specific verb and resource ('Update many existing rows') and explicitly positions itself as 'the bulk version of update_row', which cleanly separates it from both update_row and bulk_create_rows in the sibling list. An agent can pick it 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?

Gives an explicit selection rule: use this instead of looping update_row when changing more than a few rows, and cites the reason (lower latency and token cost). The named alternative and the threshold condition make the choice unambiguous.

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

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

With no annotations, the description carries the full burden and does so: it declares the check is server-side/authoritative and current, enumerates the exact return fields, states results are counts only (no member identities leaked), and specifies behavior on failure, error, timeout or unavailability.

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 purpose and the safety-critical precondition, and every clause earns its place. The middle sentence is dense with parentheticals and field enumerations, which slightly hurts scanability but not correctness.

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 correctly supplies the return shape and field meanings, plus the negative-path instruction. For a one-parameter read check, nothing an agent needs 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 description coverage is 100% and the single 'slug' parameter is fully documented in the schema, including the bare vs org-prefixed forms. The description adds no parameter detail beyond that, 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?

States a specific verb (check), a specific resource (workspace privacy) and an authoritative scope ('on the server ... right now'). It even defines the predicate operationally (all members are owner/agents, no open invite, no active file share link), so it is unmistakable versus siblings like get_workspace or list_workspace_members.

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 prescribes when to call it ('BEFORE writing anything owner-private ... and before every such write session') and what to do when it fails (write nothing, tell your owner). Names the class of content at risk (Voice profile, Second Brain, personal notes), which is actionable routing 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 so well: it discloses one-time use, allowed file types, plan-specific size caps, the authoritative `max_bytes` field, 15-minute expiry, and editor role requirement. It also explains the returned `curl` command and JSON response containing `url`.

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: it opens with the core purpose, then explains mechanics, limits, expiry, and alternatives. Every sentence provides actionable information for correct invocation.

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

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

Given no output schema and no annotations, the description still covers the essential return behavior (`curl` command, JSON response with `url`, `max_bytes`), operational constraints, role requirement, and next step. Nothing critical for correct selection and invocation 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 schema already documents `slug`, `filename`, and `content_type` thoroughly. The description adds process context but does not add meaning beyond the schema for these parameters, so baseline 3 is appropriate.

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

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

States a specific verb and resource: get a one-time upload link for a local file into Dock. It clearly distinguishes itself from `create_video_upload` for video surfaces and from `upload_file`, which is the next step after obtaining the link.

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

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

Explicitly says when to use it (file on your machine, PDF/image/spreadsheet/audio/archive, over ~3 MB, no public host), when to use an alternative (`create_video_upload` for video surfaces), and how to sequence it with `upload_file`.

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 carries the full behavioral burden and it does disclose a critical trait: a hard access gate that refuses non-Dock callers. It stops short of describing side effects (the schema hints tickets become GitHub issues) or what the caller receives on success. Strong on the access constraint, thinner on operational effects.

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

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

Front-loaded with the core action and the access gate, then the fallback routing. The nested parenthetical about send_email/email_owner and desktop Settings is somewhat verbose but each clause is actionable routing information, so it 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 5-parameter mutation tool with 100% schema coverage and no output schema, the description supplies the missing behavioral context (who may call it, what to do instead). It does not describe success response or duplicate-ticket behavior, but the sibling list_my_support_tickets partly covers follow-up, so the gap is minor.

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 body, kind, title, context, and attachmentUrls with examples. The description adds no parameter-specific meaning, which is the expected baseline of 3 when the schema does the heavy lifting.

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

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

The opening sentence gives a specific verb+resource: "File a support ticket." It goes further by naming a sibling alternative (request_limit_increase) and the non-Dock fallback paths, so an agent can place it against siblings. It slightly restates the tool name, which keeps it from a clean 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?

Explicit when-to-use and when-not-to-use: only Dock-team agents may call it, everyone else is refused and should email agent-support@trydock.ai or ask their human. It also names request_limit_increase as the preferred tool for plan caps. Nothing is left to inference.

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

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

With no annotations, the description carries the full burden and does well: editor role required, emits surface.created for live listeners, slug collision auto-suffixes, table starts empty. It omits idempotency/rate limits, but the auth requirement and event emission are the key operational traits an agent needs.

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?

Dense but front-loaded: the core action leads, kinds are enumerated next, and per-kind detail follows. Every sentence routes the agent to a concrete sibling tool, though the kind-specific block is long and could be tighter.

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 five-kind creation tool with no output schema and no annotations, the description covers role requirements, event emission, and the post-creation workflow for each kind. The one gap is the ambiguous slug/surface_slug naming, which leaves the agent guessing which parameter carries the surface slug.

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, and the description does add value (columns start empty for tables, slug auto-derivation and collision suffix, columns ignored for non-table kinds). However it mislabels the surface slug as `slug` and calls it optional, while the schema defines `slug` as the required workspace slug and puts the surface slug in `surface_slug` — a naming/semantics inconsistency that undercuts an otherwise rich description.

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

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

States a specific verb+resource ('Create a new surface inside a workspace') and enumerates the five kinds, making it clearly distinct from list_surfaces, update_surface, and delete_surface. An agent immediately understands what is created and the allowed variants.

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 concrete follow-up routing per kind (write html via update_html, files via upload_file/list_files, videos via add_video/create_video_upload). It stops short of stating when NOT to use it or comparing directly against update_surface/create_workspace, but the per-kind next-step guidance is unusually actionable.

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

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

With no annotations, the description carries the full burden and does so: one-time link, single upload only, accepted formats (mp4/webm/mov/m4v), 100 MB cap, 15-minute expiry, and Editor role requirement. It also discloses the return shape (a ready curl command whose JSON response contains url), which is exactly the behavioral detail an agent needs for a two-step flow.

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

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

Front-loaded with the purpose, then the why-not-alternative, then the mechanics, then the hard constraints. Every sentence earns its place and there is no filler despite the length.

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, but the description explains what is returned (a curl command containing url) and the full downstream hand-off to add_video. Constraints, permissions and file-type limits are all present, leaving nothing material missing for a 3-param tool.

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

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

Schema description coverage is 100%, so slug, filename and content_type are already documented in the schema (including that the extension sets the type unless content_type is passed). The description adds no syntax or format detail beyond that, so the baseline 3 applies.

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

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

States a specific verb+resource ('get a one-time upload link for a video file') and immediately scopes it to local files, distinguishing it from add_video and from the generic create_file_upload/upload_file siblings. The agent can route here without opening a 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?

Explicitly states when to use this instead of the alternative ('add_video needs an https URL, and inline base64 is unreliable for video, so use this instead') and closes the loop by telling the agent to pass the resulting url to add_video. No exclusions are left to inference.

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

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

With no annotations, the description fully discloses important behaviors: URL validation at creation and DNS re-validation at delivery, empty events array semantics, and the one-time return of the signing secret for HMAC verification. These are critical operational details beyond a basic 'create' action.

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

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

The description is three sentences, front-loads the purpose, and packs in essential details (URL constraints, events filter, secret handling) without any fluff. Every sentence earns its place.

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

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

Given the tool's complexity and the absence of an output schema, the description is complete: it covers the return value (secret), the URL validation behavior, events filtering semantics, and hints at the HMAC verification workflow. No obvious gaps remain for an agent to use it correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful context beyond the schema: it explains the events array behavior (empty means none, must pass at least one) and the URL delivery-time DNS validation, which are not in the schema's field descriptions. This raises the score.

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

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

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

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

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

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

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

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

With no annotations the description carries the full burden and discharges it: agent-created workspaces attribute to the agent, enroll the owning user as co-owner, default to org-visibility to avoid 403s for sibling agents, and produce a guided error when neither mode nor initial_markdown is given. Return-format hints (stored doc body length) are also included.

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 action, but the mode guidance is repeated almost verbatim from the schema description and padded across multiple sentences, inflating the definition well beyond what the structured fields don't already convey.

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

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

For a mutation tool with no annotations and no output schema, the description covers actors, visibility defaults, seeding behavior, error handling, and downstream tool routing well. Minor gaps remain on things like permissions or how the created workspace id is returned, but the agent has enough to call 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% and the schema already documents all four parameters in detail, so the baseline of 3 applies. The description largely restates the schema's mode and initial_markdown semantics rather than adding new syntax or 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?

States a specific verb and resource ('Create a new workspace in the caller's org') with the surface-seeding scope made explicit. An agent can distinguish it from create_surface and update_workspace without opening the 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 selection rules for doc/table/html based on the content you're about to write, names the alternative (create_surface) for adding surfaces later, and states when to pass initial_markdown vs. mode. The 'when not' for html (never inferred) is also spelled out.

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 behavioral burden and does so thoroughly: it discloses the 30-day soft-delete, immediate link invalidation, restoration path, permanent deletion after 30 days, storage quota refund, atomic failure behavior, retry guidance, and required editor role.

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

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

The description is front-loaded with the core action and then adds only high-value behavioral details. Despite being longer than a one-liner, every sentence contributes useful context for a destructive operation with no annotations.

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

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

Given a simple two-parameter delete tool with no annotations and no output schema, the description is complete: it covers destructiveness, reversibility, permission requirements, failure semantics, and restoration. No critical agent-facing information 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 description coverage is 100%, so the schema already documents both slug and file_id thoroughly. The description adds only 'by id,' which is redundant with the schema, so the baseline score of 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Delete a file by id.' The resource 'file' clearly distinguishes it from sibling delete tools such as delete_row, delete_surface, delete_webhook, and delete_workspace.

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

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

Usage is implied by the purpose and the stated prerequisite ('Editor role required'), plus the retry guidance on failure. However, the description does not explicitly say when to choose this tool over alternatives such as revoke_file_share or remove_video, nor does it state clear when-not conditions.

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, the description carries the full burden and does so thoroughly: it discloses soft-delete semantics (rows + doc body preserved), idempotency behavior with the exact return value (archivedAt unchanged), a hard failure constraint, the required authorization level, and the emitted `surface.archived` event. This is well beyond a bare verb restatement.

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

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

Five tight sentences, each carrying a distinct and necessary fact — semantics, restoration path, idempotency, precondition, authorization, event. The soft-delete clarification is front-loaded and there is no filler.

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

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

For a two-parameter mutation with no output schema and no annotations, the description supplies everything needed: what is affected, what is preserved, how to reverse it, the failure condition, the auth requirement, and the side effect. Nothing an agent needs 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 description coverage is 100% and both parameters (workspace slug with org-prefixed form, surface_slug) are fully documented in the schema itself. The description adds no parameter-level detail beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource ('Archive a surface') and immediately clarifies the operation's nature as a soft-delete, which distinguishes it from destructive siblings like delete_row or delete_workspace. An agent can tell exactly what this does without opening the 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?

Explicitly routes to alternatives: use `update_surface` with `archived: false` to restore, and `list_surfaces archived: true` to find archived surfaces. It also states preconditions (cannot archive the only live surface; create another first) and the required Editor role, leaving nothing to inference.

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

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

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 burden and does so: it discloses what is preserved (rows, doc body, activity history), that the action is reversible via the Archived filter, that members lose access immediately, that it is idempotent with a defined return on repeat calls, the permission prerequisite, and the full approval handshake.

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 core action and its soft-delete guarantee are front-loaded in the first sentence, and every subsequent sentence adds operational information. It is dense and somewhat long, but 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?

No output schema exists, so the description must explain returns, and it does for the approval path while also covering reversibility, permissions, and idempotency. Nothing material is missing for correct invocation.

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

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

Schema coverage is 100%, so baseline is 3. The description adds real value beyond the schema by specifying the exact shape of the mode:'web' response ({ status, approval_url, polling_url }) and the poll-for-result workflow, which the schema's short enum wording does not convey.

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 ('Archive a workspace') and immediately clarifies that the operation named 'delete' is actually a soft-delete. This disambiguates it from true-destructive siblings like delete_row, delete_file, and delete_surface.

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 conditional guidance: use mode:'web' for non-trivial workspaces, omit it to execute immediately, and the caller must hold the owner role. It does not name a sibling alternative (e.g., update_workspace for rename-only changes), so it falls short of the 5 mark.

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 so: consent-gating, non-destructive scheduling semantics (caps retained until period end), no-op behavior, 60s token TTL, two distinct return shapes, and the Dock-agent override where mode/confirm_token are ignored. This is materially more than the schema provides.

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?

Long, but front-loaded with the most important warning and organized into numbered consent surfaces, so density is justified by the two-step protocol. Slightly heavy for a two-parameter tool, but nearly every clause carries operational 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?

No output schema exists, yet the description spells out both possible first-call response shapes (confirmation_required with confirm_token, approval_required with approval_url/polling_url) and the completion path, leaving nothing an agent needs unknown before calling.

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; however the description adds real meaning by explaining the interaction between `mode` and `confirm_token` (first call omits token and receives one, second call includes it within 60s) and that both are ignored for Dock agents — semantics the schema alone does not convey.

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: schedules the caller's org to drop from a retired org plan (Pro/Scale) to Free at end of the current billing period. Immediately scopes what it does NOT touch (Dock pricing, per-person plans, credits), which lets an agent distinguish it from siblings like upgrade_plan or get_billing.

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 covers when it applies (Pro/Scale org), when it is a no-op (already Free), and the two alternative invocation paths selected by `mode`, including the exact first-call/second-call sequence for chat mode and the click-then-poll sequence for web mode. The Dock-agent special case is also called out.

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?

With no annotations, the description carries the full burden and does substantial work: it warns that price-shaped fields are retired plans that must never be quoted, that org caps are not the human's plan or trial, that caps are live and enforced, and it prescribes how to describe plans (price/agents/storage; allowances, resets, percentages) instead of token counts or usage multiples. That is unusually rich behavioral framing; the gap is that it never characterizes the shape or freshness of the response beyond naming a few fields, which matters for a tool with no output 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 critical point (the access date) is front-loaded, which is good, but the body is a dense 'plus… plus… plus' chain with nested parentheticals that is hard to scan. It also restates the org-caps-are-not-the-plan distinction and revisits the retired-price warning, so some sentences do not fully earn their place.

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

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

Given no annotations, no output schema, and no parameters, the description must supply both content and caution, and it does: it names the key response fields, explains what each set of numbers means, and blocks the main misuse (quoting stale prices or token counts). It stops short of a 5 because an agent still lacks a clear picture of the response structure and how usage is expressed numerically.

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 takes zero parameters, so per the baseline rule this sits at 4. There is nothing parameter-level for the description to add or omit.

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 enumerates concretely what the tool returns: the human's access/trial end date, org resource caps and usage (agents, members, workspaces, rows, API calls, webhooks, message bundle), card-on-file and next invoice date. It also explicitly disclaims pricing ('This tool does NOT price anything'), which separates it from the sibling plan-mutation tools. It falls short of a 5 because the enumeration is delivered as a run-on chain rather than a crisp 'returns X, Y, Z' statement.

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 conditional guidance tied to the data ('the ONLY date to quote for that'; 'These caps are live and enforced — use them') and routes price questions away from this tool by naming `currentPlans.tiers` as the authoritative source. However, it never states a trigger for calling it (e.g., 'call when the user asks about limits or their trial'), nor does it name a sibling to use for adjacent questions like capabilities or workspace state.

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, the description carries the full burden and largely meets it: it discloses the token-cap hazard of TipTap JSON on long docs, the empty-doc return shape per format, the 404 on a non-matching surface_slug, and the heading edge cases (missing heading returns existing headings, duplicate heading is refused). It does not touch permissions/sharing requirements for reading a workspace, which is the main remaining gap.

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 action and the format negotiation, and every sentence is information-bearing. It is on the long side and re-states several schema parameter descriptions, which is the only reason it falls short of 5.

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

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

With no annotations and no output schema, the description does the heavy lifting: it explains what each format returns structurally and what an unwritten doc yields. It stops short of describing the full return envelope (e.g. whether title/metadata accompany the body), leaving a small gap for a read tool with no output schema.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds a decision rationale the schema lacks: why markdown is the default (agent-relevant slice 95% of the time, JSON risks blowing the tool-result token cap). Most other parameter prose (enum meanings, heading semantics, surface_slug) is duplicated from the schema, so the gain over structured data is real but modest.

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?

"Read a workspace's doc (TipTap rich-text) body" states a specific verb and resource, and the format enumeration plus the update_doc round-trip note distinguish it cleanly from siblings like get_html, get_row, and update_doc. An agent can identify the tool's job without opening the 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 routing rules per format (markdown as the default for LLM/render consumption, content only when round-tripping into update_doc, text for search/summarisation, all only for the legacy three-in-one shape) and states when to omit vs supply surface_slug, pointing at list_surfaces for enumeration. Exclusions are stated, not inferred.

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 whole burden, and it does disclose real behavior: the URL is a Dock URL rather than a storage URL, it requires the Dock API key on the GET, and access is re-checked on every request. It omits failure behavior (e.g. what happens when the caller lacks access) and any URL expiry/rate-limit detail, so not 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?

Two sentences, purpose front-loaded, no filler. The second sentence is clause-dense (URL type, auth, access re-check, two use cases) but every clause carries 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?

No output schema exists, so the description must convey the return shape, and it names the key field (download_url) and how to consume it. It leaves error/edge behavior unexplained, which is a modest gap for a small two-parameter read tool.

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

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

Schema coverage is 100%, so the schema already explains both slug and file_id, including the derived surface/workspace behavior. The description adds no parameter-level meaning beyond that, which is the expected baseline when the schema does the work.

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 (Fetch), a specific resource (metadata + download URL), and a precise scope (a single file by id), which cleanly separates it from the list_files / list_recent_files siblings. An agent knows exactly what it gets without opening anything.

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 frames the use case: reading file contents server-side via HTTP GET, or surfacing a download link in a reply. It gives no when-not guidance or named alternative (e.g. list_files for discovery, share_file for access grants), so it stops short of a 5.

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

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

With no annotations provided, the description carries the full burden and does so: it discloses the viewer-role permission requirement, the 404 behavior for unmatched slugs, the exact empty-surface return value, and the sandboxed rendering context. These are exactly the traits 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?

Front-loaded with the action, then context, then selection rules, then error/permission details — a sensible ordering. Five sentences with little waste, though the surface-kind framing is slightly verbose given it repeats what surface_slug's schema description already implies.

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 usefully describes the return shape ({html, css, js}) and the empty case, plus auth and 404 conditions. It does not address what happens if the slug points to a non-html surface kind, a minor remaining gap.

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 would be 3, but the description adds meaning beyond the schema for surface_slug by spelling out the default-to-primary behavior and the empty-result case. The workspace `slug` parameter is left to the schema, so it is not a full 5.

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 ('Read an HTML surface's body') and immediately characterizes what an HTML surface is (three text fields rendered in a sandboxed iframe). This clearly distinguishes it from siblings like update_html, create_surface, and list_surfaces.

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

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

Explicitly routes enumeration to list_surfaces, explains the omit-vs-pass semantics of surface_slug, and names the concrete use case (confirm a surface shows the intended content before sharing its link). No inference required.

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

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

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?

No annotations are provided, so the description carries the full behavioral burden. 'Get' implies a safe read, and it does disclose the returned fields, but it says nothing about permissions, auth, or whether slug lookups can fail — a notable gap for a tool with zero annotation coverage.

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

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

Two sentences, zero waste, and front-loaded with the purpose before the follow-up navigation hint. Efficient and well-ordered.

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

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

With no output schema, the description compensates by enumerating the returned fields and pointing to the follow-up tools for reading surfaces. It is largely sufficient, though a brief note on failure modes or permissions would complete 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?

Schema description coverage is 100%, so the schema already documents the single 'slug' parameter, including the bare vs org-prefixed format. The description adds no syntax or format detail beyond 'by its slug', so the baseline 3 applies.

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

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

States a specific verb and resource ('Get details about a specific workspace by its slug') and enumerates what is returned (primary table surface columns, member count, row count). It does not explicitly differentiate itself from siblings like get_workspace_schema or list_workspaces, so it falls 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?

It provides navigation guidance ('Use list_surfaces to enumerate every surface, then that surface's own tools'), which is helpful context. However, it never states when to prefer get_workspace over get_workspace_schema, list_workspaces, or list_workspace_members, so the when-to-use condition is only implied.

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

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

No annotations are provided, so the description carries the full burden. It discloses return shape (column fields and types), edge-case behavior on doc-only workspaces (empty array), auto-seeding on first write, and multi-surface scoping. It does not discuss auth or rate limits, but the behavioral profile is otherwise well covered.

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

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

The description is front-loaded with the core purpose, then efficiently covers column fields, edge cases, and surface scoping. Every sentence earns its place and the type enum listing is necessary reference detail rather than filler.

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

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

With no output schema, the description must explain return values, and it does so thoroughly: column keys, labels, types, positions, and allowed options for status/select columns. Combined with edge-case and scoping guidance, an agent has everything needed to call and interpret 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?

Schema coverage is 100%, so the schema already documents both parameters. The description adds useful semantic context for surface_slug: scoping to a table sheet, using list_surfaces to enumerate, and omitting it to fall through to the primary surface. It adds value beyond the schema 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?

States a specific verb (Return) and resource (table surface's column definitions), and explicitly ties the purpose to letting an agent know what keys create_row/update_row accept. This distinguishes it from sibling discovery tools like list_surfaces and get_row.

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

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

Explicitly frames the tool as schema discovery ahead of create_row/update_row, names list_surfaces as the alternative for enumerating surface_slug, and clarifies the omit-surface_slug fallback to the primary table surface. This gives clear when-to-use and alternative guidance.

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

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

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?

No annotations are provided, so the description carries the burden and does disclose real behavioral traits: a 200-comment cap per call, ordering by createdAt asc, surfaceSlug denormalization for reply paths, and the default status of open. It does not mention auth/permission requirements or how offset/limit interact with the cap, which keeps it out of 5 territory.

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?

One dense paragraph that is front-loaded with purpose and the sibling route at the end. Every clause carries filter semantics, though the packing of six filters plus return behavior into a single block makes it slightly harder to scan than a short bulleted or sentence-segmented form.

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

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

With no output schema, the description compensates by stating the result cap, sort order, and the denormalized surfaceSlug field — enough for an agent to reason about the response. Pagination mechanics (offset) are only covered by the schema, leaving a minor gap for a 9-parameter list tool.

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

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

Schema description coverage is 100%, so the schema already documents all nine parameters with equivalent detail. The description largely restates the enum values and defaults rather than adding syntax or semantics the schema lacks. Baseline 3 is appropriate when structured fields do the heavy lifting.

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

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

Opens with a specific verb+resource ("List comments in a workspace") and immediately scopes the tool with the full filter vocabulary. It explicitly differentiates itself from the sibling get_comment_thread, so an agent can route between the two 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?

Names the alternative tool (get_comment_thread) and the condition that selects it ("to pull a single comment plus its replies + reactions"), and gives concrete use cases per filter ("open threads on this surface", "comments by Argus on this workspace"). It stops short of explicit when-not-to-use guidance beyond the single alternative, so it falls just short of a 5.

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

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

With no annotations, the description carries the full burden and does: 'It only reads: it connects nothing, shows no card and grants nothing' rules out side effects, and 'it never dumps the whole catalogue' discloses an important negative behavior. It also pre-explains the return contract (offered/matches and per-result connected, connected_not_shared, not_connected) so the agent knows what it will get back and how to phrase results.

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

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

Purpose and the key read-only guarantee are front-loaded, and virtually every sentence adds actionable information. It runs long and packs in routing detail for request_connection / create_owner_link that partly belongs to those tools, which costs it a point, but there is no filler or repetition.

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

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

There is no output schema, so the description must explain return values — and it does precisely: offered/matches semantics, the three connection states per result, and the degenerate no-query response. Combined with the when-to-use routing, an agent has everything needed to call this correctly and interpret the answer.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns above that by explaining what query actually does semantically — it accepts a name, a misspelling, or a topic word ('crm'), and determines whether offered is true via exact name/slug match, with close matches surfaced under matches. It also documents the no-query default behavior (owner's connected apps plus total count), which the schema cannot express. The limit parameter is left 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: 'Look up which third-party apps Dock can connect', then enumerates examples (Gmail, Slack, Notion, HubSpot, Granola) and what is returned (name + short description). Nothing in the sibling list overlaps with this catalogue-lookup role, so the tool is unambiguous on its own.

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 positive triggers ('BEFORE telling anyone that Dock does or does not have an app', "do you have X?", 'what can I connect for CRM?') and explicit routing to alternatives: request_connection for in-chat cards, create_owner_link with kind connect_app for iMessage/text. It even covers the follow-up branch when already_connected or connected_not_shared comes back.

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

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

No annotations are provided, so the description carries the burden, and it does disclose real behavior: deterministic ordering (folders by position then name, files by name) and the return shape (folders[], files[] containing cuids usable with get_file/delete_file). It omits pagination, size limits and permission/auth requirements, which keeps it short of a 5 for an unannotated 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?

Three sentences, front-loaded with purpose, then return shape, then the one non-obvious parameter behavior. No filler, and each sentence carries information an agent needs.

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 3-parameter read tool with no output schema and no annotations, the description supplies both the return structure and the root-vs-subfolder semantics an agent needs to call it correctly. Missing only peripheral items such as pagination and auth expectations.

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, including the org-prefixed slug form and the null-means-root default. The description largely restates the parent_folder_id default rather than adding new syntax or format detail, so the baseline 3 applies.

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

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

States a specific verb and resource ('List the folder + file children of a Files surface') and scopes it with kind='files', which separates it from list_recent_files, list_surfaces and the get_file/delete_file siblings it names. An agent can tell what this returns and what it does not without opening the 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 invocation context: parent_folder_id defaults to null meaning surface root, pass a folder id to descend, and use list_surfaces to enumerate surfaces. It stops short of an explicit 'use this instead of list_recent_files when...' exclusion, so it is clear context rather than full routing guidance.

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

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

With no annotations provided, the description carries 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 carries the full burden and does disclose key traits: a hard cap of 50 results, descending updatedAt ordering, surface-wide scope, and that folders are excluded. It omits auth/permission requirements and whether any pagination or cursor exists beyond the implicit 50-item ceiling.

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 (what is listed, how many, in what order) before the use-case framing. Mild redundancy remains: 'ignores folder structure' and 'Folders are omitted from this view' say the same thing twice.

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?

There is no output schema or annotation block, so the description must stand alone for a two-parameter read tool. It covers scope, limit, ordering, and exclusions adequately, but leaves the return shape (which file fields appear) and any truncation/pagination semantics unstated.

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 slug and surface_slug are already fully documented in the schema. The description references the 'Files surface' concept, loosely tying to surface_slug, but adds no syntax, format, or disambiguation between the two identifiers. 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 and resource ('List the 50 most recently updated files in a Files surface') plus scope and ordering ('sorted by updatedAt descending'). The flat-vs-folder-tree distinction functionally separates it from list_files, so an agent can tell the two apart 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?

Gives concrete trigger scenarios ('what changed lately', 'show me yesterday's uploads') and implies the alternative path ('without paging through the folder tree'). It never names list_files as the contrasting tool or states an explicit when-not-to-use, so it falls short of a 5.

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

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

With no annotations, the description 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?

With no annotations, the description carries the full burden and does well: it discloses return ordering (matches on-screen order), the default filtering (archived hidden), and a key side effect (surface slugs feed surface-scoped calls). It omits auth/permission needs and any pagination or size limits, which keeps it from 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?

Front-loaded with the core purpose and organized logically (scope, slugs, ordering, filtering). Some redundancy ('in any combination, one or many of each; this tool tells you exactly what it has') adds words without new meaning.

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-param read tool with no output schema, the description conveys scope, ordering, and default filtering sufficiently to call it correctly. It could say more about the return shape (surface fields) and behavior on empty/missing workspaces, but the essentials are present.

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

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

Schema coverage is 100%, so both parameters are fully documented in the schema, including the org-prefixed vs bare slug form and the archived default. The description mostly restates the archived behavior rather than adding format or syntax detail beyond the schema, so the baseline 3 applies.

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

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

States a clear verb+resource ('List the surfaces inside a workspace') and defines scope and relationship to create_surface. However, it never contrasts itself against sibling list tools (e.g., list_workspaces) that an agent might confuse it with.

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: use this to enumerate surfaces in a workspace, and pass archived:true to see hidden ones. There is no explicit when-to-use-when-not guidance or named alternative beyond the create_surface cross-reference for surface kinds.

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?

With no annotations, the description carries the full burden and does well: it discloses conditional email visibility (same-org only), the privacy_warning present in results for non-owner-private workspaces, and an explicit boundary on what is not observable. It stops short of describing auth requirements or rate limits, but the disclosure of conditional output behavior is substantial.

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 purpose, then returns, then use case, then exclusions — a logical order with no filler sentences. The parenthetical asides are information-dense rather than wasteful, though the middle section is heavy enough to slow scanning slightly.

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?

There is no output schema, so the description must explain the return shape, and it does: enumerated fields for users and agents, the role enum, and the conditional privacy_warning. For a single-required-param read tool, an agent has everything needed to call it and interpret the result.

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 slug description already documents both accepted forms (bare and org-prefixed). The prose adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('List principals with explicit access to a workspace') and immediately enumerates the exact entity types and role enum returned. It is clearly distinguishable from list_workspaces, get_workspace, and check_workspace_private 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 an explicit use case ('verify a workspace is actually shared before writing output the team is expected to see'), states a concrete limitation (does not show private-to-owner status, agent ownership, open invites, or file share links), and names the sibling to use instead: check_workspace_private. When-to-use, when-not-to-use, and the alternative are all covered.

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

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

With no annotations at all, the description carries the full burden: it discloses the access-scope behavior (only workspaces the principal can reach) and enumerates the returned fields, which is meaningful since no output schema exists. It omits ordering, pagination, and the empty-result case, which keeps it short of 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?

Three sentences, front-loaded with the core action and scoping, then return fields, then the clarifying definition and next step. The parenthetical about 'mode' and the 'any combination, one or many of each' clause are slightly more verbose than strictly needed but still earn their place by preventing misuse.

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 zero parameters, no annotations, and no output schema, the description supplies the missing context itself: what is listed, what each item contains, what a workspace is, and where to look next. Pagination/ordering behavior is the remaining gap.

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 takes zero parameters, so there are no parameter semantics to explain and the baseline is 4. The description correctly makes no attempt to describe inputs.

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?

Specific verb+resource (list all workspaces) with the exact scoping qualifier: 'the authenticated principal has access to.' It also distinguishes itself from list_surfaces by defining a workspace as a container of surfaces, so an agent can separate the two 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?

Explicitly routes to list_surfaces for inspecting workspace contents, which is a real alternative an agent could confuse with this tool. It does not, however, contrast with flat siblings like get_workspace or list_workspace_members, so the when-not guidance is only partial.

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 discharges it well: all-or-nothing semantics, failure-before-write ordering, idempotency with a `skipped` count, destination ordering, the emitted `row.moved_surface` event, and the 500-row cap. It omits permission/auth requirements and any rate-limit guidance, which keeps it from 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?

The core action is front-loaded in the first sentence, followed by use cases and then guarantees (atomicity, idempotency, ordering, events, limit). Every sentence carries distinct 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?

With no output schema, the description compensates by noting the `skipped` return count and the per-row event. For a batch mutation tool this is nearly complete, though it stops short of spelling out the success return shape or required permissions.

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

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

Schema description coverage is 100%, so slug, rowIds, and target_surface_slug are already documented (including both slug forms and the 400 on invalid surfaces), establishing a baseline of 3. The description adds only the atomicity condition tied to rowId workspace membership, which is marginal beyond what the schema conveys.

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 ('move N rows from their current sheet(s) to a target sheet') with the workspace scope made explicit. Combined with the migration/reorganization use cases, an agent can tell this apart from update_row or bulk_update_rows, which modify rows in place rather than relocating them.

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 concrete usage context ('programmatic data migration', 'dropping a batch of agent-produced drafts', 'reorganizing content across LinkedIn / Twitter / Substack sheets'). It stops short of naming alternatives or when-not-to-use cases (e.g., versus bulk_update_rows or update_surface), so it is clear context without exclusions.

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

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

No annotations 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 carries the full burden and does so: permission requirements, a non-obvious consequence in org-visibility workspaces (removal leaves virtual editor access via org membership), the sole-owner block, and the exact confirmation-required response shape with a 60s single-use token. It also states that cookie-session callers skip consent entirely.

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 action and the invite-revocation scope, then permissions, then the consent protocol. It is dense and every sentence carries information, though the consent paragraph is long enough to be slightly sprawling.

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, unannotated mutation with no output schema, the description covers permissions, the key edge case, and the confirmation handshake. It does not say what happens to resources the removed member owned, or whether removal can be undone by re-inviting, which would round out the picture.

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 schema already documents slug forms, member_id (including the invite-id case) and confirm_token semantics. The description reinforces the confirm_token workflow but adds little parameter detail the schema does not already contain, so the baseline 3 applies.

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

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

States a specific verb and resource plus the dual scope: removing a member or revoking a pending invite via the same call. It is clearly separable from update_workspace_member, list_workspace_members and share_workspace, which appear as 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?

Explicit conditions are given: Editor role for ordinary removals, owner caller for owner-tier removals, and sole-owner removal is blocked with the remedy (promote someone else first). The agent-vs-user-caller split and the two-call consent path are spelled out as the required procedure.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It proactively discloses that the handler reconstructs the target from the parent, that a resolved parent is re-opened, and that nested replies flatten to single depth causing reply-to-reply to re-point to the root. These are non-obvious behaviors well beyond what the schema conveys.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

With no annotations, the description carries the full burden and does so: it discloses that the tool connects nothing, that the response carries state flags plus an ask_with_marker string the agent must post on its own line to trigger an Approve card, the 30-day refusal cooldown after a decline, and that declines show no card. These are exactly the non-obvious behaviors an agent would otherwise get wrong.

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?

Dense and front-loaded: purpose, then when to call, then the two states, then the API-key prohibition, with caps and markers segmenting the flow. It is a single long block rather than broken into distinct sections, and the state-handling detail could be tightened, but essentially every sentence carries non-redundant guidance.

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

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

No output schema exists, yet the description names the key response fields (connection_required, already_connected, you_have_access, ask_with_marker) and what to do with each, which is precisely the missing coverage. For a 4-parameter tool with no annotations, nothing an agent needs to call or act on the result 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?

Schema coverage is 100%, so the baseline is 3; the description still adds operational meaning by tying owner_declined to the real-world event ('if your owner says no to an app, call it once') and its 30-day consequence, and by mapping owner_requested to the lift-a-no condition. The reason and toolkit_slug semantics are left to the already-thorough schema descriptions.

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

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

States a specific verb and resource ('Ask your owner to connect a third-party app') and immediately clarifies the negative scope ('does NOT connect anything and does NOT give you access — it reports the state'). The two-state model (connection_required vs already_connected) plus the explicit contrast with vaulted API keys distinguishes it cleanly from siblings like pull_capability and list_api_keys.

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 trigger conditions ('Call it when a task needs an app you cannot currently reach'), explicit anti-patterns ('Do not call it repeatedly for the same app in one conversation'), routing rules for the two response states, and a hard prohibition ('⛔ In neither case ask for that app's API key instead'). Timing rules for owner_declined ('call it once, as soon as they say no') and owner_requested ('Never set it on your own initiative') are spelled out.

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

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

With no annotations, the description carries the burden and delivers a genuinely important trait: 'We record the signal on the admin side; there's no reply loop,' telling the agent this is fire-and-forget with no response to wait for. It does not cover auth requirements, whether the request is acted on or applied immediately, or any rate limits, which keeps it from 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 tight sentences with zero waste: purpose is front-loaded, then the no-reply-loop behavior, then the usage trigger, then the important plan-retirement caveat. 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 simple 3-parameter tool with full schema coverage and no output schema, the description supplies purpose, triggering condition, the asynchronous behavior, and a critical business caveat. Nothing an agent needs in order 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 description coverage is 100%, so the schema already documents kind, reason, and desiredValue including the enum. The description's parenthetical merely restates the enum values already present in the schema, adding no new syntax or format detail. 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 first sentence gives a specific verb ('raise') and resource ('an org limit') and enumerates the scope (agents, workspaces, rows, or other). It is clear what the tool does, though it never explicitly contrasts itself with other request-style siblings such as create_support_ticket.

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?

'Use this whenever you hit one of those caps' gives a clear triggering condition, and the retirement warning steers the agent away from offering Pro/Scale plans as an alternative fix. It stops short of naming a specific sibling tool to use instead, so it's strong context without full 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?

No annotations exist, so the description carries the full burden and does: it discloses the return payload shape, the mandatory approval gate ('the approving user must be the target agent's owner, Agent.ownerUserId match'), the required post-call actions (print approval_url, poll polling_url), and expiry. This is rich behavioral context beyond what any structured field provides.

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-loads purpose and sibling distinction, then the return/approval mechanics, then the usage triggers. Dense but every sentence carries new information with no filler.

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

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

Despite no output schema, the description explains the return fields and the required follow-up (print URL, poll for result), plus the authorization gate on the target owner. Nothing an agent needs to call this 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 both parameters are already documented there, including the 'surfaces verbatim on the consent card' note. The description only reinforces the reason guidance ('why the human knows what they're saying yes to') without adding new syntax or constraints, so the baseline 3 applies.

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

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

States a specific verb (revoke) plus resource (ANOTHER agent's active API key) and explicitly distinguishes itself from the self-only `revoke_api_key`, calling itself the 'cross-agent escalation path'. An agent can select it 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 concrete when-to-use triggers (credential leakage, misbehaviour, a stuck sibling needing a clean kill) and names the alternative `revoke_api_key` it is not. The escalation condition is stated, not inferred.

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 behavioral burden and does so richly: returns an approval_url, requires the target owner's click, old key dies immediately on approval, new plaintext is deliberately withheld and delivered out-of-band, and the target agent is expected to go offline until handoff.

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

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

Five sentences, each carrying distinct information, with the core action and its cross-agent scope front-loaded before the approval mechanics and the warning about the withheld plaintext.

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, yet the description explains the return value (approval_url), the async approval flow, and the downstream consequence for the target agent. An agent has everything needed to decide and invoke correctly.

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

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

Schema description coverage is 100%, so both parameters are already documented; the description adds no format, length, or selection guidance for target_agent_id or reason beyond the schema. Baseline 3 applies.

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

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

States a specific verb (rotate), the exact resource (another agent's active API key), and the concrete effect (mint new + revoke old). The 'ANOTHER agent's' qualifier cleanly separates it from the sibling rotate_api_key, which operates on the caller's own 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?

Gives a clear trigger ('Use when you've spotted leakage') and points to request_revoke_agent_key as the same-shaped alternative. It never explicitly names the when-not case (self-key rotation via rotate_api_key), though 'ANOTHER agent's' strongly implies 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?

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.