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

Annotations already declare readOnlyHint=false and openWorldHint=true, so the mutation nature is covered; the description reinforces this and adds real behavioral detail beyond the schema, notably that access='none' removes implicit access and that the call returns the created permission entry. It omits any auth/permission requirements for granting access.

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

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

Four tight sentences, front-loaded with the core action and scoping rules; every sentence conveys distinct, useful information with no filler.

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

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

For a mutation tool with full schema coverage, annotations, and an output schema, the description covers the action, targeting rules, and access semantics adequately. Return values need not be detailed since an output schema exists.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds a genuine constraint not encoded in the schema: the mutual exclusion of principal_email and principal_domain. It also enumerates the access levels, though it omits mention of suppress_notification.

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

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

The description opens with a specific verb+resource ('Add a permission entry to a Coda doc') that immediately distinguishes it from siblings like coda_list_permissions and coda_delete_permission. The scope (user by email or entire domain) is stated up front.

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

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

It gives a clear usage rule: 'Specify either principal_email or principal_domain (not both),' which is actionable guidance an agent needs before calling. It stops short of naming alternatives or when-not-to-use conditions (e.g., vs. coda_get_acl_settings), so it falls below a 5.

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

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

Annotations already declare this is a write operation (readOnlyHint=false) with open-world effects. The description adds useful context beyond annotations: it returns the new doc's ID, name, and URL, and specifies the folder/root placement behavior. It does not cover permission requirements or failure modes, but that is a minor gap given the annotation coverage.

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

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

The description is front-loaded with the core action and remains fairly tight. The second sentence slightly restates the first ('Create a new Coda doc' vs 'Creates a blank doc or a copy'), making it not maximally concise, but every sentence still carries useful information.

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

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

Given the tool's simplicity, annotations, and the existence of an output schema, the description is complete enough. It covers both creation modes, the default folder behavior, the cloning option, and even previews return values, so an agent has everything needed to invoke it correctly.

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

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

Schema description coverage is 100%, so all three parameters are already documented. The description largely repeats the schema: 'folder or root' mirrors folder_id documentation, and 'use source_doc to clone' is equivalent to the schema's 'copy as a starting point.' It adds no significant parameter semantics beyond what the schema provides, so the baseline of 3 applies.

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

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

The description opens with a specific verb and resource ('Create a new Coda doc'), then immediately clarifies the two modes (blank doc or copy of an existing doc). This clearly distinguishes it from sibling tools like coda_create_page or coda_create_folder, which operate on different resources.

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

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

It explains how to create a blank doc versus a copy, states the default folder behavior, and instructs to use source_doc to clone an existing doc as a template. However, it does not explicitly state when not to use this tool or name alternative tools for similar 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?

Annotations declare readOnlyHint=false and openWorldHint=true, so the write/external nature is already covered. The description usefully adds that it returns the new folder's ID and metadata, but says nothing about permissions, failure modes, or whether names must be unique — additional behavior context is thin.

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

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

Short and front-loaded with the core action first, then the return value and chaining hint. Minor redundancy in restating 'Creates a folder in the specified workspace' after the header, but no wasted sentences.

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

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

Output schema exists, so return values need not be detailed. The description covers purpose, scope, and a useful integration hint, but does not address permissions or uniqueness constraints for a mutation tool, leaving a small gap.

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

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

Schema description coverage is 100%, so the schema already documents name, description, and workspace_id. The description only refers generically to the 'specified workspace' and adds no format, constraint, or default details beyond the schema — baseline 3 is appropriate.

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

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

States a specific verb and resource ('Create a new folder in a Coda workspace') and clearly distinguishes it from sibling folder operations like coda_list_folders, coda_get_folder, and coda_update_folder. An agent can immediately tell what this tool does.

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

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

Gives clear context for when to use it and, crucially, a downstream chaining hint: use the returned folder ID with coda_create_doc to organize docs. It stops short of explicit exclusions or stating when not to use it versus alternatives, so it is not a 5.

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

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

Annotations declare readOnlyHint=false and openWorldHint=true, so the mutation/side-effect profile is already covered. The description adds genuinely useful behavioral context on top: default top-level nesting, the content format switch, and a real limitation ('Pack formulas cannot be inserted via the API'). It stops short of auth/rate-limit/permission notes, so not a 5.

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

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

Front-loaded with the create action and each sentence carries a distinct fact, but the first two sentences ('Create a new page...' / 'Creates a page with optional initial content.') restate the same idea, a small 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?

An output schema exists, so return values need no explanation, and the description still covers the operationally relevant edges: default nesting, format selection, and the pack-formula limitation. Nothing essential for calling the tool correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters. The description reinforces parent_page_id's default (top-level) and content_format's role, but adds little beyond what the schema text states, so baseline 3 applies.

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

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

States a specific verb+resource (create a page) and scopes it to a Coda doc, which cleanly separates it from siblings like coda_create_doc and coda_update_page. An agent can identify the action without opening the schema.

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

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

The description implies usage through detail (nest under parent_page_id, specify content_format) but never states when to use this versus coda_update_page or coda_create_doc, nor any prerequisites for creation. Usage is inferable but not explicit.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds genuinely new behavioral detail: the deletion cascades to all pages, tables, and data, and the operation is irreversible. It does not mention permissions or authorization needs, which limits it short of 5.

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

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

Three short sentences with the destructive scope front-loaded in the first line, followed by the consequence and the prerequisite. No filler or repetition.

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

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

An output schema exists, so return values need not be explained. For a one-parameter destructive tool, the description covers what it does, what it destroys, the irreversibility, and the verification step — nothing an agent needs to call it correctly is missing.

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

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

With a single parameter at 100% schema description coverage, the schema already fully documents doc_id. The description adds no format, sourcing, or ID-resolution guidance beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb and resource ('Permanently delete a Coda doc') with the irreversible scope qualifier. This cleanly separates it from sibling deletion tools such as coda_delete_page, coda_delete_row, and coda_delete_folder, which all target different resources.

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

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

Gives a concrete pre-call prerequisite — verify the doc name with coda_get_doc first — and names that sibling explicitly. It does not state when-not to use this tool (e.g. archival or unpublish alternatives), but the guidance it gives is actionable.

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

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

Annotations already declare destructiveHint=true, but the description adds genuinely useful context: 'Permanently removes the folder' and that contained docs 'may be moved to the root level or deleted depending on Coda's behavior.' The latter is a valuable behavioral disclosure about side effects beyond the annotation signal.

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

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

Front-loaded with the core action, then the destructive warning, then the verification step. Mostly efficient, though the hedge 'depending on Coda's behavior' is slightly vague and adds uncertainty rather than precision.

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

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

An output schema exists so return-value details are unnecessary, and annotations cover the safety profile. The description supplies the destruction warning, side-effect ambiguity, and a verification prerequisite, making it complete enough for correct invocation, with only minor residual ambiguity about doc handling.

Complex tools with many parameters or behaviors need more documentation. 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 a single parameter at 100% schema coverage, the schema fully documents folder_id ('The folder ID to delete'). The description adds only that confirmation includes folder_id, offering marginal value beyond structured data. Baseline 3 is appropriate.

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

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

States a specific verb and resource ('Delete a folder from the Coda workspace'), making it clearly distinguishable from other delete tools like coda_delete_doc or coda_delete_page. It does not explicitly name a sibling alternative, but the resource is unambiguous.

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

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

Gives actionable pre-condition guidance: 'Verify the folder with coda_get_folder before deleting.' This directs the agent to a prerequisite step. It lacks explicit when-not-to-use framing, 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?

Annotations already declare destructiveHint=true, but the description adds crucial behavioral detail beyond them: the operation is irreversible, the page and all its content are removed, and child pages are reparented to the deleted page's parent. This is exactly the extra context an agent needs before invoking a destructive tool.

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

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

Three sentences, front-loaded with the irreversible warning, then side effects, then a verification step. Every sentence earns its place with no wasted words.

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

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

For a destructive deletion tool with annotations covering safety and an output schema covering return values, the description supplies all remaining critical context: irreversibility, content removal, child reparenting, and a pre-call verification step. Nothing essential is missing.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description does not add syntax, format, or constraint details beyond what the schema provides, making the baseline 3 appropriate.

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

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

The description states a specific verb and resource: 'permanently delete a page from a Coda doc.' This clearly distinguishes it from doc-level deletion or page-content deletion, but it never names or contrasts those sibling tools, so it falls short of a 5.

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

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

It provides a clear prerequisite: 'Verify the page name with coda_get_page before calling this.' That is actionable guidance, though it does not explicitly state when to use this tool versus alternatives like coda_delete_page_content or coda_delete_doc.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds genuinely useful detail beyond that: what precisely is destroyed (text content) versus preserved (name, metadata), plus an explicit irreversibility warning.

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

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

Four short sentences, front-loaded with the core action and followed by the crucial non-deletion clarification, irreversibility, and the alternative. 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?

An output schema exists so return values need not be explained. For a destructive two-param tool, the description covers scope, permanence, and the alternative sibling, leaving no material gap.

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

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

Schema description coverage is 100% with both params documented (doc_id, page_id_or_name), so the schema carries parameter meaning. The description adds no syntax or format guidance, so baseline 3 is appropriate.

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

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

States a specific verb+resource ('Delete all content from a page') and immediately scopes it against the sibling operation by clarifying the page itself survives. An agent can distinguish this from coda_delete_page without opening either schema.

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

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

Explicitly states when to use it (clear content, keep the page) and names the alternative ('Use coda_delete_page to remove the page entirely'), giving the routing condition. Nothing is left to inference.

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

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

Annotations already declare destructiveHint=true and openWorldHint=true, so the safety profile is covered. The description adds genuine context beyond that: the principal loses access unless covered by another permission such as domain-level, which helps the agent predict consequences.

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

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

Front-loaded with the core action, followed by two short sentences on effect and prerequisite. No filler; every sentence carries information.

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

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

An output schema exists, so return values need not be explained, and the annotations cover the safety profile. What remains for the agent (action, prerequisite, side effect) is fully stated.

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

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

Schema coverage is 100% and both parameters are documented in the schema, including the provenance of permission_id ('from coda_list_permissions'). The description largely repeats this, adding little beyond the baseline for a fully-covered 2-param tool.

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

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

The description opens with a specific verb+resource ('Remove a permission entry from a Coda doc') that is clearly distinct from siblings like coda_add_permission and coda_list_permissions. An agent can tell exactly what this does without opening the schema.

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

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

It gives a clear prerequisite ('Get the permission_id from coda_list_permissions first') and states the effect on the principal. It stops short of explicit when-not-to-use guidance, but the context for correct invocation is well established.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is partly structured. The description adds real context beyond that: the removal is permanent and irreversible, plus a recommended verification step. It stops short of stating permission/ACL requirements or any error behavior, so it is not a 5.

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

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

Three short sentences, front-loaded with the action, then irreversibility, then verification and the alternative. No filler; every sentence carries a distinct piece of information.

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

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

For a destructive single-row tool with full schema coverage, an output schema (so return values need no prose), and annotations covering safety, the description supplies everything else an agent needs: irreversibility, a verification precondition, and the bulk alternative.

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

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

Schema description coverage is 100% and all three parameters (doc_id, table_id_or_name, row_id_or_name) are documented in the schema. The description adds no format hints (e.g., whether a row name is accepted vs. an ID) beyond what the schema already says, so the baseline 3 applies.

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

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

States a specific verb (Delete) and resource (a single row from a Coda table), with the scope word 'single' explicitly distinguishing it from the bulk sibling. An agent can tell it apart from coda_delete_rows without opening either schema.

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

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

Names a concrete precondition ('Verify the row with coda_get_row before deleting') and an explicit alternative with the selecting condition ('For bulk deletion, use coda_delete_rows with a list of row IDs instead'). When-to-use and when-to-use-something-else are both covered.

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

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

Annotations already declare destructiveHint=true, so the safety profile is largely covered. The description adds genuinely useful context beyond that: irreversibility ('Permanently removes... This is irreversible') and the async return contract ('Returns a requestId for async mutation tracking'). It does not, however, discuss permissions or partial-failure 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?

Front-loads the action, then the critical warning, then the prerequisite, then the return shape, then the sibling preference. Every sentence earns its place with no filler.

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

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

For a destructive batch mutation, the description covers irreversibility, prerequisite step, async tracking, and sibling choice. An output schema exists, so return-value explanation is not needed, and nothing essential is missing.

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

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

Schema description coverage is 100%, so the schema already documents doc_id, table_id_or_name, and row_ids. The description only adds that row_ids come from coda_list_rows, which is marginal. Baseline 3 is appropriate.

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

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

States a specific verb+resource ('Delete multiple rows from a Coda table') with explicit scope ('in a single call'). It clearly distinguishes itself from the singular sibling coda_delete_row by contrasting the batch behavior.

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

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

Explicitly names the prerequisite action ('List the rows first with coda_list_rows to get their IDs') and the alternative it beats ('Prefer this over calling coda_delete_row in a loop'), with the reason (performance/rate limit efficiency). Nothing is left to inference.

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

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

Annotations cover readOnlyHint and openWorldHint, so safety in broad terms is established. The description adds valuable context: async job initiation, possible immediate return for small pages, and polling of an export ID. It doesn't mention rate limits, retention of export artifacts, or what happens on repeated calls for the same page, but the async lifecycle disclosure is genuinely additive.

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

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

Three sentences, front-loaded with the core action, then the async lifecycle, then the sibling routing. Zero filler.

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

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

An output schema exists, so return-value details are unnecessary. The description covers the async flow and alternative tool well, though it could note whether repeated exports are idempotent or deduplicated, which matters for a polling-based API.

Complex tools with many parameters or behaviors need more documentation. 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 an enum exists, so the schema already fully documents the three parameters. The description adds nothing new about doc_id, page_id_or_name, or output_format; baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific verb ('export') and resource ('a page's content'), and explicitly distinguishes itself from the sibling coda_get_page_content. The async nature of the operation is clear from the first sentence.

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

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

Explicitly names the alternative (coda_get_page_content) and the condition that selects it ('quick reads' vs 'full export with embedded images resolved'). This is a textbook routing instruction.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint, so safety is covered. The description adds real context beyond that by enumerating what the settings contain (copying allowed, editors changing permissions, default access mode) and by clarifying these are doc-level administrative flags rather than per-user grants. No auth or rate-limit detail is added, keeping it out of 5 territory.

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

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

Three short sentences, front-loaded with the core action, and each sentence earns its place by clarifying return content and scope. Slightly more prose than strictly necessary for a one-parameter getter, but no filler.

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

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

An output schema exists, so return values need not be explained, yet the description informally previews the return content. Between the full schema coverage, annotations and this text, an agent has what it needs, with only the lack of explicit alternative-tool routing as 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?

Schema description coverage is 100% and there is only one parameter, so the schema fully documents doc_id. The description adds no format or syntax detail beyond naming the doc, making 3 the correct baseline.

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

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

States a specific verb+resource ('Get the ACL settings for a Coda doc') and then explicitly distinguishes the target from individual permission entries, which separates it from siblings like coda_list_permissions. It names the resource clearly but does not name the sibling tool directly, so it falls just short of a 5.

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

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

Usage is only implied: the note that these are 'administrative settings, not individual permission entries' hints that permission-entry tools are the alternative, but no explicit when-to-use or when-not-to-use guidance is given. Adequate but with a clear gap.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, openWorldHint), so the bar is lower. The description adds genuine behavioral context beyond them: analytics are 'not real-time' and 'typically updated every few hours,' which tells the agent about data staleness/latency. It does not cover any rate-limit or auth nuance, so not a 5.

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

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

Three short sentences, front-loaded with the core action, then the freshness caveat. Slight redundancy between 'Get the timestamp' and 'Returns a timestamp indicating the freshness,' but every sentence still carries useful 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?

An output schema exists, so return values need no explanation. The description supplies the one thing an agent needs before calling it — that the data is periodically refreshed, not live. Complete for a trivial, parameterless read tool.

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

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

The tool takes zero parameters, so per the rubric the baseline is 4. There are no arguments whose semantics the description would need to clarify.

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

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

States a specific verb and resource: 'Get the timestamp of when analytics data was last updated.' This clearly differentiates it from data-returning siblings like coda_list_doc_analytics or coda_get_doc_analytics_summary, since it fetches freshness metadata rather than analytics content. It stops short of naming a sibling explicitly, so a 4 rather than a 5.

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

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

Gives an explicit trigger: 'Check this before relying on analytics data for time-sensitive decisions.' That is actionable context for when to call it. It omits an explicit contrast with the actual analytics-listing tools, so it is clear but not fully routing.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint, so the safety profile of this read operation is fully covered. The description adds that the return includes name, ID, type, format and configuration, but that overlaps with the existing output schema, so incremental behavioral value is modest.

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

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

Three short sentences, front-loaded with the core action, followed by return contents and the routing hint. Every sentence earns its place with no filler.

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

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

For a simple 3-param read tool with an output schema and full annotation coverage, the description supplies everything needed to call it correctly. Minor gap: no note on auth or rate limits, but nothing an agent strictly needs is missing.

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

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

Schema description coverage is 100%, so all three parameters (doc_id, table_id_or_name, column_id_or_name) are already documented in the schema. The description adds no syntax or format guidance beyond that, so the baseline 3 applies.

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

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

States a specific verb+resource ('Get metadata for a single column in a Coda table') and immediately distinguishes itself from the sibling coda_list_columns by naming that alternative. An agent can tell it apart from the list variant without opening the schema.

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

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

Provides explicit when-to-use guidance ('check a specific column's type before writing data to it') and names the alternative for the other case ('For the full column schema, use coda_list_columns instead'). Both the selection condition and the alternative are supplied.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so safety is covered. The description adds genuine context by defining what a control is (sliders, select lists, date pickers, text inputs, buttons) and clarifying that the value reflects the current user-facing state.

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

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

Front-loaded with the core action, followed by tightly scoped sentences that each add a distinct piece of information (return fields, control types, state semantics, discovery sibling). No filler.

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

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

An output schema exists to explain return values and annotations cover the safety profile, so the description need not repeat those. It supplies the remaining semantic context (what a control is, what the value means) that an agent needs.

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

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

Schema description coverage is 100%, so both parameters (doc_id, control_id_or_name) are already documented in the schema. The description adds no additional syntax or format detail for either, so the baseline 3 applies.

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

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

States a specific verb ('Get') and resource ('control in a Coda doc'), then enumerates return fields (name, ID, type, current value). It also names the sibling coda_list_controls so the agent can distinguish lookup-by-identity from discovery.

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

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

Explicitly routes the agent to coda_list_controls for discovery, which clarifies when this tool is the right choice. It lacks any explicit when-not or prereq guidance, so it falls short of a full 5.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint, so the safety profile is covered. The description adds genuine behavioral boundary context by enumerating returned metadata (name, owner email, folder, timestamps, doc size) and stating what is out of scope. It omits auth/permission requirements or rate-limit behavior, so it stops short of a 5.

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

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

Three tight sentences: purpose first, return contents second, and the disambiguation/alternative pointer last. No filler and nothing buried.

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

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

An output schema exists, so return-value detail is not strictly required, yet the description still summarizes the payload and rules out the common misexpectation (page/table data). For a single-param read tool this is fully 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?

Only one parameter (doc_id) at 100% schema description coverage, so the schema already carries the semantics. The description repeats the sourcing hint from the schema without adding format or validation detail; baseline 3 applies when the schema does the work.

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

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

States a specific verb and resource with scope: 'Get metadata for a single Coda doc by ID.' This clearly separates it from coda_list_docs (plural listing) and from coda_get_page/coda_get_table, so an agent can pick it without opening the schema.

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

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

Explicitly bounds the tool with a negative case — 'Does NOT return page content or table data — use coda_list_pages or coda_list_tables for those' — and names the alternative tools that supply doc_id (coda_list_docs, coda_resolve_browser_link). Both the when and the when-not are stated.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the safety profile is covered. The description adds real context beyond that: it enumerates the returned metrics (views, unique viewers, copies) and discloses the aggregation scope ('summed across all accessible docs'). It doesn't cover date-window defaults or whether untitled/inaccessible docs are excluded, but that is a minor gap given the annotation coverage and the output schema.

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

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

Two sentences, zero filler: the first states the action and scope, the second states the metrics and the routing rule. Information is front-loaded with the routing constraint last, which is the right ordering.

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

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

An output schema exists, so return values need not be spelled out, yet the description still names the key metrics. With annotations, a schema, and a clear sibling distinction, an agent has what it needs; only the treatment of the date-range defaults and the meaning of 'accessible' remain unstated.

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

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

Schema description coverage is 100%, so since_date, until_date, and is_published are already documented in the schema with ISO 8601 and boolean semantics. The description adds nothing about parameter behavior (e.g., default all-time window), so the baseline of 3 applies.

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

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

States a specific verb ('Get'), a specific resource ('aggregated analytics summary across all docs'), and the aggregation scope ('summed across all accessible docs'). It also explicitly names the sibling coda_list_doc_analytics as the per-doc alternative, so an agent can distinguish the two from description text alone.

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

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

Explicitly prescribes when to use this tool ('for a high-level overview') and names the alternative plus the condition that selects it ('use coda_list_doc_analytics for per-doc breakdown'). This is exactly the when/when-not/alternative routing an agent needs.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint, so the safety and repeatability profile is covered. The description's only added behavioral content is the list of returned fields, which the output schema already conveys, and it says nothing about permissions, failure modes, or depth of child items. Adequate but thin against an already-covered annotation 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?

Two short sentences, front-loaded with the action and scoping guidance following immediately. The field enumeration in the first sentence is mildly redundant given the output schema exists, which keeps it from a perfect score.

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

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

For a single-parameter read tool with full schema coverage, an output schema, and read-only/idempotent annotations, the description supplies the missing piece (discovery prerequisite) and nothing critical is absent. It is complete enough for correct invocation, though not exhaustive.

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

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

Schema description coverage is 100% and the single folder_id parameter is fully documented in the schema ('The folder ID to get details for'). The description adds no format, source, or constraint detail beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource ('Get metadata for a single folder') and enumerates the returned fields (name, ID, parent folder, child items). It also names the sibling coda_list_folders, so an agent can distinguish this single-folder read from the list operation without opening either schema.

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

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

Explicitly directs the agent to run coda_list_folders first to discover folder IDs, which is real when-to-use guidance tied to the required folder_id parameter. It stops short of stating exclusions or alternative retrieval paths, so it is clear context rather than a full when/when-not rubric.

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

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

Annotations already cover safety (readOnlyHint, idempotentHint). The description adds genuinely useful context beyond them: the value is computed by Coda and reflects the latest state, and error state is surfaced. It doesn't mention auth scope or rate limits, but the added semantic context is solid.

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

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

Front-loaded with the core action in sentence one, then returns and the alternative. The middle sentence enumerating return fields partly duplicates the output schema, so it is slightly less lean than it could be.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 two-param read tool with an output schema and full annotations, the description covers purpose, returns, freshness, and the discovery alternative. Nothing an agent needs in order to call it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The phrase 'named formula' implies, but does not add new detail about, how formula_id_or_name resolves names — baseline 3 is correct when the schema does the heavy lifting.

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

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

States a specific verb ('Get') and resource ('current value of a named formula in a Coda doc'), and explicitly distinguishes itself from the discovery sibling coda_list_formulas. An agent can tell it apart from coda_list_formulas and coda_get_control without opening a schema.

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

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

Explicitly routes the agent to coda_list_formulas for discovery, which is the key usage decision here. It does not state when-not-to-use or cover edge cases (e.g., formula not found), so it falls short of a 5.

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

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

Annotations already establish readOnlyHint, idempotentHint, and openWorldHint, but the description adds substantial context beyond them: the 202/requestId contract that ties this tool to a prior write, the three possible outcome states, and the polling cadence with a hard 30-second ceiling. This is exactly the kind of operational detail an agent cannot derive from structured fields.

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

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

Four short sentences, front-loaded with the purpose and followed by the trigger, the return shape, and the polling recipe. Every sentence carries distinct information with no redundancy.

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

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

An output schema exists, so return values need not be exhaustively described, and annotations carry the safety profile. The description still adds the async workflow contract (202 -> requestId -> poll) and timeout, leaving nothing an agent needs in order to call this correctly.

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

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

Schema coverage is 100% and the single required parameter is documented in the schema as the requestId from a 202 response. The description restates that origin but adds no format, syntax, or validation detail beyond the schema, so the baseline 3 for schema-led parameters 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 states a specific verb and resource ('Check the status of an asynchronous mutation') and immediately explains the trigger context (write operations returning 202 with a requestId). No sibling tool covers async mutation polling, so there is no ambiguity to resolve.

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

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

It gives explicit when-to-use guidance ('Use this tool to poll whether the mutation has completed, is still processing, or failed') plus concrete operational rules: poll every 2 seconds, up to 30 seconds maximum. Neither the conditions nor the cadence are left to inference.

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

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

Annotations already cover safety traits: readOnly, openWorld, and idempotent. The description adds meaningful behavior beyond those annotations by disclosing the pack-maker authorization requirement and clarifying that metrics are summed across packs. It does not contradict the annotations.

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

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

The description is two short sentences, front-loaded with the purpose and followed by the return contents and access condition. It is appropriately sized and contains no filler.

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

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

With an output schema covering return values and annotations covering safety, the description supplies enough context: aggregation purpose, returned metrics, and pack-maker restriction. The main remaining gap is explicit guidance on how it relates to nearby list_pack analytics tools.

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

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

Schema description coverage is 100%, so the schema already documents pack_ids, since_date, until_date, and is_published. The description adds no parameter-specific syntax, defaults, or filter behavior beyond what the schema provides. Baseline 3 is appropriate when the schema fully carries parameter semantics.

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

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

States a specific verb and resource: get aggregated analytics summary for packs. It further distinguishes itself from sibling list tools by specifying that results are summed across packs and by naming the returned metrics. An agent can identify it as the aggregate counterpart to coda_list_pack_analytics.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 an access prerequisite ('only available to pack makers'), which is useful context. However, it does not explicitly say when to use this summary versus coda_list_pack_analytics or coda_list_pack_formula_analytics. Usage is implied by 'aggregated summary' but not clearly routed.

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

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

Annotations already declare readOnly, idempotent, and openWorld, so the safety profile is covered. The description adds valuable behavioral context beyond that: exactly which metadata is returned, what is explicitly excluded, and the instability of page names. It does not mention pagination or error behavior, but those are not clearly relevant for a single-resource get.

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

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

Three tight sentences with zero waste. The core purpose and returned fields are front-loaded, followed by the exclusion and the ID caveat.

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

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

An output schema exists so return values need not be explained, yet the description still summarizes them usefully. With annotations covering the safety profile and both parameters documented, an agent has everything needed to call this correctly.

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

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

Schema coverage is 100%, so both parameters are already documented in the schema, and the description's 'prefer ID — names are unstable' note merely echoes the schema's own wording. No additional format or syntax detail is added, so baseline 3 is correct.

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

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

States a specific verb and resource ('Get metadata for a single page in a Coda doc') and enumerates the returned fields (name, ID, parent, subtitle, icon, image). It explicitly distinguishes itself from the sibling coda_get_page_content by stating it does NOT return text content.

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

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

Explicitly routes the agent to coda_get_page_content when text content is needed, and adds the operational guidance to always use page IDs since names can change. Both the when-to-use and the alternative are named directly.

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

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

Annotations already cover the safety profile (readOnly, idempotent, openWorld), so credit goes to added context: the warning that markdown output may be lossy for complex Coda content such as embedded objects and pack formulas. This is genuine behavioral disclosure beyond structured fields, though it doesn't mention output shape or pagination.

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

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

Front-loaded with the core purpose, then the format behavior, then the lossy caveat and alternative. The second sentence ('Returns the page's content in the specified format') is slightly redundant against the first, but the description remains tight and purposeful.

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

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

An output schema exists, so return values need not be described, and the description covers format behavior, the lossy-markdown caveat, and the sibling routing. It is essentially complete for a read tool, with only minor gaps around alternatives like export_page.

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

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

Schema description coverage is 100% and the enum for output_format is defined in the schema, so the schema does the heavy lifting. The description repeats the HTML/markdown format choice but adds no syntax or format detail beyond what is already documented. Baseline 3 applies.

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

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

States a specific verb and resource ('Get the text content of a page in a Coda doc') and explicitly distinguishes itself from the sibling coda_get_page ('metadata only'). An agent can tell it apart from coda_get_page without opening either schema.

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

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

Gives clear when-to-use guidance and names the specific alternative (coda_get_page for metadata). It does not address related siblings like coda_export_page or coda_delete_page_content, but the core routing decision is explicit.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint, so the safety profile is covered. The description adds that all column values are returned and that the display column value can serve as a key, but says nothing about pagination, rate limits, or behavior for missing rows. That is reasonable added context but not rich behavioral disclosure.

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

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

Three tight sentences: purpose first, return value second, disambiguation last. No filler, no repetition of the title, and the routing guidance is placed where an agent will read it before committing to the call.

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

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

With an output schema present, the description need not explain return shape, and annotations carry the safety profile; the description covers purpose, keys, and the closest alternative. Slightly short of 5 only because it does not address what happens when a row is not found or how display-column matching behaves on ambiguity.

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

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

Schema description coverage is 100%, so all four parameters are already documented in the schema. The description reinforces the ID-or-display-column-value semantics of row_id_or_name and the column-name/ID distinction indirectly, but adds no syntax, format, or defaulting detail beyond the schema. Baseline 3 applies.

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

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

States a specific verb and resource ('Get a single row from a Coda table'), specifies the lookup keys (ID or display column value), and names the sibling it is distinct from (coda_list_rows). An agent can distinguish it from coda_list_rows, coda_get_table, and coda_list_columns without opening any schema.

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

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

Explicitly states when to use it ('when you have a specific row ID or know the display column value') and names the alternative with its selecting condition ('For querying multiple rows with filters, use coda_list_rows instead'). Both the positive and negative routing cases are covered.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so safety semantics are covered. The description adds real value by specifying the nature of the returned metadata (share/copy/restriction flags) and clarifying what it is not, though it omits any auth or scope 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 short sentences, front-loaded with the purpose and followed by the return characterization and the disambiguation. Every sentence earns its place with no filler.

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

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

For a single-param read tool with an output schema and full annotation coverage, the description is complete: it explains what is returned, what it is not, and where to go instead. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100% for the single doc_id parameter, so the schema fully documents it. The description adds no syntax or format detail beyond what the schema provides, which is the expected baseline when the schema does the work.

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

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

States a specific verb and resource (get sharing metadata for a Coda doc) and immediately characterizes the return content (whether the doc can be shared, copied, or restricted). It also explicitly distinguishes itself from coda_list_permissions, so an agent can tell the two apart without opening a schema.

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

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

Explicitly routes the agent: use this for the doc's sharing configuration, and use coda_list_permissions when you want the list of who has access. This is a clear when-to-use plus a named alternative, leaving nothing to inference.

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

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

Annotations already declare readOnly/idempotent/openWorld, so the safety profile is covered. The description adds real scope behavior beyond them by naming exactly which fields come back and by stating the negative scope ('does NOT return row data or column definitions'), which prevents a wrong call — though the field list partly overlaps with the output schema.

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

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

Two sentences, front-loaded with purpose, then the return scope, then the negative scope with alternative tools. No filler; every clause carries routing or scoping information.

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

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

With annotations covering the safety profile, a full output schema describing return values, and a 100%-documented two-parameter schema, the description fills the remaining gap — exactly what this tool returns and what it deliberately omits — so an agent has everything needed to call it correctly.

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

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

Schema description coverage is 100% and both parameters (doc_id, table_id_or_name) are documented in the schema. The description adds no format or naming nuance beyond the schema's 'Table ID or name', so the baseline 3 applies.

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

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

States a specific verb and resource ('Get metadata for a single table or view in a Coda doc') and enumerates the returned fields. It also distinguishes itself from the row/column siblings, so an agent can tell it apart without opening any schema.

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

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

Explicitly routes the agent away from this tool for row data (coda_list_rows) and column definitions (coda_list_columns), which is precise when-not-to-use guidance. It does not address when to use this tool versus coda_list_tables, so the routing is not fully symmetrical.

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

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

Annotations declare only readOnlyHint=false and openWorldHint=true, so the description carries real weight: it discloses the 500-row-per-call cap, the async 202 behavior, the requestId return, the tracking tool, and the upsert semantics. These are concrete operational traits an agent cannot get from the annotations or schema.

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

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

The core action is front-loaded in the first sentence, and every following sentence adds a distinct constraint (limit, column naming, upsert behavior, async return). No filler or redundant restatement of the name.

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

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

For a 4-parameter write tool with an output schema present, the description covers the mutation safety profile, the bulk limit, async behavior, upsert path, and the tracking follow-up. Nothing essential to invoking it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful semantics by requiring column names rather than IDs inside cells and clarifying that key_columns is 'the only way to bulk-update rows.' That extra guidance exceeds what the schema alone conveys.

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

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

States a specific verb and resource (insert rows into a Coda table) with the added scope of optional upsert. It distinguishes itself from siblings by noting it is the only way to bulk-update rows and by naming coda_get_mutation_status as the tracking companion. An agent can tell it apart from coda_update_row and coda_list_rows without opening any schema.

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

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

Explicitly explains when key_columns triggers upsert versus pure insert, and points to coda_get_mutation_status for async tracking. It does not name coda_update_row as the alternative for single-row edits, leaving that inference to the agent. Clear context overall but no explicit when-not-to-use statement.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the safety profile is covered. The description adds that each entry has a name and ID, which is useful context about the payload, but nothing about pagination, size, or freshness of the list. Adequate but not rich.

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

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

Three short sentences, front-loaded with the purpose, then the return shape, then the downstream use. No filler or redundancy.

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

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

For a zero-parameter reference lister with annotations covering safety and an output schema covering return structure, the description supplies everything an agent needs to select and call it. Only minor gaps remain (list size/pagination expectations).

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

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

The tool takes zero parameters, so the baseline is 4; there is nothing to disambiguate and the description correctly implies no inputs 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?

States a specific verb and resource ('List all available publishing categories') and scopes it to the Coda gallery publishing domain. It also names the payload contents (name and ID), so an agent can tell it apart from the other list_* tools without opening the schema.

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

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

Explicitly ties its output to a downstream tool: 'Use these category IDs with coda_publish_doc.' That gives clear context for when the tool is relevant, though it never states when not to call it or names an alternative source for the same IDs.

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

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

Annotations already establish readOnly, idempotent and openWorld, so the bar is lower, yet the description still adds real context: column IDs are internal identifiers and names should be used with row data. It omits pagination behavior despite the limit/cursor parameters, keeping it short of a 5.

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

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

Four sentences, all front-loaded and purposeful, with the core action first and the workflow guidance last. The return-field enumeration slightly overlaps the output schema, but nothing is wasted.

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

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

With an output schema, rich annotations and full param coverage, the description only needs to add workflow context, which it does via the pre-write recommendation and the ID-vs-name caveat. Pagination semantics for limit/cursor are the one notable omission.

Complex tools with many parameters or behaviors need more documentation. 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 limit, cursor, doc_id and table_id_or_name are already documented. The description adds only the conceptual ID-vs-name distinction, which is the expected baseline when the schema does the heavy lifting.

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

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

States a specific verb and resource ('List all columns in a Coda table') and the 'all columns' scope implicitly separates it from the singular coda_get_column sibling. An agent can tell what it returns without opening either schema.

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

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

Explicitly says to 'call this before inserting or updating rows to know the available columns and their types', which is a concrete when-to-use condition tied to coda_insert_rows/coda_update_row. It does not, however, name coda_get_column as the alternative for fetching a single column.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint, so the safety profile is covered. The description adds that controls are interactive UI elements and lists return fields, but says nothing about pagination behavior, result limits, or permissions needed to read controls — context an agent would benefit from given the cursor parameter.

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

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

Three short sentences, front-loaded with the core action followed by return contents and the sibling handoff. The sentence explaining that controls are interactive UI elements is mild filler, but nothing is wasted or buried.

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

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

With an output schema present, return-value explanation is not required, and the description covers purpose, scope and the alternative tool. It is essentially complete for a simple paginated list, with only permission/pagination nuance missing.

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

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

Schema description coverage is 100% with 3 parameters, so limit, cursor and doc_id are fully documented in the schema. The description adds no syntax, format, or defaulting detail beyond that, so the baseline of 3 applies.

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

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

States a specific verb (list) and resource (controls) scoped to a Coda doc, and immediately disambiguates with concrete examples (sliders, select lists, date pickers). It is clearly distinguishable from coda_get_control and from the other list_* siblings.

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

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

Explicitly routes the agent to coda_get_control for reading a single control's current value, which is the key decision point against the closest sibling. It lacks an explicit statement of when not to use this tool or a note about doc scope/permissions, so it falls short of full when/when-not coverage.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint, so the safety profile is covered. The description adds an authorization constraint ('Only available to doc owners') that annotations cannot express, which is genuine value; it stops short of noting rate limits or result-window caveats, so it is not a full 5.

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

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

Three sentences, front-loaded with purpose, then capability, then the alternative. Efficient overall, but the metric list ('views, copies, likes, sessions') is partially repeated in the next sentence ('total views, unique views, copies'), a small redundancy that keeps it out of the top band.

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

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

With annotations covering the read-only/idempotent profile, an existing output schema covering return values, and 100% schema coverage of parameters, the description only needs to supply scope, access rules and sibling routing — all of which it does. Nothing essential is missing, though pagination behavior across a potentially long result set is left entirely to the schema.

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

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

Schema description coverage is 100% and all six parameters (limit, cursor, doc_ids, since_date, until_date, is_published) are documented in the schema itself. The description only alludes to a 'specified date range' and adds no format or syntax detail beyond what the schema already provides, so the baseline 3 applies.

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

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

States a specific verb+resource (list analytics data for docs) and enumerates the returned metrics (views, copies, likes, sessions), which is more than a restatement of the name. It also explicitly differentiates itself from coda_get_doc_analytics_summary ('per-doc breakdown' vs 'aggregated totals'), so an agent can pick between the two without opening either schema.

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

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

Gives the routing condition explicitly: use this for per-doc breakdowns, use coda_get_doc_analytics_summary for aggregated totals. It also states a real prerequisite ('Only available to doc owners'), which is the kind of when-can-you-use-this guidance an agent needs before calling.

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

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

Beyond the readOnly/idempotent/openWorld annotations, it discloses a concrete rate limit (4 calls per 6 seconds), enumerates the returned metadata (name, owner, folder, timestamps), and explicitly excludes page content and table data. That is exactly the operational context annotations cannot express.

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

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

Four tight sentences with the scope stated first and the negative constraint second; no filler. Slightly dense but every sentence carries information, and the ordering prioritizes the highest-value facts.

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

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

With an output schema present and annotations covering the safety profile, the description needs only to frame scope, exclusions, and throttling, which it does. It omits mention of the response_format and folder/owner filters, but the schema documents those adequately, so nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so every parameter already carries its own description; the description merely echoes the purpose of query and cursor. It adds no syntax, format, or interaction details beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource with explicit scope ('List Coda docs accessible to the current API token') and immediately contrasts itself with siblings by declaring what it does not return, naming coda_list_pages and coda_list_tables. An agent can distinguish this from coda_get_doc, coda_create_doc, and the page/table listers without opening a schema.

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

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

It routes the agent away from this tool for page/table content and points to the correct alternatives, and it explains how to use query for name search and cursor for pagination. It stops short of stating explicit when-to-use framing (e.g., 'use this to discover doc IDs before calling coda_get_doc'), but the implied 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?

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so the safety profile is covered. The description adds that folders are scoped to 'the current API token' and lists returned metadata fields, but the return details are redundant because an output schema exists. No pagination or rate limit behavior is mentioned.

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

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

The description is three sentences: purpose, return metadata, and integration hint. It is front-loaded with the core action 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?

For a zero-parameter list tool with full annotation coverage and an output schema, the description covers purpose, return shape, and a key downstream use. It omits minor details like pagination or empty-result behavior, but is otherwise complete for correct invocation.

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

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

The tool takes zero parameters, so the baseline is 4. The description does not introduce any parameter-related information, which is appropriate since there are none to document.

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

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

The description states a specific verb and resource ('List all folders') and clearly differentiates from sibling tools like coda_get_folder by specifying a list operation across all folders accessible to the token. The scope is unambiguous.

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

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

It provides an implicit usage context ('Use the returned folder IDs with coda_create_doc'), but does not explicitly say when to choose this tool over alternatives such as coda_get_folder, nor does it state any exclusions or 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?

Annotations already declare readOnlyHint, idempotentHint and openWorldHint, so safety is covered. The description adds real behavioral context beyond that: the result set contains name/ID/value metadata, and the disambiguation between doc-level named formulas and column formulas prevents a wrong-scope call. Pagination behavior is left to 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?

Three short sentences, front-loaded with the purpose, then return shape, then disambiguation and the alternative. No filler sentences and every clause carries information.

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

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

With an output schema present, return values need not be spelled out, and the rich annotations cover the safety profile; the schema documents all three parameters. The description covers purpose, scope and the sibling alternative, leaving only minor details such as pagination to structured fields.

Complex tools with many parameters or behaviors need more documentation. 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 limit, cursor and doc_id are fully documented in the schema itself. The description adds no syntax, format or constraint detail beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource (list named formulas in a doc) and immediately scopes it: 'doc-level computed values (not column formulas)'. This lets an agent separate it from coda_get_formula and from column-related siblings like coda_list_columns without opening a schema.

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

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

Explicitly routes the agent: 'Use coda_get_formula to get a specific formula's current value', and the named-vs-column-formula note implies when this tool is the right one. It lacks an explicit exclusion list for the other list_* siblings, but the selection condition for the main alternative is stated.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so safety is covered. The description adds a non-obvious authorization constraint (pack makers only, own packs only) that the annotations do not convey, though it says nothing about pagination behavior beyond what the cursor parameter implies.

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

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

Three short sentences, front-loaded with the core action, followed by return content and access restriction. No filler, though the return-content sentence is partly redundant given an output schema exists.

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

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

With an output schema present and all six optional parameters fully documented, the description only needs to supply scope and access rules, which it does. The missing piece is sibling differentiation within the analytics family.

Complex tools with many parameters or behaviors need more documentation. 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 every parameter (limit, cursor, pack_ids, since_date, until_date, is_published) is already documented in the schema. The description adds no syntax or filtering guidance, so the baseline 3 applies.

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

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

The description uses a clear verb+resource ('List analytics data for Coda packs') and specifies the metric types returned (install counts, doc usage, formula invocations). It does not, however, distinguish this listing tool from close siblings like coda_get_pack_analytics_summary or coda_list_pack_formula_analytics, so an agent must infer the boundary.

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

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

'Only available to pack makers for their own packs' gives a real access precondition, but there is no explicit statement of when to prefer this over the summary or formula-analytics siblings. Usage is only implied by the tool name.

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

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

Annotations cover the safety profile (readOnly, idempotent, openWorld), so the description carries a lighter burden. It adds a genuinely useful behavioral fact beyond the annotations: an authorization requirement (pack maker only). It does not, however, discuss rate limits or freshness/staleness of the analytics window.

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

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

Three short sentences with zero padding; the core purpose leads and the permission caveat and return summary follow in descending priority. 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?

An output schema exists, so explaining the return payload is unnecessary; the description still gives a compact preview of the metrics. With full schema coverage and explicit annotations, an agent has enough to call correctly; only the relationship to sibling analytics tools is left implicit.

Complex tools with many parameters or behaviors need more documentation. 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 limit, cursor, pack_id, since_date, and until_date are all documented in the schema with types, bounds, and format hints. The description adds no parameter-level meaning beyond that, making the baseline 3 correct.

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

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

States a specific verb (List), resource (analytics data), and scope (individual formulas within a pack), immediately distinguishing it from the sibling pack- and doc-level analytics tools. The second sentence enumerates the metrics returned, so an agent knows exactly what it gets.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 access constraint ('Only available to the pack maker') is stated, which helps the agent decide whether the call is even permissible. However, there is no explicit guidance on when to prefer this over coda_list_pack_analytics, coda_get_pack_analytics_summary, or coda_get_analytics_updated; usage must be inferred from the scope wording.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the safety profile is covered. The description adds meaningful behavioral context beyond annotations by disclosing the required authorization level (doc owners only) and the returned metrics (views, unique views). It does not discuss pagination or rate limits, so not a 5.

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

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

The description is three sentences, front-loaded with the core action and resource, then the return value, then the access constraint and use case. Every sentence adds distinct value with no redundancy or filler.

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

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

Given the output schema exists, the description need not explain return values in full, and annotations cover safety. The description supplies critical context (owner-only auth, per-page metrics, use case) but omits any mention of pagination or time-range filtering behavior, which are present in the schema and may be relevant for correct invocation.

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

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

Schema description coverage is 100%, so all five parameters including doc_id, limit, cursor, since_date, and until_date are already documented in the schema. The description adds no further parameter-level detail, which is the expected baseline when schema coverage is high.

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

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

The description states a specific verb (List) and resource (page analytics within a doc), and clarifies that it returns per-page usage metrics rather than doc-level analytics. This clearly distinguishes it from sibling tools like coda_list_doc_analytics and coda_get_doc_analytics_summary.

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

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

It provides a clear prerequisite ('Only available to doc owners') and a use case ('Useful for understanding which pages get the most traffic'), giving context for when to use it. It does not explicitly name alternatives or when-not-to-use conditions, which keeps it from a 5.

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

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

With readOnlyHint/idempotentHint already covering the safety profile, the description still adds substantive behavior: return contents (name, ID, parent, icon), tree ordering, and the ID-not-name contract for later calls. It stops short of describing pagination semantics (limit default 50, cursor round-trip), which would be the remaining behavioral detail.

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

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

Four short sentences, front-loaded with the core action, then exclusions, then the downstream convention. No filler; each sentence changes agent behavior.

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

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

An output schema exists, yet the description still summaries the returned fields and ordering, and closes the loop on how to use the returned IDs. Nothing needed to call this correctly or chain it is missing.

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

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

Schema description coverage is 100%, so limit, cursor, and doc_id are already documented in the schema with defaults, bounds, and meaning. The description adds no parameter-level syntax or format detail beyond that, so the baseline 3 is appropriate.

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

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

States a specific verb+resource ('List all pages in a Coda doc') and immediately bounds scope by naming what it does not return (page content) versus coda_get_page_content. An agent can distinguish it from coda_get_page, coda_list_docs, and coda_get_page_content without opening any schema.

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

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

Explicitly routes the agent: 'Does NOT return page content — use coda_get_page_content for that,' and adds the downstream rule 'Use the returned page IDs (not names) for all subsequent page operations.' Both the alternative and the follow-up convention are stated outright.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint, so the safety profile is covered and the bar is lower. The description still adds useful information beyond them, spelling out the shape of each entry (principal plus permission type) and the possible access levels (read, write, etc.). It does not mention pagination behavior or any permission/auth prerequisites for the read.

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

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

Four short sentences, front-loaded with the core action and scope before the return details and the alternative-tool routing. Tight and readable, with only mild redundancy given that an output schema already describes the returned fields.

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

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

With an output schema present and annotations covering the read-only/idempotent/open-world profile, the description need not explain return values. It is complete enough to call correctly, though it omits whether pagination is required for large docs and any permission prerequisites for reading ACLs.

Complex tools with many parameters or behaviors need more documentation. 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% (limit, cursor, doc_id are all documented), so the schema already carries parameter meaning. The description adds no syntax, format, or default details beyond what the schema provides, which is the baseline expectation.

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

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

States a specific verb and resource ('List all permission entries (ACL) for a Coda doc') and immediately clarifies what those entries are (who has access, their access level, the principal). It also names the mutation siblings (coda_add_permission, coda_delete_permission), so an agent can place the tool without opening the schema.

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

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

The description gives explicit routing for the write side of permissions: use coda_add_permission to grant or coda_delete_permission to revoke. It does not, however, differentiate this read tool from the overlapping coda_get_acl_settings or coda_get_sharing_metadata siblings, so the when-to-choose guidance is clear but incomplete.

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

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

Annotations already declare readOnly/idempotent/openWorld, so the safety profile is carried. The description adds real behavioral context the annotations do not: results are paginated with a cursor, and column names are used by default in returned values. It stops short of documenting rate limits or page-size behavior beyond the limit default.

Agents need to know what a tool does to the 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 short sentences, front-loaded with the primary action, then the alternative, then pagination. No filler; each sentence adds a distinct operational fact.

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

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

With an output schema present, the description need not explain return values, and it covers the remaining gaps an agent needs: filtering, sorting, default column naming, and cursor-based pagination. Nothing required to call it correctly is missing.

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

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

Schema description coverage is 100% and the schema already documents query, sort_by, cursor, response_format, and use_column_names with examples and defaults. The description's mentions (query filters by column values, names vs IDs) largely restate the schema, so the baseline 3 applies.

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

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

States a specific verb+resource+scope ('List rows in a Coda table') and adds the dimensions of filtering and sorting, which distinguishes it from sibling write/read tools. It also explicitly routes the singular-row case to coda_get_row, so an agent can pick it without opening either schema.

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

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

Gives explicit conditions: use query to filter, use coda_get_row instead for a single row by ID, and pass cursor to page. However, it does not cover when-not-to-use beyond the single-row alternative (e.g. limit tradeoffs or when to prefer table-level tools), so it falls just short of the top tier.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the safety profile needs no restatement. The description adds valuable substance beyond them by declaring the returned content domain ('name, ID, type, row count, and parent page') and an explicit exclusion (no row data), which prevents misuse.

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

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

Three short sentences, front-loaded with the core action and then routing information. Every sentence carries a distinct job: what it lists, what it excludes, and where to go next — no filler.

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

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

With a full output schema present, the description need not detail the response shape, and it correctly avoids doing so beyond a short content summary. Combined with complete parameter docs and annotations, nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is 100%, so doc_id, limit, cursor, and table_types are all fully documented in the schema itself. The description adds no parameter meaning beyond listing the doc as the target, so the baseline of 3 is appropriate.

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

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

States a specific verb and resource ('List all tables and views in a Coda doc') and immediately scopes the resource by clarifying it enumerates table/view objects, not their contents. It distinguishes itself from closely-named siblings by naming coda_list_rows and coda_list_columns.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 what this tool does NOT do ('Does NOT return row data — use coda_list_rows for that'), then names a second alternative (coda_list_columns) with the condition that selects it. Both when-to-use paths and the negative case are covered.

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

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

Annotations only declare readOnlyHint=false and openWorldHint=true, so the description usefully adds the key side effect that the doc becomes publicly reachable via a URL and that the change is reversible via coda_unpublish_doc. It stops short of stating permission requirements or whether publishing overwrites prior settings.

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

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

Short and front-loaded with the core action, and the revert pointer is well placed. There is mild redundancy between the opening line and 'Publishes the doc ... becomes accessible via a public URL', which repeats the same idea.

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

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

With an output schema present, the return values need not be explained, yet the description still notes it returns the URL and settings. Combined with full schema coverage and safety-relevant annotations, the agent has enough to invoke it; only permission/prerequisite context is missing.

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

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

Schema description coverage is 100%, so all five parameters (mode, slug, doc_id, discoverable, category_names) are already documented in the schema. The description only loosely gestures at 'optional gallery listing and URL slug', which adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Publish a Coda doc') and its outcome ('make it publicly accessible'). It distinguishes itself from the sibling coda_unpublish_doc by naming it as the inverse operation, so an agent can route between publish/unpublish without opening either schema.

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

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

Gives clear context for use ('make it publicly accessible') and an explicit alternative for the opposite action ('Use coda_unpublish_doc to revert'). It does not state prerequisites (e.g. required permissions or ownership) or when-not to publish, so it falls short of a full when/when-not/alternatives treatment.

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

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

Annotations already declare this is a non-read-only, open-world mutation, but the description adds meaningful context beyond them: the effect is config-dependent and unknowable ahead of time, and the call returns a requestId for async mutation tracking. That async/idempotency-relevant detail is genuinely useful for a mutating 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 core action is front-loaded in the first sentence, and each subsequent sentence adds a distinct fact (trigger semantics, precondition, return value) with no redundancy. It is appropriately sized for a four-parameter mutation tool.

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

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

With an output schema present and annotations covering the safety profile, the description supplies the necessary extras: the precondition, the config-dependent effect, and the async-tracking requestId. The main remaining gap is routing guidance against coda_trigger_automation, but the operational picture is complete.

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

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

Schema description coverage is 100%, so all four parameters are already documented in the schema (doc_id, table_id_or_name, row_id_or_name, column_id_or_name). The description adds the constraint that column_id_or_name must point to a Button-type column, but this is already stated elsewhere in the prose, so it stays at the baseline 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 states a specific verb (push) and resource (a button in a Coda table row) and explains the resulting action (runs the button's configured automation or modifies the row). It is clear what the tool does, though it does not explicitly distinguish itself from the sibling coda_trigger_automation, which an agent might confuse it with.

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

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

It provides a precondition (the target must be a Button-type column) that implies when the tool is applicable, but it never states when to prefer this over the closely related coda_trigger_automation or other mutation tools. Usage is implied rather than explicitly guided.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint, so the safety profile is covered. The description adds useful behavioral context — it resolves to specific resource kinds and returns a type discriminator — though it says nothing about auth or failure behavior on malformed URLs.

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

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

Three short sentences, front-loaded with the core action, then sources, then routing rule. No filler.

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

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

An output schema exists, so return-value detail is not required, yet the description still usefully previews the type field. It is nearly complete for a single-parameter resolver, missing only edge-case behavior.

Complex tools with many parameters or behaviors need more documentation. 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 url parameter is already documented. The description adds value by naming the accepted URL sources (address bar, shared link) and the set of resource types the URL may point to, going beyond the schema's single-line description.

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

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

States a specific verb (resolve/convert) and resource (browser URL → API IDs), and enumerates the target resource kinds (doc, page, table, row, column). No sibling tool performs URL-to-ID resolution, so the purpose is unmistakable among the listed tools.

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

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

"Use this as the first step when a user provides a Coda URL instead of IDs" gives a clear triggering condition. No alternatives are named, but none exist among the siblings, so no exclusion guidance is needed.

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