Dock

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

With no annotations, the description covers key behaviors: auto-computed position, contiguity invariant, error on key collision, and required editor role. No contradictions.

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

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

Three sentences covering purpose, behavior, and usage guidance. No unnecessary words, 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 no output schema and moderate complexity, the description provides purpose, behavior, error conditions, authorization, and alternatives. Complete for agent usage.

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

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

Schema coverage is 100%, so baseline is 3. Description barely adds beyond schema for parameters; it mentions position auto-computation but that's not a parameter. Adequate but not improved.

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

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

Clearly states the tool appends a column to a workspace table schema and distinguishes itself from sibling tools like get_workspace_schema + update_workspace_columns for full schema replacement.

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 to use for per-column additions, not for full schema replacement, and mentions alternative tools. Also specifies that 'Editor role required' and key collision results in 409.

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

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

No annotations provided, so description carries full burden. It discloses non-idempotency, required editor role, optional surface_slug, same auth/events/guards as update_doc, and the fetch-splice-write mechanism. Lacks mention of error conditions or limits.

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

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

The description is thorough but lengthy (8 sentences). It front-loads the core purpose but includes extensive markdown support details that could be condensed. Still, the structure is logical.

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

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

Given no output schema, the description adequately covers return behavior (server fetches, splices, writes). It explains the append semantics, dedupe responsibility, and role requirements. Missing details on potential failure modes or performance.

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

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

Schema coverage is 100%, but description adds context: slug accepts bare or org-prefixed forms, markdown supports specific extensions (CommonMark, GFM, diagrams, callouts, etc.), and surface_slug is optional for multi-doc workspaces. This meaningfully enriches the schema.

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

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

The description clearly states the tool appends markdown to the end of a doc body, with specific verb 'Append' and resource 'workspace doc'. It distinguishes from update_doc by emphasizing append behavior and non-idempotency.

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 targets crons and ingest agents producing timestamped chunks, and notes the caller is responsible for dedupe. It implies using update_doc for full replacements but does not explicitly 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 discloses key behaviors: data format as JSON, valid status column values, auto-seeding on empty table, surface_slug behavior including error case. Does not mention return value or rate limits, but covers essential traits.

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

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

Four well-structured sentences totaling about 100 words. Front-loaded with purpose, then details on data, status, auto-seed, and surface_slug. No redundant or irrelevant content.

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

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

Given 3 parameters, no output schema, and no annotations, the description covers data format, special values, edge cases (empty table, multi-surface), and error conditions. Lacks return format description but is otherwise thorough.

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

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

Schema coverage is 100%, but description adds value by explaining the data field is JSON with column-name keys, acceptable status values, auto-seed behavior, and surface_slug targeting. Goes beyond technical schema descriptions.

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

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

The description clearly states the verb 'append' and resource 'new row to a workspace's table surface.' It distinguishes from siblings like update_row, delete_row, and move_rows by specifying it creates a new row.

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

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

Provides guidance on when to use surface_slug (multi-surface workspaces) and how to enumerate surfaces with list_surfaces. Implicitly indicates that for single-surface workspaces, surface_slug can be omitted. Does not explicitly contrast with other row operations, but the context is clear.

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

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

No annotations provided, so description carries full burden. It mentions mirroring to GitHub issue and dashboard visibility, but omits details like authentication, rate limits, or side effects. Adequate for a creation tool but could be more explicit.

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

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

Three sentences front-loading purpose and consequences, with no redundant information. 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?

Lacks output schema; description does not explain return value or error cases. Also, the nested 'context' parameter structure is not elaborated. With 5 parameters and a sibling set of 40+, more completeness would be helpful.

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

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

Schema coverage is 100% (baseline 3). Description adds value by providing usage guidance for body (e.g., include what you did for bugs, use case for features) and clarifying attachment URL requirements, going beyond enum labels.

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 'File a support ticket' and enumerates specific use cases (bugs, features, billing, questions, other), distinguishing it from siblings like request_limit_increase.

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 provides when to use (bugs, feature requests, billing, questions) and when not to use ('Prefer request_limit_increase when the user is simply hitting a plan cap'), offering a clear alternative.

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

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

Despite no annotations, the description discloses key behaviors: editor role required, slug collision handling, column override ignored for doc, and emission of 'surface.created' event. This provides sufficient transparency for an agent to understand side effects.

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

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

The description is concise and well-structured, front-loading the primary purpose and then covering details logically. Every sentence adds necessary information without redundancy.

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

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

Given no output schema and no annotations, the description covers all critical aspects: purpose, parameter details, behavioral traits (role, event), and optional customization. It provides sufficient context for an agent to use the tool correctly.

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

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

Input schema has 100% coverage, but the description adds value beyond schema by explaining slug auto-derivation, collision behavior, and column override limitations. This extra context justifies a score above 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 creates a new surface (tab) inside a workspace, and specifies the two possible kinds (table or doc). It distinguishes itself from sibling tools like delete_surface and update_surface by focusing on creation.

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

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

The description implies when to use this tool (to create a new tab with specific kind and optional customization). It provides context about slug auto-generation and column behavior, but lacks explicit guidance on when not to use it or compare it directly to siblings like create_workspace.

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

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

The description discloses URL validation details (private ranges, cloud metadata blocked and DNS re-validated) and that an empty events array means none. It also notes the signing secret is returned once. With no annotations, this provides good behavioral insight but could mention rate limits or activation timing.

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

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

The description is a single well-structured paragraph that front-loads the main purpose. It includes necessary details but is slightly dense; every sentence contributes value.

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

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

Given the tool complexity and lack of output schema, the description covers key aspects: URL validation, event selection, and secret handling. However, it does not detail the full response (e.g., webhook ID) which would improve completeness.

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

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

Schema coverage is 100%, so baseline is 3. The description adds extra meaning for 'url' (validation specifics) and 'events' (empty array means none), improving understanding beyond the schema descriptions.

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

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

The description clearly states 'Register a new webhook endpoint on an org,' providing a specific verb and resource. It distinguishes from siblings like delete_webhook and list_webhooks by focusing on creation.

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

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

The description gives context about when to use (e.g., need public URL, pick events) but does not explicitly state when not to use or provide alternatives. It is clear but lacks exclusions.

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

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

With no annotations, the description carries full burden. It discloses agent vs user behavior, co-owner enrollment, default visibility, seed surface logic, and markdown conversion. Minor omissions like return value format and error conditions prevent 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 description is a single paragraph that efficiently covers all key points without redundancy. It is front-loaded with purpose and flows naturally, though structured bullets could improve scannability.

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

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

Given the complexity (4 params, no output schema, no annotations), the description covers creation behavior well but does not specify the return value (e.g., workspace ID) or error conditions. This omission leaves some uncertainty for the agent.

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

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

Schema coverage is 100%, and the description adds value beyond schema by explaining mode auto-resolution, slug collision handling, and the purpose of initial_markdown as an alternative to hand-built JSON. It elaborates on parameter interactions not captured in schema.

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

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

The description explicitly states 'Create a new workspace in the caller's org.', identifies the resource and action, and distinguishes from siblings like 'create_surface' by noting that mode only picks the first tab and that additional tabs can be added later.

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 advises to use this for creating workspaces and provides specific use cases for prose content with initial_markdown, suggesting it over a create+update_doc workflow. It also mentions default visibility for agent callers. However, it lacks explicit 'when not to use' statements.

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

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

Discloses irreversibility ('cannot be undone') but lacks information on permissions, side effects, or response behavior. Without annotations, description partially informs but is insufficient.

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

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

Two sentences with no redundancy. Efficiently communicates core purpose and key consequence.

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?

Simple tool but no mention of return value, permissions, or when deletion is appropriate. Minimal completeness for a deletion action.

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 both parameters (slug, rowId) with descriptions. Description adds no extra meaning beyond schema, so baseline 3 for 100% 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?

Clearly states the action 'permanently delete' on a specific resource 'row from a workspace.' Distinguishes from siblings like create_row or update_row.

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

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

No guidance on when to use this tool vs alternatives (e.g., move_rows, update_row). Only mentions permanence but no exclusion criteria.

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

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

With no annotations provided, the description fully discloses behavior: soft-delete semantics (preservation for restore), idempotency, the restriction on archiving the last surface, required role, and emitted event. This is comprehensive and leaves no ambiguity.

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

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

The description is highly concise, using 3 sentences to convey all essential information without filler. Key actions and constraints are 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 tool with 2 simple parameters and no output schema, the description covers behavior, constraints, permissions, and events completely. No gaps are evident.

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 100% of parameters with detailed descriptions. The description adds no parameter-level details beyond the schema, but given high schema coverage, a baseline score of 3 is appropriate.

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

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

The description clearly states the action ('Archive a surface (soft-delete)'), the resource ('surface'), and key behavioral details like preservation, idempotency, and constraints. It distinguishes itself from sibling tools like delete_row or delete_workspace by specifying it's a soft-delete for surfaces.

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

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

The description provides clear context for when to use the tool: to archive a surface, with explicit constraints (cannot archive the only live surface, requires editor role). It does not directly mention alternatives or when not to use, but the sibling list implies alternatives like create_surface or update_surface.

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

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

No annotations provided, but description fully discloses permanence, immediate effect, and secret destruction, which are critical behavioral traits.

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

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

Two sentences, front-loaded with main action, no wasted words.

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

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

Covers key behavioral aspects for a simple 2-param tool with no annotations or output schema; minor omission of error conditions but not critical.

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 minimal descriptions; the description adds no additional parameter meaning beyond the schema's brief 'Org slug' and 'Webhook id'.

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 ('Permanently delete a webhook endpoint') and distinguishes from siblings like update_webhook for pausing.

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

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

Explicitly states when to use (permanent deletion) and when not to (for pausing, use update_webhook), plus mention of recreating from scratch.

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

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

No annotations provided, so description carries full burden. Discloses: soft-delete, data preservation, restoration path, immediate access loss, idempotency, editor role requirement, and detailed mode behavior (returning approval_url, polling). Covers all behavioral traits.

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

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

Lengthy but every sentence adds unique information. Front-loaded with main action, then progressively detailed. Minor redundancy could be trimmed, but overall efficient for the complexity.

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

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

No output schema, but description covers return behavior for web mode (status, approval_url, polling_url) and idempotency. Addresses edge cases and provides complete usage context. No gaps.

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

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

Schema coverage is 100% (baseline 3). Description adds value: clarifies slug accepts bare or org-prefixed form, and mode describes consent surface and recommends web for non-trivial workspaces.

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

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

Starts with 'Archive a workspace' — a specific verb and resource. Clearly distinguishes from sibling deletion tools (e.g., delete_row, delete_surface) by targeting workspaces and calling it archiving.

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?

Explains when to use (archiving workspace) and provides context for mode parameter (recommend web for non-trivial). Does not explicitly state when not to use, but the soft-delete and restore capability imply it is not for permanent removal.

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

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

With no annotations provided, the description fully discloses the tool's behavior: it is not immediate, it is consent-gated, requires two calls in chat mode with a 60s timeout, and in web mode requires browser approval and polling. Also notes no-op condition. No contradictions.

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

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

The description is well-structured, starting with the core action, then detailing the two modes. Every sentence provides unique value without unnecessary verbosity. For the complexity of the tool, it is appropriately concise.

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

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

Given the tool has no output schema and involves a two-step consent process, the description fully covers the workflow: scheduling behavior, no-op, consent modes, token management, and polling. It is complete for an agent to invoke correctly.

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

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

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

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

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

The description clearly states it schedules a downgrade to Free at the end of the billing period, distinguishing it from the sibling 'upgrade_plan'. The verb 'schedule' and resource 'downgrade to Free' are specific and unambiguous.

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

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

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

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

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

With no annotations, the description must fully disclose behavior. It states the tool retrieves billing summary (a read operation) but doesn't address potential errors (e.g., no org or billing info) or authentication 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?

Single sentence lists all key information without redundancy. Every phrase earns its place, from verb to field enumeration to usage note.

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 provided, so description must cover return values—it lists expected fields. Missing data types and structure, but sufficient for a simple billing summary tool.

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

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

No parameters exist (schema is empty, coverage 100%). Per guidelines, zero parameters baseline is 4. The description adds value by implying the tool needs no configuration.

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

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

The description clearly states 'Get the caller's org billing summary' and lists specific fields (plan, agent count, price, card, next invoice). This definitively distinguishes it from sibling tools, none of which handle 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?

It notes 'Both humans and agents can call this,' indicating no special access restrictions. However, it lacks explicit guidance on when not to use it or alternative tools for related tasks.

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

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

With no annotations, the description fully discloses the tool's behavior: it returns three content forms, explains the empty state for unwritten docs, and the 404 error for invalid surface_slug. It also notes that content is round-trippable into update_doc, which is a key behavioral trait.

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

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

The description is well-structured and front-loaded with the purpose, but it is somewhat dense with multiple details packed into a single paragraph. Breaking it into smaller sentences or bullet points could improve readability, but it remains clear and concise overall.

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

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

Given the absence of an output schema, the description thoroughly explains all three return formats and their use cases (e.g., structural edits, LLM feeding, search). It also covers edge cases (empty doc, invalid slug). The tool's behavior is fully described for its level of 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?

Although the schema already covers both parameters with descriptions (100% coverage), the description adds significant context: it explains that slug accepts both bare and prefixed forms, and that surface_slug is optional and can be discovered via list_surfaces. This goes beyond the schema's 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 specifies that the tool reads a workspace's doc body, mentions the three return formats (content, markdown, text), and distinguishes it from sibling tools like update_doc by explicitly noting that content is round-trippable. This provides a specific verb+resource with clear differentiation.

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

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

The description offers guidance on when to omit or pass surface_slug, references list_surfaces for enumeration, and explains the behavior for absent docs and invalid slugs. However, it does not explicitly state when not to use this tool (e.g., for editing, use update_doc), though this is implied by the round-trippability comment.

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 lacks details about behavior such as time range for 'recent', sorting order, or whether it's read-only. The description is too vague on behavioral traits.

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

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

The description is two sentences, front-loaded with purpose, and contains no redundant information. Every word 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 listing tool with two parameters and no output schema, the description is largely complete. It explains the return value (who, what, when) and suggests usage, though it could mention sorting or time range.

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

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

Schema coverage is 100%, and the description does not add meaning beyond the schema. The slug parameter details are already in the schema, and the limit parameter default is also specified. Baseline score applies.

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

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

The description clearly states the verb ('Get'), resource ('recent activity events for a workspace'), and provides context ('Who did what, when'), distinguishing it from sibling tools like get_workspace or search.

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

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

The description implies usage context ('Useful for understanding what's happened since you last looked') but does not explicitly state when to use this tool vs alternatives, nor does it provide exclusions or 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 burden. It is transparent about the return shape ('same row shape as list_rows'), but does not disclose error handling (e.g., if rowId is missing or invalid). For a simple fetch, this is acceptable but not exhaustive.

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

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

The description is only two sentences, each serving a purpose: first sentence states the action and differentiates from list_rows, second gives a usage scenario and return shape. No waste, 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 simple fetch tool with high schema coverage, the description is nearly complete. It explains how to use it, what it returns, and when to use it. However, it lacks details on what happens if the row is not found, which could be considered a minor 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 input schema already provides detailed descriptions for both parameters (slug and rowId) with 100% coverage. The description adds no additional semantic information beyond what is in the schema, so it meets the baseline but does not exceed it.

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

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

The description clearly states 'Fetch a single row by id', which is a specific verb+resource. It also distinguishes from the sibling tool list_rows by explicitly saying 'without listing the full table', making its purpose unambiguous.

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

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

The description explicitly says when to use this tool: 'Useful when a cue payload carries a row id and the agent only needs that one record.' This provides clear context and implies when not to use it (when multiples are needed, use list_rows instead).

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

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

No annotations are provided, so the description carries the full burden. It explains the workspace structure (surfaces, kinds) and the returned fields (columns, counts). However, it does not explicitly state that the operation is read-only or idempotent, which would enhance transparency.

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

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

The description is two sentences: the first is a clear statement of purpose, the second provides additional context about workspace composition and sibling tool usage. No unnecessary words; every sentence adds value.

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

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

Given no output schema, the description covers the main return components (columns, counts) and workspace structure. It references sibling tools for further actions. While not an exhaustive field list, it provides sufficient context for a single-parameter tool.

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

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

The schema already describes the 'slug' parameter and its format. The description adds value by explaining the slug accepts both bare and org-prefixed forms, and also outlines the return fields not in the schema (columns, member count, row count). This goes beyond the baseline for 100% 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 'Get details about a specific workspace by its slug, including columns of its primary table surface, member count, and row count.' This specifies the verb, resource, and output, distinguishing it from siblings like list_workspaces and get_workspace_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 mentions when to use alternative tools: 'Use `list_surfaces` to enumerate every tab; fetch /rows or /doc to read or write a specific one.' This provides clear context for when this tool is appropriate versus others.

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

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

With no annotations, the description fully covers return shape (keys, label, type, position, options) and special behavior for doc-only workspaces, ensuring no surprises.

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 front-loaded with purpose, followed by detail and edge case. No filler, 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?

Despite no output schema, the description explains return structure and handles edge cases, making it complete for a single-parameter retrieval tool.

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

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

Schema coverage is 100%, baseline 3. The description adds value by detailing valid slug formats (bare or org-prefixed), improving parameter understanding beyond the schema.

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

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

The description clearly states the tool returns workspace column definitions for agent use with create_row/update_row, distinguishing it from sibling tools like get_workspace.

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

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

Provides clear context for when to use (to know accepted keys) and handles edge cases (doc-only workspaces), but does not explicitly list when not to use or name alternative tools.

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

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

With no annotations, the description effectively discloses key behavioral traits: caller-dependent visibility, no plaintext returned, and the limited scope of results. However, it omits potential side effects or rate limits, which would elevate it to 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 description is concise with three sentences, each adding value. It front-loads the core purpose, though could be slightly more terse.

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 and no output schema, the description adequately covers behavior and response differences for caller types. It lacks pagination details but is otherwise complete.

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

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

No parameters exist, so baseline is 4. Description correctly adds no parameter info as none are 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 'List API keys' and provides specific behaviors for agent vs. user callers, distinguishing it from other key-related tools like revoke or rotate.

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 lacks explicit guidance on when to use this tool versus alternatives such as revoke_api_key or rotate_api_key, leaving the agent to infer based on name alone.

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

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

With no annotations, the description fully discloses behavior: it returns rows with specific fields, empty array for no data, and the effect of surface_slug (filter to one surface vs. all). It also notes a 400 error for invalid surface_slug. This is comprehensive for a read-only list tool.

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

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

The description is concise and well-structured: it starts with the main purpose, then details return values, edge cases, and usage of the key parameter. Every sentence adds necessary information without redundancy.

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

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

Given no output schema, the description adequately explains what is returned. It covers the four parameters and their behaviors. A minor gap is the lack of explicit mention of pagination limits (default 100, max 1000) which are in schema but not re-emphasized, but overall 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?

All four parameters have schema descriptions (100% coverage), so the description does not need to compensate. However, it adds meaningful context for surface_slug (scoping vs. back-compat) and slug (accepted formats), improving the agent's understanding beyond the schema.

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

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

The description explicitly states the tool lists rows in a workspace's table surface, detailing the returned fields (data, creation time, principals, surface_slug) and behavior (empty array if no rows). This clearly differentiates from sibling tools like get_row (single row) or create_row (write).

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

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

The description gives clear context on when to pass surface_slug (for multi-surface workspaces to scope to one sheet) and when to omit (for legacy compatibility). It does not explicitly say when not to use this tool versus alternatives, but the purpose is well-defined.

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

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

Discloses key behaviors: returns both table and doc surfaces, order matches tab strip, archived hidden by default. No annotations provided, but description covers needed transparency for a read 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 efficient sentences with front-loaded purpose. No wasted words; each sentence adds distinct 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?

Lacks details on exact output fields (e.g., id, type, title) and error scenarios, but for a list tool it covers primary usage and behaviors adequately given no output schema.

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

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

Schema coverage is 100%, baseline 3. Description adds value by explaining archived default and slug meaning not repeated. The slug parameter is already well described in schema.

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

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

Clearly states the tool lists 'surfaces (tabs) inside a workspace'. Explains the two types (table, doc) and ties to slug usage. Distinct from sibling tools like create_surface or list_workspaces.

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

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

Provides clear context: surfaces listing with ordering, archived hidden by default. Implicitly indicates when to use, but lacks explicit when-not-to-use or alternatives.

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

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

With no annotations, the description carries full burden. It reveals the read-only nature, return fields, secret preview behavior (full secret only at create/rotate), and access permissions. No mention of rate limits or pagination, but acceptable for a simple list.

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

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

Two concise sentences with no fluff. Every sentence adds value: first states the action and return fields, second provides usage context and access info.

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

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

Given one parameter, no output schema, but description lists return fields. It covers the essential behavior and usage context. Minor omission of pagination or ordering details, but not critical for this 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% for the single param org_slug. The description does not add additional meaning beyond the schema's own description, which already covers the scoping. Baseline score 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 it lists webhook endpoints registered on an org, specifies the returned fields (id, url, subscribed events, active flag, secretPreview), and distinguishes from sibling mutation tools like create_webhook and delete_webhook.

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

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

Provides explicit guidance: 'Use to audit what's subscribed before adding or removing endpoints.' Also states that any org member can list. Does not explicitly mention alternatives or when not to use, but the context is clear.

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

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

Discloses email visibility condition for users, but with no annotations, it omits other typical behaviors like pagination, error handling, or authentication 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?

Three sentences with no fluff: purpose, return details, and usage context are all front-loaded and concise.

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

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

For a simple list tool with one parameter, the description adequately covers return fields and a use case, though it could mention possible limits or sorting.

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 already describes the slug parameter well; the description adds no additional parameter meaning beyond the schema.

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

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

The description clearly states the tool lists principals with explicit access to a workspace, and distinguishes it from siblings like 'remove_workspace_member' and 'list_workspaces' by focusing on access listing and verification.

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 a specific use case (agents verifying workspace sharing before writing) but lacks explicit when-not-to-use or alternative tool references.

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 covers basic behavior: listing workspaces accessible to the authenticated principal and returning specific fields. It does not discuss side effects, rate limits, or authentication details, but for a read-only list operation, the transparency 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 three sentences, front-loading the core action and return info. It briefly explains the workspace concept and points to a sibling tool, adding value without redundancy. Slightly less concise due to tangential explanation, but still efficient.

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

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

For a simple list tool with no parameters and no output schema, the description is fairly complete. It specifies what is returned, gives workspace context, and directs to list_surfaces for further detail. It lacks details on ordering or pagination, but these are not critical for a basic listing.

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

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

There are no parameters in the schema, and schema description coverage is 100%. The description does not need to add parameter semantics. With 0 parameters, the baseline score of 4 is appropriate.

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

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

The description clearly states the tool lists all workspaces and specifies the returned fields (slug, mode, creation date). It effectively distinguishes from sibling tools like create_workspace, get_workspace, and delete_workspace.

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

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

The description advises using list_surfaces to see workspace contents, providing clear context for when to use this tool. However, it does not explicitly state when not to use it or explore alternative tools beyond list_surfaces.

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

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

With no annotations, the description fully discloses atomicity, idempotency, batch failure conditions, order preservation, event emission, and row limit. This exceeds the burden of behavioral transparency.

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

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

The description is concise with front-loaded purpose, followed by technical details in efficient sentences. Every sentence provides necessary information without redundancy.

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

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

Given no output schema, the description mentions returned `skipped` count and event emission, but could detail the full response format. Overall, it is fairly complete for the tool's complexity.

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

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

Schema coverage is 100%, and the description adds value by clarifying slug formats, order preservation for rowIds, and referencing list_surfaces for target_surface_slug. It enhances understanding beyond the schema.

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

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

The description clearly states the tool moves rows atomically within the same workspace, with specific verbs and resource. It distinguishes from sibling tools like delete_row, create_row, and update_row by focusing on batch migration.

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 use cases (programmatic data migration, reorganizing content) but does not explicitly state when not to use it or compare to alternatives. The context is sufficient for understanding appropriate usage.

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

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

With no annotations, the description fully discloses behavioral traits: consent-gated two-step flow for agents, timeout, role requirements, and edge case for org visibility, ensuring the agent understands the tool's behavior.

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

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

The description is front-loaded with the purpose and is efficient, though it is a single paragraph that could be more structured (e.g., bullet points). Still, it avoids fluff.

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

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

Given the complexity (consent flow, role constraints, edge cases) and no output schema, the description provides thorough guidance, making the tool's usage clear.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds context (e.g., confirm_token flow) but does not significantly extend parameter semantics beyond the schema.

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

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

The description clearly states the tool's function ('Remove a workspace member') and provides specific constraints (role requirements, sole-owner blocking), making it distinct from sibling tools like 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?

The description offers clear context on when to use (e.g., Editor role required) and when not (sole-owner removal blocked), but does not explicitly name alternative tools for similar actions.

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

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

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

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

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

Three sentences, no wasted words, front-loaded with the action and scope.

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

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

Adequately covers the purpose and usage for a simple request tool. Could mention the return value (e.g., confirmation) but not critical given no output schema.

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

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

Schema coverage is 100%, so the description adds only marginal context. It repeats the enum values but doesn't elaborate beyond the schema.

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

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

The description clearly states the tool requests a plan limit increase, lists the specific limits (agents, workspaces, rows, other), and distinguishes from upgrade_plan by giving an example (already Pro needing custom limit).

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

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

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

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

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

No annotations provided, so description carries full burden. It transparently describes the approval flow: returns {status, approval_url, polling_url, expires_in}, instructs to print approval_url and poll polling_url, and notes that the approving user must be the target agent's owner. This covers the behavior and constraints well.

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

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

Description is a tight paragraph of about 4 sentences, front-loaded with purpose, then differentiator from sibling, then return value and usage instructions, then usage guidance. Every sentence adds value without redundancy.

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

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

Given 2 parameters fully covered in schema, no output schema, the description compensates by explaining the return structure and approval process. It also provides context on when to use and where to get parameter values, making it complete for an agent to select and invoke.

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

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

Schema coverage is 100%, baseline 3. Description adds meaningful context: for reason, explains it's shown verbatim on consent card and capped at 500 chars; for target_agent_id, suggests sources (list_workspace_members, list_workspaces) and notes it's the sibling agent's id. This goes beyond schema descriptions.

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

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

The description clearly states the tool's purpose: asking the human owner to revoke another agent's API key, contrasting with the self-only revoke_api_key sibling. It specifies the action, resource (another agent's key), and scope (cross-agent escalation).

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

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

The description explicitly states when to use this tool: 'when you've spotted credential leakage, misbehaviour, or a stuck sibling that needs a clean kill.' It also advises to provide a useful reason, and contrasts with the sibling revoke_api_key tool, which is self-only.

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

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

Despite no annotations, the description discloses key behaviors: returns an approval_url, requires human owner consent, intentionally does not return the new key plaintext to the requesting agent but surfaces it to the human owner via Settings. This fully informs the agent of the security model.

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

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

The description is concise and front-loaded: it states the core action first, then adds context about similarity to another tool, followed by security implications and usage guidance. Every sentence adds value 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?

Given the lack of output schema, the description adequately explains the return format (approval_url) and the outcome (key rotated, new key out-of-band). The justification for not returning the key and the security pattern are fully covered, making the tool's behavior predictable.

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 that 'reason' surfaces on a consent card and is capped at 500 chars, and that 'target_agent_id' is a sibling agent. This extra context improves clarity beyond the schema.

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

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

The description clearly states the tool rotates another agent's active API key, specifying the action (mint new + revoke old). It distinguishes from siblings like request_revoke_agent_key and rotate_api_key by focusing on agent-level rotation with consent.

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

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

The description provides a clear use case: 'when you've spotted leakage and the target needs a clean credential without going dark mid-task.' It also references request_revoke_agent_key as a sibling with similar shape. However, it does not explicitly list when not to use or compare to other rotation tools like rotate_api_key.

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

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

Discloses soft-delete, 401 on subsequent requests, self-destruct for agents. Could mention irreversibility or restoration possibilities but is informative.

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

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

Single paragraph, front-loaded, every sentence adds value, 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?

Covers behavior, consequences, alternative, and user types. Adequate despite 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?

Adds context: omission defaults to agent's own key, enhancing the schema description significantly.

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

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

Clearly states action 'Revoke an API key' and effect 'soft-delete via revokedAt' and 'return 401'. Distinguishes from sibling tool 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?

Explicitly explains when to use this vs rotate_api_key, and differentiates agent vs user capabilities.

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

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

Discloses atomicity, one-time return of plaintext, 401 on old key, and ownership rules. No contradictions with missing annotations.

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

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

Three concise sentences, front-loaded with key action, no redundant words. Every sentence adds value.

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

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

Given no output schema and one parameter, description fully covers return value, lifecycle, caller guidance, and failure mode. Complete for 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 covers the single parameter with 100% coverage. Description adds valuable context beyond schema: when to omit (agents) vs required (users), and default behavior.

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

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

Clearly states the tool atomically mints a new API key and revokes the old one, with specific details on scopes and naming. Distinct from siblings like revoke_api_key and request_rotate_agent_key.

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

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

Explicitly says when to use (routine hygiene or after leak), how to call (agents omit id, users require id), and consequences (old key invalid, must store new key).

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

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

With no annotations, the description fully discloses key behaviors: the secret is returned only once, immediate effect on signing, and that old secrets cause 401 errors. This provides complete transparency for a critical security 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 concise sentences with no wasted words. The first sentence immediately states the core action, followed by critical usage details. Perfectly front-loaded and efficient.

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

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

Despite no output schema, the description explains what is returned (new secret once) and the downstream effect (deliveries signed with new secret, old receivers reject). Together with schema coverage, it provides complete context for correct tool usage.

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

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

Schema coverage is 100% with clear property descriptions. The description adds only minor context (e.g., 'from list_webhooks' for webhook_id) but does not significantly enhance understanding beyond the schema.

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

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

The description opens with a specific verb 'Mint' and resource 'fresh signing secret for a webhook,' clearly distinguishing from sibling tools like create_webhook or update_webhook which deal with different aspects of webhook management.

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

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

Explicitly states when to use: 'after a suspected leak or as part of routine rotation hygiene.' It doesn't explicitly list alternatives but the context makes it clear this tool is only for secret rotation.

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

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

With no annotations, the description discloses key behaviors: returns ranked hits (score 0-1), navigable URL per hit, access-gated (never returns from inaccessible workspaces). This adequately informs the agent of read-only nature and response structure.

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 appropriately sized and front-loaded with the tool's purpose. It is efficient but could be slightly trimmed without losing 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?

Given no output schema, the description explains return format (ranked hits, score, URL) and covers all parameters. It also mentions pagination via limit/offset, providing sufficient context for a search 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?

All four parameters have schema descriptions (100% coverage). The description adds value by elaborating on the 'kind' parameter (e.g., 'workspace is fastest when the user is naming something') and clarifying the search behavior of 'q' (case-insensitive substring match, already in schema).

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

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

The description uses specific verbs and resources: 'Search across...workspace names, row cell values, and doc sections/paragraphs.' It clearly distinguishes from sibling tools like list_workspaces or get_row by emphasizing multi-surface search and ranked hits.

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 states when to use: 'when the user references something by keyword' and provides a comparison: 'Faster than listing workspaces and iterating.' It implies not to use for exact lookups but doesn't explicitly list alternatives.

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

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

No annotations are provided, so the description carries full responsibility for behavioral disclosure. It discloses conditional behavior (immediate add vs. invite token), required role (editor), and emitted events (member.joined/member.invited). While it doesn't cover idempotency or error handling, it provides significant insight beyond the schema.

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

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

The description is four sentences: first states core purpose, second explains conditional behavior, third states requirement, fourth lists events and alternatives. It is front-loaded, concise, and every sentence adds value without redundancy.

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

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

Given no output schema, the description adequately covers the tool's behavior, prerequisites, and side effects. However, it does not describe the return value or common error conditions (e.g., duplicate invite). For a mutation tool, this is a minor gap; overall, it is fairly complete.

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

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

With 100% schema coverage, the baseline is 3. The description adds value by explaining the email parameter's behavior based on user existence and the role parameter's default and owner-tier constraint. This extra context enhances understanding beyond the schema's type/enum descriptions.

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

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

The description clearly states the tool's action: 'Invite a human (by email) to a workspace at a specified role.' It differentiates from sibling tools like update_workspace_member and remove_workspace_member by explicitly naming them for subsequent actions. The verb 'invite' and resource 'human to workspace' are specific and unambiguous.

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

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

The description provides explicit guidance: 'Editor role required on the workspace' and directs when to use alternatives ('Use update_workspace_member to change a role afterwards, remove_workspace_member to revoke'). It also distinguishes between inviting existing vs. new users, helping the agent choose the correct context.

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

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

With no annotations, the description carries full burden and thoroughly discloses behavior: last-write-wins semantics, emitted events (doc.updated, doc.heading_added, doc.mention_added), permission requirements, detailed input format constraints and limits, cross-reference backlink creation, and auto-embed rules. This is comprehensive.

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

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

The description is overly long and includes many detailed format specifications (e.g., Mermaid sub-types, math constraints) that could be referenced externally. While well-structured, it could be more concise by pointing to documentation for edge cases without losing essential 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?

Despite lacking an output schema and annotations, the description covers all essential aspects: core function, parameter differentiation, behavioral traits, constraints, related events, permission requirements, and references to additional resources. It is sufficient for an agent to use the tool correctly.

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

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

Schema coverage is 100%, baseline 3. The description adds value by clarifying the purpose of each parameter: 'content' for round-tripping from get_doc, 'markdown' for prose from scratch, slug format variants, and optional surface_slug. It also explains mutual exclusivity and conversion behavior, going beyond the schema.

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

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

The description clearly states 'Replace a workspace's doc body.' and distinguishes between content formats (TipTap JSON vs Markdown) and explicitly calls out the sibling tool `append_doc_section` for append-only updates, making the purpose unambiguous.

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

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

Provides explicit when-to-use guidance: 'pass markdown when you're producing prose from scratch... pass TipTap JSON when you need structural edits to an existing doc'. It also mentions the alternative `append_doc_section` tool and specifies the required 'editor role', setting clear prerequisites.

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

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

No annotations provided, so description carries full burden. Discloses section semantics (heading matching, end of section detection), strict 404 on no match, markdown parameter behavior (including deletion), markdown surface compatibility, identity/attribution/events/doc-guard flow, required editor role, and optional surface_slug. No contradictions.

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

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

Description is well-structured and every sentence adds value, but it is somewhat lengthy. Front-loaded with purpose and use case, then parameter details. Excellent but not maximally concise.

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

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

No output schema, so description must explain behavior. It covers error cases (404), permissions, markdown compatibility, and relationship to other endpoints. Fully addresses the tool's complexity.

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

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

Schema coverage is 100%, baseline 3. Description adds significant value beyond schema: for `heading` explains hash marks are stripped and advises using `get_doc` first; for `markdown` explains inclusion of heading line and deletion on empty; for `slug` explains accepted forms; for `surface_slug` explains optionality.

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 verb 'Replace' and resource 'a single section of a workspace's doc body, identified by its heading text.' Explicitly distinguishes from siblings `update_doc` (full replacement) and `append_doc_section` (append-only).

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

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

Provides explicit when-to-use: 'Use this when the agent maintains a recurring section... and only needs to refresh that one piece.' Mentions alternatives and explains why they are inferior (token cost, latency, race conditions). Advises using `get_doc` if heading is uncertain.

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. It explains partial update semantics and move behavior, but omits details like the triggering of a row.moved_surface event (present only in schema descriptions) and does not discuss permissions or error states beyond what's in schemas.

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, no superfluous words. Front-loaded with the primary purpose, then succinctly covers the nuanced move behavior. Every sentence adds necessary information.

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

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

The description covers the tool's behavior well but does not mention the return value (likely the updated row) since no output schema exists. Error conditions are only in parameter descriptions, not the main description. Could be more complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the interaction between surface_slug and position ('position recomputes to the new sheet's tail unless position is also set'), which is not in the schema descriptions.

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

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

The description clearly states 'Update specific fields of an existing row' with a specific verb and resource. It distinguishes from siblings like create_row and delete_row by emphasizing partial updates and the unique move behavior via surface_slug, which is not covered by move_rows but shows overlap.

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 use: partial updates and moving rows via surface_slug. However, it does not explicitly exclude alternatives like move_rows or explain when to prefer this tool over move_rows for moves, leaving some ambiguity.

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 covers mutability, position normalization, event emission, and required role. It does not disclose rate limits or idempotency, but provides sufficient behavioral context for a mutation tool.

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

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

Three sentences with no wasted words. All information is front-loaded and dense, making it easy to parse quickly.

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 update tool with no output schema, the description covers purpose, parameters, behavior, and prerequisites. It lacks mention of return values, but is otherwise complete.

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

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

Schema coverage is 100% with descriptions. The description adds context about subsets and position normalization, enhancing understanding beyond schema alone.

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

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

The description explicitly states the tool renames, reslugs, or reorders a surface, with specific fields like name, surface_slug, position. It clearly distinguishes from siblings like create_surface by focusing on updates.

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

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

It specifies when to use the tool (updating existing surfaces), mentions optional subset of fields, explains position normalization, and notes required editor role. However, it does not explicitly state when not to use or suggest alternatives.

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

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

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

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

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

Three sentences, each adding value: first states the action, second explains the effect when inactive, third gives a concrete use case. No wasted words, front-loaded with primary purpose.

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

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

For a simple toggle tool with 100% schema coverage and no output schema, the description is complete. It covers purpose, effect of both states, and a recommended use case, making it fully actionable for an AI agent.

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

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

Schema coverage is 100% with clear parameter descriptions. The description reinforces the meaning of active flag (enable/silence) but doesn't add new information beyond what schema provides. Baseline 3 is appropriate.

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

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

The description clearly states the tool's action: 'Toggle a webhook's `active` flag on or off.' This is a specific verb+resource pair that distinguishes it from siblings like create_webhook, delete_webhook, and rotate_webhook_secret.

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

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

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

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

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

With no annotations, the description fully discloses behavioral traits: slug renames preserve URLs via aliases, visibility changes disconnect SSE subscribers, editor role required, consent-gating for widening, and emitted events. This is comprehensive and leaves no hidden side effects.

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

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

The description is relatively long but every sentence adds crucial information. It is front-loaded with the main actions and then elaborates on edge cases. Slightly verbose but justified by complexity.

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

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

Given the tool's 6 parameters, no output schema, and complex behaviors (consent, events, role), the description covers all necessary aspects: parameters, side effects, role requirements, consent process, and emitted events. It is complete for agent decision-making.

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 value by explaining the consent flow for visibility widening, the behavior of mode (doesn't affect surfaces), and the implications of changes. This enriches the schema's 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 identifies the tool as updating workspace properties (rename, slug, default-view mode, visibility) and distinguishes it from siblings like update_workspace_member. It uses specific verbs and resources, making its purpose unambiguous.

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

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

The description provides detailed guidance on parameter usage (any subset, omit unchanged), consent requirements for visibility widening, and immediate execution for other updates. It implicitly advises when to use this tool versus other workspace-related tools, though it does not explicitly compare to 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 full burden for behavioral disclosure. It details caller role requirements, blocked operations (demoting sole owner), no-op behavior, and event emission (`member.role_changed`). This is comprehensive.

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

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

Five concise sentences, each adding unique value. No fluff, front-loaded with the main purpose, then covers constraints, edge cases, and side effects efficiently.

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

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

Despite no output schema, the description covers caller prerequisites, blocked scenarios, no-op behavior, and emitted event. This is complete for a mutation tool without needing return value details.

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 context about role transitions (promoting/demoting owner) but does not directly enhance parameter meaning beyond schema descriptions. Schema already covers role, slug, and member_id adequately.

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 'Change an existing workspace member's role', which is a specific verb and resource. It distinguishes itself from siblings like 'remove_workspace_member' (which deletes) and 'share_workspace' (which invites new 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?

The description provides explicit conditions for usage: requires editor role for caller, owner-tier transitions need owner caller, blocking demoting sole owner, and no-op when role unchanged. It lacks explicit comparison to alternatives but gives clear context on when to use.

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

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

No annotations provided, but the description fully discloses billing flat-rate, consent-gated switch, consent surfaces, token details, and special cases like no-card and same-plan paths.

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

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

Though lengthy, the description is well-structured with core action up front, followed by detailed flows; every sentence serves a purpose.

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

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

Description thoroughly covers responses, edge cases, and consent mechanisms, making it complete even without an output schema.

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

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

Schema covers 100% of parameters, yet description adds defaults, token purpose, and mode use cases, providing meaning beyond the schema.

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

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

The description clearly states the tool upgrades the org to Pro or Scale plans with specific verb 'Move the caller's org' and distinguishes from sibling tool 'downgrade_plan'.

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

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

Provides explicit guidance on when to use chat vs web mode, consent flows, and conditions for immediate execution, effectively differentiating from alternatives like downgrade_plan.

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

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

With no annotations provided, the description fully discloses that the tool has no side effects ('NEVER writes anything'), details the return structure (ok, errors, warnings, parsed counts), and explains error and warning categories. It also reveals dependencies (cross-ref resolution gated on accessible workspace set).

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 focused paragraph that front-loads the purpose and then concisely details return values and usage. Every sentence provides essential information without redundancy.

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

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

Given the tool's simplicity (single parameter, no output schema), the description is remarkably complete. It covers the return format, error/warning semantics, dependencies, and usage scenario. No missing information that would hinder agent invocation.

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

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

Schema coverage is 100% with a schema description. The description adds value by specifying that the markdown content supports the same surface as update_doc and lists supported formats (mermaid, math, callouts, etc.), which goes beyond the schema's basic 'Markdown body to validate' description.

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

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

Clearly states the tool is a pre-flight check for markdown before writing, with a specific verb ('validate') and resource ('doc_markdown'). It distinguishes itself from sibling tools like update_doc and append_doc_section by explicitly stating it 'NEVER writes anything; pure parse + analysis.'

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 when iterating on rich-format markdown to catch problems before burning a write.' It references the sibling write tools and clarifies that cross-ref resolution depends on workspace access, providing clear context for usage.

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