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

Annotations only supply readOnlyHint=false and openWorldHint=true, so the description carries most of the burden and does add real context: it discloses the side effect that access 'none' removes existing implicit access rather than merely setting a level, and that a permission entry is returned. It omits auth/permission prerequisites (who may grant access) and the default notification behavior is left to the schema, so it is strong but not complete.

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 action, then constraints, then enum semantics, then the return value. No sentence is filler and none restates the schema verbatim.

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

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

With no output schema, explaining that the created permission entry is returned is the right call, and the mutation's side effects are covered. Missing only operational context an agent might want — required permission level to grant access and whether notifications fire by default (implied only through 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%, so the baseline is 3, but the description genuinely adds meaning the schema does not: it declares principal_email and principal_domain mutually exclusive, and it glosses the 'none' enum value as removing implicit access. That is value beyond the structured fields.

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

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

States a specific verb and resource ('Add a permission entry to a Coda doc') and immediately scopes what the operation does — grants access to a user or domain. This is clearly distinguishable from sibling tools like coda_list_permissions and coda_delete_permission without opening any schema.

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

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

Gives the operative selection rule for the two principal parameters — 'Specify either principal_email or principal_domain (not both)' — which is genuine when-to-use guidance. It does not explicitly route the agent away from siblings (e.g. use coda_delete_permission to revoke, coda_search_principals to find a user first), so it stops short of full alternative 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 declare a write operation (readOnlyHint=false, openWorldHint=true); the description adds value beyond them by stating the return payload (doc ID, name, browser URL), the default destination when folder_id is omitted, and the cloning behavior. It omits permission/auth requirements and any rate limits, which keeps it short of a 5.

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

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

Four short sentences, front-loaded with the core action before the modes and defaults. Slight redundancy between the opening two sentences ('Create a new Coda doc' / 'Creates a blank doc or a copy'), but no padding.

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

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

For a write tool with no output schema, the description covers the essentials: what is created, the two creation modes, destination defaults, and what is returned. 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 all three parameters are already documented. The description's 'omit for root' and 'clone as a template' framings largely restate the schema wording rather than adding new syntax or constraints. 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 new Coda doc) and clarifies the two modes (blank vs. clone from source_doc). An agent can distinguish this from coda_create_page, coda_create_folder, and coda_update_doc without opening schemas.

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

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

Explains when to use source_doc (cloning an existing doc as a template) and where the doc lands (specified folder, else user root). No explicit when-not guidance or sibling routing (e.g., 'if you want a page, use coda_create_page'), but 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=false and openWorldHint=true, so the mutating nature is covered. The description adds useful output context ('Returns the new folder's ID and metadata') in the absence of an output schema, but discloses nothing about permissions, workspace requirements, or failure modes.

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 opening two sentences are largely redundant — 'Create a new folder in a Coda workspace' and 'Creates a folder in the specified workspace' restate the same fact. The return-value and usage notes earn their place, but the overlap wastes space and blurs the front-loading.

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, fully-documented create tool, the description covers purpose, the returned value, and a follow-up usage path, which is enough to invoke it correctly. Missing only edge-case behavior (naming conflicts, permission requirements), which is minor at this complexity level.

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 fully documents name, description, and workspace_id. The description adds no syntax, format, or constraint details beyond what the schema already provides, so the baseline 3 is appropriate.

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

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

The description states a specific verb and resource ('Create a new folder in a Coda workspace') that clearly distinguishes it from the list/get/update/delete folder siblings. It also names coda_create_doc as the downstream consumer of the returned folder ID. It stops short of explicitly contrasting its scope against siblings beyond that link.

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

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

It gives workflow context ('Use the folder ID when creating docs with coda_create_doc to organize them'), which implies when the tool fits into a broader flow. However, it offers no explicit when-to-use/when-not guidance, prerequisites, or comparison to alternatives like update_folder or delete_folder.

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 mutation profile (readOnlyHint=false, openWorldHint=true), so the bar is lower. The description still adds real behavioral context: default top-level placement, the returned ID/metadata, and the notable constraint that pack formulas cannot be inserted via the API. Auth/permission requirements are not stated, keeping it from a 5.

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

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

Four short sentences, front-loaded with the primary action, and every sentence carries distinct information (purpose, return value, nesting default, format control, limitation). 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 no output schema, the description helpfully states what is returned (ID and metadata), and it covers formats, nesting, and a key API limitation. It does not mention permissions or failure modes, but for a create tool against rich annotations and a fully documented schema, it is nearly complete.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds relational semantics the per-parameter schema does not: parent_page_id defaults to top-level nesting, and content format is controlled jointly by content and content_format. That interplay is genuinely useful beyond the individual field descriptions.

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

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

States a specific verb+resource ('Create a new page in a Coda doc') and is immediately distinguishable from siblings like coda_update_page, coda_get_page, and coda_create_doc. An agent can select it without ambiguity.

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 create intent is self-evident, and it implies usage context (nesting via parent_page_id, format via content_format). However, it names no alternatives and gives no explicit when-to-use/when-not guidance against siblings such as coda_update_page or coda_create_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 genuine value beyond that: it spells out the blast radius (pages, tables, data), confirms irreversibility, and notes a confirmation status is returned.

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, each earning its place: action, warning/blast radius, precondition. The irreversible warning is front-loaded where it matters most.

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 an irreversible single-parameter mutation, the description covers the action, the consequence, the safe pre-check, and the return shape. 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% with a single well-documented doc_id parameter. The description 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 ('Permanently delete a Coda doc'), which is clearly distinct from sibling page/row/folder delete tools. The adverb 'Permanently' immediately scopes the operation.

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

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

Gives an explicit precondition — verify the doc name with coda_get_doc before calling — which routes the agent through a safe read step. It does not name when *not* to use it versus other delete siblings, but the context is clear enough.

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 destructive=true and openWorld=true, so the mutation profile is covered; the description still earns credit by disclosing the cascading side effect that annotations cannot express — child docs "may be moved to the root level or deleted depending on Coda's behavior." The honest admission of uncertainty is useful, though it does not resolve what actually happens to the contents, which is exactly the risk an agent needs to price in.

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

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

Front-loaded with the action, then the return value, then the safeguard, then the side-effect caveat — a sensible order. "Delete a folder" and "Permanently removes the folder" restate each other slightly, but there is little waste overall.

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

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

For a one-parameter destructive tool with no output schema, the definition covers the action, the return payload, the recommended pre-check, and the destructive ripple effect. The only remaining gap is that the fate of contained docs is left as "depends on Coda's behavior," but the agent is at least warned of the 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% with a single required parameter already documented as "The folder ID to delete," so the schema does the full job. The description only echoes that a folder_id comes back; 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 ("Delete a folder from the Coda workspace") and even names the return payload ("confirmation with folder_id"). The resource "folder" cleanly separates it from the many other delete siblings (delete_doc, delete_page, delete_row, delete_permission).

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 through a precondition ("Verify the folder with coda_get_folder before deleting"), which names a sibling and the condition for using it. It stops short of stating when NOT to delete or what alternatives exist for archiving/moving instead, so it is clear context rather than full when/when-not guidance.

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

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

Annotations already flag destructiveHint=true and readOnlyHint=false, but the description adds genuinely new behavioral detail: the operation is irreversible, all page content is removed, and child pages are reparented to the deleted page's parent. That side-effect disclosure exceeds what the annotations convey.

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 irreversibility warning, followed by the side effect 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?

For a destructive two-parameter tool with no output schema, the description covers the action, irreversibility, side effects on child pages, and a verification step. Nothing material is missing for correct invocation.

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

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

Schema coverage is 100% and both parameters (doc_id, page_id_or_name) are documented in-schema. The description adds no syntax, format, or lookup guidance for the parameters, 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 page from a Coda doc'), and the detail about child-page reparenting clarifies it acts on the page node itself rather than its contents, distinguishing it from siblings like coda_delete_page_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?

Provides a clear pre-call prerequisite — 'Verify the page name with coda_get_page before calling this' — naming a sibling tool to use first. It does not explicitly contrast when to use page deletion vs. coda_delete_page_content (delete content but keep the page), so a 5 is not warranted.

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 mark this as destructive and non-read-only. The description adds important behavioral context beyond the annotations: exactly what is removed (text content), what remains (page, name, metadata), and that the operation is irreversible.

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

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

The description is compact and front-loaded with the core action and its boundary. Each sentence adds useful information: scope, what is preserved, irreversibility, and the alternative tool.

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

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

For a two-parameter destructive operation with full schema coverage, destructive annotations, and no output schema, the description supplies everything an agent needs to call it correctly and avoid confusion with page deletion.

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 are fully documented in the input schema. The description does not add syntax, format, or edge-case meaning beyond what the schema already provides, so the baseline of 3 is appropriate.

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

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

The description states a specific verb and resource: deleting all content from a page. It explicitly distinguishes the operation from deleting the page itself, so an agent can tell it apart from sibling tools like coda_delete_page.

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 clearly explains when to use this tool versus coda_delete_page: use this to blank a page while keeping the page, and use coda_delete_page to remove the page entirely. The alternative and its selecting condition are named explicitly.

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, readOnlyHint=false, and openWorldHint=true, so safety is covered. The description adds genuinely new behavioral context, namely the caveat that the principal loses access only unless covered by another permission such as domain-level. It does not mention reversibility or auth requirements, 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?

Four short sentences, action front-loaded, then effect, then caveat, then prerequisite. No repetition of the title and nothing extraneous.

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

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

For a two-parameter mutation with no output schema, the description covers the operation, its effect, and the prerequisite. Annotations carry the safety profile. Only minor gaps remain, such as what the response confirms after deletion.

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, giving a baseline of 3. The description adds real value beyond the schema by naming the source of permission_id (coda_list_permissions), which clarifies how to obtain a valid value.

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

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

States a specific verb and resource ('Remove a permission entry from a Coda doc') plus the effect ('Revokes the specified permission'). An agent can distinguish this from coda_add_permission and coda_list_permissions without opening any schema.

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

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

Gives an explicit prerequisite and routing hint: 'Get the permission_id from coda_list_permissions first,' pointing at the sibling that produces the required ID. It lacks explicit when-not guidance (e.g. when to prefer changing a permission level over deleting it), so it stops short of a 5.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is partly structured. The description still adds real behavioral value by spelling out that removal is permanent and irreversible, plus the recommended verify-before-delete workflow. It stops short of noting auth/permission requirements or what happens to row references, which keeps it from a 5.

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

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

Three short sentences, front-loaded with the action, then consequence, then the safety workflow and escape hatch to the bulk sibling. No padding 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?

For a destructive single-row delete with fully documented params and annotation coverage, the description closes the important gaps: irreversibility, verification prerequisite, and the bulk alternative. Nothing an agent needs to invoke it safely is missing, and no output schema is expected for a delete.

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 all three required parameters documented (doc_id, table_id_or_name, row_id_or_name), so the baseline is 3. The description adds no syntax, format, or name-vs-ID nuance beyond what the schema already states.

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 single row from a Coda table') and explicitly scopes it to ONE row, which is exactly what distinguishes it from the sibling coda_delete_rows. 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?

Names the alternative explicitly ('For bulk deletion, use coda_delete_rows with a list of row IDs instead') and adds a pre-flight verification step with coda_get_row. Both when-to-use and when-not-to-use are covered with concrete conditions.

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

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

Annotations already declare destructiveHint=true, so the safety profile is partly covered, but the description adds genuinely new context: irreversibility ('Permanently removes all specified rows. This is irreversible') and the async contract ('Returns a requestId for async mutation tracking'). It stops short of naming required permissions or whether partial failures roll back.

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 destructive scope, then prerequisite, return behavior, and the alternative. Every sentence carries distinct information; 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 no output schema, the description correctly supplies the return value (requestId for async tracking), the prerequisite lookup, the irreversibility warning, and the sibling preference. An agent has everything needed to call and follow up correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds only one piece of parameter meaning — that row_ids values come from coda_list_rows — and says nothing about doc_id or table_id_or_name formats, so it does not exceed the schema.

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

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

States a specific verb+resource with an explicit batch scope ('Delete multiple rows from a Coda table in a single call'), which immediately separates it from the singular coda_delete_row sibling. An agent can select correctly without opening the schema.

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

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

Gives an explicit prerequisite ('List the rows first with coda_list_rows to get their IDs') and an explicit alternative with the condition that selects it ('Prefer this over calling coda_delete_row in a loop for better performance and 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 only declare readOnlyHint and openWorldHint, so the description must carry the operational detail — and it does, disclosing the async job semantics, that small pages may return content inline, and that large pages yield an id requiring a status poll. It stops short of discussing export quotas, latency, or whether repeated exports are deduplicated, keeping it just below a 5.

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

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

Three short paragraphs, front-loaded with the operation and its async nature, then the polling path, then the routing advice as a closing preference. Every sentence carries distinct information with no restatement of the name or title.

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

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

There is no output schema, yet the description explains what comes back in both branches (immediate content vs. an id for polling) and names the sibling that consumes that id. Combined with the schema's full parameter coverage, an agent has everything needed to call this tool and handle its result 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 all three parameters (doc_id, page_id_or_name, output_format) are documented in the schema itself, so the baseline of 3 applies. The description hints at format relevance via 'embedded images resolved' but adds no format syntax, defaults, or page-name resolution rules beyond the schema.

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

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

States a specific verb and resource: 'Export a page's content, initiating an async export if needed.' It immediately differentiates itself from the closest sibling by framing the operation as a heavier full export rather than a quick read, so an agent can distinguish it from coda_get_page_content without opening either schema.

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

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

Explicitly routes the agent: 'Prefer coda_get_page_content for quick reads — use this only when you need a full export with embedded images resolved.' It also names the follow-up tool, coda_get_export_status, and states the condition that triggers it (large pages), giving when-to-use, when-not-to-use, and the alternative in a single paragraph.

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 context beyond that: it enumerates what the settings actually contain (copying allowed, editor permission changes, default access mode), which gives the agent a concrete sense of the payload.

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 response is compact and front-loaded: the purpose sentence leads, followed by a scope-clarifying sentence. Both sentences carry information and there is no filler, though the second sentence is slightly verbose for the value it adds.

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

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

With no output schema, the description compensates by naming representative fields returned in the settings, so an agent knows roughly what to expect. For a one-parameter read tool this is nearly complete, with only the comparison to sharing metadata 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?

There is a single parameter with 100% schema description coverage, so the schema fully documents doc_id. The description adds no additional format or acquisition detail for the parameter, 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?

States a specific verb and resource ('Get the ACL settings for a Coda doc') and clarifies the scope is administrative doc-level settings rather than individual permission entries, which routes the agent away from coda_list_permissions. It does not explicitly distinguish itself from the close sibling coda_get_sharing_metadata, leaving some ambiguity.

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

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

The description implies usage context by contrasting administrative settings with permission entries, giving a degree of implicit guidance. However, it never states when to choose this tool over coda_get_sharing_metadata or coda_list_permissions, and offers no prerequisites or conditions.

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

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

Annotations already declare readOnlyHint, openWorldHint and idempotentHint, so the safety profile is covered. The description adds genuinely useful context beyond that: analytics are not real-time and refresh every few hours. With no output schema, stating 'Returns a timestamp' is a helpful 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 short sentences, front-loaded with the core action. Minor redundancy: 'Get the timestamp of when analytics data was last updated' and 'Returns a timestamp indicating the freshness' say nearly the same thing.

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, no-output-schema tool, the description covers what it returns (a timestamp) and why it matters (freshness before time-sensitive decisions). Adequate; only the lack of explicit sibling routing keeps it from being fully 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate and it correctly stays silent on inputs. Baseline 4 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 timestamp of when analytics data was last updated.' The purpose is self-evidently distinct from the analytics-listing siblings (coda_list_doc_analytics, coda_get_pack_analytics_summary), but the description never names or contrasts those siblings explicitly.

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 usage context: 'Check this before relying on analytics data for time-sensitive decisions.' This tells the agent when the tool is worthwhile, though it names no alternative and states no exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint, so the safe-read profile is covered structurally. The description adds value beyond that by enumerating the returned fields (name, ID, type, format, configuration), which matters given there is no output schema. It stops short of noting failure behavior for a missing column, so 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?

Four short sentences, each earning its place: purpose, return contents, primary use case, and the alternative. Purpose is front-loaded and nothing is padded or repeated.

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

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

With no output schema, the description compensates by listing the returned fields, and annotations carry the safety/idempotency profile. Parameters are fully covered by the schema, so nothing an agent needs to call this read 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 all three parameters (doc_id, table_id_or_name, column_id_or_name) are already documented in the schema. The description only implies that column_id_or_name identifies "a single column" and adds no new naming/format semantics beyond what structured data provides, 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 and resource ("Get metadata for a single column") and immediately scopes it to one column versus the whole table. It explicitly distinguishes itself from the sibling coda_list_columns, so an agent can select between them without opening either schema.

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

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

Gives an explicit use case ("check a specific column's type before writing data to it") and names the alternative tool plus the condition that selects it ("For the full column schema, use coda_list_columns 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 readOnlyHint, openWorldHint, and idempotentHint, so safety is covered. The description adds value beyond that by disclosing the returned fields (name, ID, type, value), the control types covered, and that the value reflects current user-facing state — all useful since no output schema exists.

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 a compact list of returned fields and a routing hint. Slight redundancy between the returned-fields sentence and 'the value reflects the current user-facing state,' but no significant waste.

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-parameter read with no output schema, the description covers purpose, return fields, and the discovery path adequately. It omits only minor edge-case behavior such as what happens when a control is not found, which keeps it short of a 5.

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 doc_id and control_id_or_name are already documented in the schema. The description adds no syntax or format guidance 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?

States a specific verb and resource ('Get the current value of a control in a Coda doc') and enumerates what a control is, so the agent can distinguish it from sibling tools like coda_list_controls or coda_push_button. 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?

Explicitly routes discovery to 'coda_list_controls' and clarifies that the returned value is the current user-facing state. It gives clear context for when this tool applies, though it does not state when-not to use it (e.g., for button-press side effects, see coda_push_button).

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 behavioral value by enumerating exactly what comes back (name, owner email, folder, timestamps, doc size) and what does not, which is the main ambiguity for a metadata getter. It omits auth/permission requirements, but for a read-only call that is a minor gap.

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

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

Three short sentences, front-loaded with the core action, followed by return contents and then exclusions/alternatives. It is tight overall, with only slight redundancy in repeating the doc_id provenance that the schema already carries.

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

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

With no output schema, the description correctly compensates by listing the returned fields and explicitly bounding the scope. Combined with the annotation-declared safety profile and the 100%-documented single parameter, 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 coverage is 100% and the schema description already documents the single doc_id parameter, including its source. The description restates the same sourcing guidance, adding no format or constraint detail beyond the schema, 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 ('Get metadata for a single Coda doc by ID') and immediately distinguishes itself from the content-oriented siblings by naming coda_list_pages and coda_list_tables. An agent can select this over the many other coda_get_* tools without opening any schema.

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

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

Gives an explicit negative scope ('Does NOT return page content or table data') plus the named alternatives for that case, and tells the agent where the required doc_id comes from (coda_list_docs or coda_resolve_browser_link). Nothing about when-to-use 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 readOnlyHint, idempotentHint and openWorldHint, so safety and repeatability are covered. The description still adds value by disclosing that results are summed rather than listed and that scope is limited to 'all accessible docs', which explains why counts may differ from a naive total. It does not mention rate limits or caching, 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?

Two sentences: the first front-loads what is returned, the second routes to the alternative. No redundancy, no filler, and the aggregation semantics precede the disambiguation.

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

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

For a read-only aggregation tool with no output schema, the description usefully previews the returned metrics and clarifies scope and the sibling relationship. It is largely complete; only minor details such as default date-range behavior or response shape are 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 three filters (since_date, until_date, is_published) are documented with format and semantics in the schema itself. The description adds no further parameter meaning, 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 aggregated analytics summary') with an explicit scope, 'across all docs', that separates it from the per-doc scoped siblings. It also enumerates the metric categories returned (views, unique viewers, copies), so an agent knows what the tool produces without opening the schema.

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

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

Names an alternative tool, coda_list_doc_analytics, and the exact condition that selects it ('per-doc breakdown' vs 'high-level overview'). The when-to-use decision is fully resolved in the text.

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 cover safety (readOnly, idempotent, openWorld); the description adds substantial behavior beyond that: the terminal states inProgress/failed/complete, that downloadLink expires and must be re-fetched, that error explains failures, and that the request itself expires. This is exactly the added context annotations cannot supply.

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

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

Front-loaded with purpose and the request_id mapping, then the state machine, then the expiry caveat. Every sentence carries operational information; nothing is redundant with the schema or annotations.

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

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

There is no output schema, so the description correctly documents the returned fields (status, downloadLink, error) and their lifecycle. Combined with the polling and expiry guidance, an agent has everything needed to call and interpret this tool.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real value the schema cannot: it clarifies the naming mismatch that the `id` returned by coda_export_page must be passed as request_id. That resolves a genuine ambiguity for the agent.

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

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

States a precise verb+resource ('Check a page export') and immediately anchors it to the sibling that creates the request ('started by coda_export_page'). An agent can distinguish this from the other ~50 coda_* 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 defines when to call (after coda_export_page), the polling policy (every 2 s up to 30 s), the same cadence as coda_get_mutation_status, and the recovery path when 404/410 is returned (start a new export). Both when-to-use and failure handling 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 is covered. The description adds value by enumerating the return fields (name, ID, parent folder, child items), which is important since there is no output schema. It does not cover error behavior or permission requirements, but the annotations carry the main behavioral burden.

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 that are front-loaded with the core purpose, followed by return values and a routing hint. Every sentence earns its place with no redundancy.

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

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

For a simple single-resource getter with full schema coverage and annotations covering safety, the description is complete: it explains what is returned, and how to discover folder IDs. No output schema is present, and the description adequately covers the return shape.

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 parameter (folder_id) is documented in the schema. The description adds no additional syntax, format, or constraint details beyond what the schema already provides, 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 ('Get metadata for a single folder'), and the phrase 'single folder' distinguishes it from the sibling coda_list_folders. An agent can immediately tell it apart from list/update/delete/create folder 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?

Explicitly directs the agent to use coda_list_folders first to discover available folders, which is useful prerequisite context. However, it does not state when not to use this tool or contrast it with other sibling getters, so it falls short of full when/when-not guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the safety profile is covered. The description adds genuinely useful context beyond that: the return fields (name, ID, type, current value, error state) and the note that the value is computed by Coda and reflects the latest state, which explains the openWorld/live-computation 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?

Three short sentences, front-loaded with the core action, followed by return-value context and the sibling pointer. Efficient with no filler, though the second sentence is slightly enumerative.

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

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

With no output schema, the description usefully enumerates the returned fields, compensating for that gap. It is complete for a simple two-parameter read tool; only minor details like error semantics or permission requirements are unaddressed.

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

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

Schema coverage is 100%, with both doc_id and formula_id_or_name documented in the schema, so the schema carries the burden. The description only indirectly reinforces that formula_id_or_name accepts a name ('named formula') and adds no format or lookup semantics beyond the schema.

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

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

States a specific verb ('Get') and resource ('the current value of a named formula in a Coda doc'), and distinguishes itself from the sibling coda_list_formulas by describing what it retrieves versus what it enumerates. An agent can tell it apart from other coda_get_* 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 routes the agent: 'Use coda_list_formulas to discover available formulas in a doc,' which clarifies the discovery-vs-fetch workflow. It gives clear context for use but states no exclusions or preconditions (e.g., permissions needed to read formulas).

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, and the description is consistent with them. Beyond that it discloses the polling contract (2s interval, 30s ceiling), the failure states it distinguishes (completed / processing / failed) and the return shape ('completed boolean and any error details') that no output schema provides. It does not say what to do once the 30s budget is exhausted.

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 what the tool does, then the trigger, the return value and the polling budget. Every sentence carries distinct information and nothing is padded.

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

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

For a single-parameter polling tool with no output schema, the description covers the trigger, the lifecycle states and the return value, which is close to everything an agent needs. The one gap is the post-timeout behavior, which is left for the caller to guess.

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 request_id parameter is already documented in the schema as 'the requestId returned by a write operation (202 response)'. The description restates that same origin rather than adding format or sourcing detail, so the schema does the heavy lifting and 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 and resource ('Check the status of an asynchronous mutation') and scopes it to write operations, which distinguishes it in substance from the sibling polling tool coda_get_export_status. It stops short of naming that sibling explicitly, so the routing is inferable rather than stated.

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 triggering context ('Coda write operations return 202 with a requestId. Use this tool to poll...') plus concrete operational guidance (poll every 2 seconds, up to 30 seconds). It never states when not to use it or names the alternative status tool for exports, so it falls short of a full when/when-not/alternative 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 readOnlyHint/openWorldHint/idempotentHint, so the safety profile is covered. The description adds real value beyond that: it specifies the access restriction (pack makers only) and the aggregated nature of the result, which an agent cannot derive from the 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?

Two short sentences with zero filler, and the core action is front-loaded ahead of the return-value detail and access note. Nothing is padded, though the layout is slightly fragmented across lines.

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

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

With no output schema, the description compensates by naming the returned aggregates (installs, doc usage, formula invocations) and stating the access restriction. Combined with the fully documented schema, an agent has enough to invoke it correctly, though the missing distinction from coda_list_pack_analytics is a residual 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 all four parameters (pack_ids, since_date, until_date, is_published) are fully documented in the schema. The description adds no further parameter meaning, 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: 'aggregated analytics summary for packs,' and enumerates the metrics returned (installs, doc usage, formula invocations). It implicitly distinguishes from the sibling coda_list_pack_analytics by emphasizing aggregation/summary, though it never names that sibling.

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 prerequisite 'Only available to pack makers' is clear and useful context for eligibility. However, there is no explicit when-to-use guidance versus the closely related coda_list_pack_analytics or coda_get_analytics_updated, leaving the agent to infer the distinction between summary and list.

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 and idempotentHint, so the safety profile is covered; the description goes further by disclosing the exact return surface and, critically, that page names are mutable and unreliable. That instability caveat is genuine operational context an agent cannot get from 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?

Three short sentences with zero filler; the core purpose is front-loaded and the exclusion plus stability caveat follow in priority order. Every sentence changes how an agent would call the tool.

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

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

With no output schema, the description carries the burden of describing the return value and does so by naming the returned fields, which is exactly the missing piece. It omits error behavior (e.g. what happens if the page name is ambiguous or not found), which is a minor gap for a two-parameter read tool.

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

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

Schema coverage is 100%, so both parameters are already documented in the schema, which sets the baseline at 3. The description's "always use page IDs" mildly reinforces the schema's "prefer ID" note but adds no new syntax, format, or constraint information.

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 explicitly contrasts itself with the sibling coda_get_page_content, so an agent can distinguish the two without opening either schema. It also enumerates the exact metadata fields returned, leaving no ambiguity about scope.

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

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

Provides a clear negative condition ("Does NOT return the page's text content — use coda_get_page_content for that") plus a practical calling convention ("always use page IDs"). It does not explicitly address when to prefer this over coda_list_pages, so it falls just short of full when/when-not/alternatives 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 safety and repeatability are covered. The description adds useful behavioral context by warning that markdown output may be lossy for complex content such as embedded objects and pack formulas.

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 definition is front-loaded with the core action and stays brief, with each sentence contributing either format details, a lossiness caveat, or routing guidance. The second sentence partially restates what the name and schema already imply, but overall it is tight and readable.

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

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

For a read-only content retrieval tool with full schema coverage and no output schema, the description covers purpose, format, lossiness, and the main alternative. Minor omissions such as large-page truncation behavior or pagination are not critical for this tool.

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

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

Schema coverage is 100%, so the schema already documents doc_id, page_id_or_name, and output_format. The description adds meaning beyond the schema by noting the HTML/markdown choice and the trade-off that markdown can be lossy, which helps an agent choose the output_format value.

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

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

States a specific verb and resource ('Get the text content of a page in a Coda doc') and explicitly distinguishes itself from the closest sibling, coda_get_page, which is for metadata only. An agent can tell exactly what this tool returns without opening the schema.

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

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

Gives a clear use case ('reading page text') and names an alternative ('use coda_get_page for metadata only'). It does not address other potentially confusing siblings such as coda_export_page, so the routing guidance is clear but not exhaustive.

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 by stating that it returns all column values for the specified row, though it does not mention error behavior (e.g., row not found) or permission scope.

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

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

Three short sentences, front-loaded with purpose and return behavior, then usage constraint and alternative. Every sentence earns its place with no redundant or vague filler.

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

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

For a simple single-row read tool with rich annotations and complete schema coverage, the description supplies the needed scope, alternative routing, and return summary. Although no output schema exists, it states that all column values are returned, which is sufficient for correct invocation.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters including row_id_or_name and use_column_names. The description adds the ID/display-column-value distinction, but that is essentially repeated from the schema and it says nothing about use_column_names.

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 (single row from a Coda table), including the accepted lookup keys (row ID or display column value). It explicitly distinguishes itself from coda_list_rows, so an agent can route correctly without opening another 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 when to use it (when you have a specific row ID or know the display column value) and names the alternative for multi-row filtering (coda_list_rows). This gives clear when-to-use and when-not-to-use guidance.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, openWorldHint), and the description adds useful substance by defining what the metadata actually contains (shareability, copyability, restrictions). It stops short of noting permission requirements or error behavior, so it is strong but not exhaustive.

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

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

Three short sentences, front-loaded with the core action, then the return semantics, then the disambiguation. No filler and no repetition of the title.

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

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

There is no output schema, and the description compensates by stating what the call returns and what it does not. For a single-parameter read tool with full annotation coverage, nothing an agent 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?

Only one parameter (doc_id) with 100% schema description coverage, so the schema already carries the meaning. The description adds nothing about the ID's format or origin, which is the correct baseline when structured data 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 distinguishes itself from the closest sibling by naming coda_list_permissions as the tool for access lists. An agent can select it without opening any schema.

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

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

Gives an explicit when-not rule ('not the list of who has access') and routes to the correct alternative ('use coda_list_permissions for that'), which is exactly the confusion this tool name could create against its permissions siblings.

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

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

With readOnlyHint/idempotentHint annotations covering the safety profile, the description adds genuine value by enumerating what is returned (name, ID, type, row count, parent page, sort/filter info) and what is not. It does not mention auth requirements or pagination, but for a read-only metadata call the disclosure 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?

Two tight sentences, front-loaded with the core action and followed by the return scope and the exclusion. 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?

There is no output schema, so the description correctly compensates by summarizing the returned fields. Combined with the negative scoping and the read-only annotations, an agent has enough to call it correctly; only auth/pagination behavior is unaddressed.

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

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

Schema description coverage is 100%, with both doc_id and table_id_or_name documented in the schema, so the baseline is 3. The description adds no extra detail on ID vs. name resolution or format, leaving the schema to do all 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?

Names a specific verb and resource ('Get metadata for a single table or view') and scopes it to one entity in a doc. The description also draws a boundary against sibling tools by naming coda_list_rows and coda_list_columns, so an agent can distinguish 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 states what the tool does NOT do ('Does NOT return row data or column definitions') and routes the agent to coda_list_rows and coda_list_columns for those cases. It stops short of stating when to prefer this over coda_list_tables for enumerating tables, so it is clear but not fully exhaustive.

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 carries real extra weight: the 500-row cap, the column-name (not ID) requirement, the destructive update semantics of upsert, and the async 202 behavior with a requestId tracked via coda_get_mutation_status. These are exactly the operational facts an agent needs before calling a mutating bulk 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?

Four short sentences, front-loaded with the core action and upsert caveat, then limits, then async/return behavior. Every sentence carries information an agent needs.

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

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

Despite no output schema, the description explains the return contract (requestId for async tracking) and the status-check sibling, plus limits and formatting constraints. Nothing essential for correct invocation is missing.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds non-obvious semantics not in the schema: cells must use column names rather than IDs, and key_columns is the only path to bulk-update. That is meaningful added value over the structured fields.

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 ('Insert one or more rows into a Coda table') and immediately qualifies it with the upsert variant. An agent can distinguish this from siblings like coda_update_row and coda_delete_rows 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?

Gives clear routing guidance: key_columns enables upsert and 'this is the only way to bulk-update rows,' which steers the agent away from row-by-row update tools. It does not state explicit exclusions (e.g., when to prefer coda_update_row), 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 declare readOnly, idempotent, and openWorld, so safety semantics are covered. The description adds value beyond them by disclosing the shape of the result ('Each category has a name and ID'), which matters because there is no output schema.

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

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

Three short sentences, front-loaded with the action and scope, then the return shape, then the downstream consumer. Every sentence carries distinct 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 zero-parameter, read-only list tool with no output schema, the description supplies the missing return-shape information (name and ID) and the integration point (coda_publish_doc), leaving nothing an agent needs 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?

The tool takes zero parameters, so per the rubric the baseline is 4; there is nothing for the description to disambiguate and it correctly adds no spurious parameter talk.

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

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

Specific verb ('List') plus a precisely scoped resource ('publishing categories in Coda'), and it clarifies these are gallery-publishing categories rather than doc/folder/page categories. An agent can distinguish it from the many other list_* siblings at a glance.

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 the downstream use: 'Use these category IDs with coda_publish_doc,' which routes the agent to the correct consumer tool. It does not state any when-not conditions or prerequisites, but the positive usage 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 cover the safety profile (readOnlyHint, idempotentHint, openWorldHint), so the bar is lower, and the description still adds real context: the shape of the returned metadata and the caveat that column IDs are internal identifiers that should not be used with row data. It stops short of disclosing pagination behavior, which matters because limit/cursor exist.

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 layers return shape and the ID-vs-name caveat in three short sentences. Every sentence carries information, though the parenthetical type list ('text, number, date, etc.') is slightly loose padding.

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

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

With no output schema, the description does the work of describing the return payload (name, ID, type, configuration) and its purpose as a schema pre-check, which is the key thing an agent needs. The notable omission is any mention of pagination despite the cursor/limit parameters and a default limit of 100.

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 four parameters (doc_id, table_id_or_name, limit, cursor) are documented in the schema itself. The description adds no format, naming, or scoping detail about the parameters, so it does not go beyond the structured data.

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 immediately characterizes the result as the table schema, which separates it from row-level siblings like coda_list_rows or coda_insert_rows. It also implicitly contrasts with coda_get_column (single column) by scoping to 'all 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?

Gives an explicit workflow trigger: 'call this before inserting or updating rows to know the available columns and their types.' It also advises using column names rather than IDs when working with row data. It does not, however, say when to prefer coda_get_column or coda_list_tables over this tool, so no true alternatives/exclusions 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 genuine context by enumerating what the operation actually returns (name, ID, type, current value) and clarifying that controls are interactive UI elements on pages. It does not discuss pagination behavior, but the schema carries that.

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, zero filler, with the scope statement front-loaded and the return contents and alternative tool following in priority order. Nothing is wasted and nothing important is 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?

There is no output schema, so the description usefully compensates by summarizing the returned fields. Parameter behavior is fully covered by the 100%-coverage schema. The only minor gap is that pagination sequencing (limit/cursor usage across calls) is never mentioned, but the schema defaults make this inferable.

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, limit, cursor) are documented in the schema itself. The description adds no syntax or format detail beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource ('List all controls ... in a Coda doc') and immediately disambiguates the resource with concrete examples (sliders, select lists, date pickers). An agent can distinguish this from coda_get_control 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 names the alternative tool and the condition that selects it: 'Use coda_get_control to read a specific control's current value,' which implies this tool is for enumerating controls rather than reading one. That is a clear when-to-use/when-to-use-the-other routing 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 useful behavioral context beyond annotations: the owner-only access restriction and the list of returned engagement metrics. It does not discuss pagination behavior, but the schema handles that.

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, tightly scoped, and every sentence earns its place: it states what is listed, what is returned, who can use it, and which sibling handles the alternative case. There is no redundant or vague language.

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

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

For a read-only list tool with rich schema coverage, annotations covering safety, and no output schema, the description supplies what is missing: the metric types returned, the owner-only constraint, and the routing rule to the summary sibling. Nothing needed to select or invoke the tool correctly is absent.

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 six parameters are already documented in the input schema. The description only implies date-range filtering and adds no syntax, format, or default 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: 'List analytics data for docs (views, copies, likes, sessions).' It also names the sibling it is not: 'Use coda_get_doc_analytics_summary for aggregated totals instead of per-doc breakdown,' so an agent can distinguish it from related analytics 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?

It gives an explicit alternative and the condition that selects it: use this tool for per-doc breakdown, and use coda_get_doc_analytics_summary for aggregated totals. It also states the prerequisite 'Only available to doc owners,' which is essential for correct invocation.

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

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

Annotations already declare read-only, idempotent, and open-world behavior. The description adds meaningful behavioral context beyond annotations: the exact rate limit (4 calls per 6 seconds), the boundary that no page/table content is returned, and the pagination behavior.

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

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

The description is front-loaded with the main action, followed by return scope, exclusions, rate limit, and parameter usage. Every sentence carries useful information without padding.

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

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

With no output schema, the description compensates by naming the returned metadata fields (name, owner, folder, timestamps). Combined with annotations and a fully described input schema, the definition is complete enough to call correctly.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters thoroughly. The description only restates query for name search and cursor for pagination, adding little beyond the schema baseline.

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

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

The description states a specific verb and resource: list Coda docs accessible to the current API token. It also distinguishes this tool from coda_list_pages and coda_list_tables by explicitly saying it does not return page content or table data.

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 clearly routes the agent to alternatives for page content and table data, names those alternatives explicitly, and gives operational context such as rate limits, name searching via query, and cursor pagination.

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/openWorldHint, but the description adds real value beyond them: pagination behavior, the per-page default, the cursor mechanism, and the shape of returned metadata. Minor flaw: it claims the API "defaults to 25 per page" while the schema's limit default is 50, an inconsistency worth resolving.

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 core action and scope, then layers pagination and downstream usage. Every sentence is relevant, though the workspace-organizing aside is slightly tangential.

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

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

With no output schema, the description correctly compensates by describing returned fields (name, ID, parent folder) and pagination handling. A low-complexity list tool is adequately covered; only the page-size inconsistency detracts.

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 limit/cursor/workspace_id are already documented; baseline is 3. The description adds the cursor's usage purpose but also introduces a page-size default (25) that conflicts with the schema's limit default of 50, so it doesn't clearly improve on the schema.

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

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

States a specific verb and resource ("List folders accessible to the current API token") with an explicit access scope, which separates it from siblings like coda_list_docs and coda_get_folder at a glance.

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

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

Gives concrete downstream guidance ("Use the returned folder IDs with coda_create_doc to place new docs in specific folders") and explains the cursor workflow. It doesn't clarify when to prefer coda_get_folder or coda_search over listing, so it's clear context without explicit exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint, so safety is covered. The description adds real context beyond them: it defines what a 'named formula' is, notes these are doc-level rather than column-level values, and describes the returned metadata (name, ID, value) in the absence of an 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?

Three short sentences, front-loaded with the core action, then scope clarification, then the alternative tool. No filler and nothing repeated from structured 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 no output schema, the description usefully states the shape of returned metadata and the tool's scope. Pagination semantics are left to the schema's cursor description, which is acceptable, though a note on large docs or paging would make it fully self-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?

Schema description coverage is 100%, so doc_id, limit (1-200) and cursor are fully documented in the schema itself. The description adds no additional parameter meaning such as cursor lifecycle or default page size behavior, 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 all named formulas in a Coda doc') and immediately disambiguates scope by clarifying that named formulas are doc-level computed values, not column formulas. An agent can distinguish this from coda_get_formula and the column/table listing tools 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_get_formula 'to get a specific formula's current value,' which is a genuine alternative with a stated selection condition. It does not cover when to prefer other listing tools or how pagination should drive repeat calls, so it stops short of full when/when-not guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so safety and repeatability are covered. The description adds the valuable authorization constraint (pack-maker-only, own packs scope) and sketches the returned metric categories, going beyond what annotations convey, though it says nothing about pagination behavior or result ordering.

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, no redundancy, with the core purpose front-loaded and the access restriction following. Every sentence carries information the agent needs.

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

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

With no output schema, the description does take on the job of summarizing return content (install counts, doc usage, formula invocations) and states the permission boundary for a six-parameter, all-optional read tool. It is nearly complete, lacking only pagination/volume expectations that the cursor parameter implies.

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, pack_ids, since_date, until_date, and is_published are all documented in the schema with defaults and formats. The description adds no syntax, format, or interaction detail beyond that, 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?

The description gives a specific verb (List) and resource (analytics for Coda packs) and enumerates what the metrics cover: install counts, doc usage, and formula invocations. It is clearly a pack-scoped analytics reader, but it never explicitly distinguishes itself from nearby siblings like coda_list_pack_formula_analytics or coda_get_pack_analytics_summary, leaving the agent to 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?

It states a real precondition -- 'Only available to pack makers for their own packs' -- which tells the agent when the call will succeed. However, there is no guidance on when to prefer this over the aggregate (coda_get_pack_analytics_summary) or formula-level (coda_list_pack_formula_analytics) alternatives, so the when-to-use direction is only implied.

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

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

Annotations already declare readOnlyHint=true, so the safe-read behavior is covered. The description adds valuable context: the return content (invocation counts, error rates, execution times) and the pack-maker-only authorization requirement, which is behavioral context beyond what annotations convey.

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 waste, front-loading the core action and then the return payload and a critical constraint. Every sentence earns its place.

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

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

Given a read-only list tool with full schema documentation and no output schema, the description covers purpose, return fields, and access limitation. It would be fully complete if it clarified pagination behavior or edge cases, but it is sufficient 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 parameters (limit, cursor, pack_id, since_date, until_date) are documented in the schema itself. The description adds no parameter formatting or usage details beyond what the schema provides, 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 ('List analytics data') and a precise resource ('individual formulas within a pack'), clearly distinguishing it from siblings like coda_list_pack_analytics (pack-level) and coda_list_formula (formula metadata, not 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?

Provides the crucial access precondition ('Only available to the pack maker'), which helps an agent decide if the call will succeed. However, it does not explicitly name alternative tools or state when to prefer pack-level vs. formula-level analytics.

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 genuinely useful context beyond that: an authorization constraint (doc owners only) and the shape of the returned metrics (views, unique views). It omits pagination behavior despite 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 action and immediately followed by the return contents. The closing sentence about traffic is mildly promotional but does carry usage intent, so no major waste.

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

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

With no output schema, the description does partially carry the return-value burden by naming views and unique views, and it covers the access requirement. Missing pagination/date-range semantics and result ordering, which an agent would need for full confidence.

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 including limit, cursor, since_date and until_date is already documented in the schema. The description adds only that doc_id identifies the target doc, which the schema already states — 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 pages within a doc') and specifies the unit of analysis — per-page metrics — which separates it from the doc-level siblings coda_list_doc_analytics and coda_get_doc_analytics_summary. It stops short of naming those siblings explicitly, so the routing distinction is implied rather than stated.

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 prerequisite ('Only available to doc owners') and a motivating use case ('understanding which pages get the most traffic'), but never says when to prefer this over the other analytics tools in the sibling set, nor what to do when owner access is unavailable.

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), and the description adds genuinely new behavioral facts: pages come back in tree order, the response contains name/ID/parent/icon metadata, and content is deliberately excluded. It stops short of describing pagination behavior (cursor semantics, what happens when more pages exist than limit), so it is strong but not exhaustive.

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

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

Three short sentences, front-loaded with the core action and the negative scope, then the return shape, then the downstream ID rule. No filler and no repetition of the title.

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

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

With no output schema, the description usefully enumerates the returned metadata fields and ordering, which is what an agent needs to consume the result. The only remaining gap is pagination behavior, though the cursor parameter is self-documented in 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 every parameter (limit, cursor, doc_id) is already documented inline, including the 1-200 bound and the default of 50. The description adds no parameter-level meaning 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?

Opens with a specific verb+resource ('List all pages in a Coda doc') and immediately scopes it against the nearest sibling by stating it does NOT return page content and naming 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 names the alternative (coda_get_page_content) and the condition that selects it, and adds a follow-on usage rule ('Use the returned page IDs (not names) for all subsequent page operations'), which is exactly the kind of when-to-use guidance an agent needs for chained calls.

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 goes beyond them by disclosing the shape of the result: who has access, their access level (read/write), and that each entry includes a principal and permission type — useful because no output schema exists.

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, zero filler, with the core purpose and return shape front-loaded before the cross-tool routing sentence. Every sentence contributes something an agent can use.

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 three-parameter read tool with no output schema, the description supplies the essential return content (principal, permission type, access level) and sibling routing. It stops short of describing pagination flow across cursor calls, but the schema already documents limit/cursor semantics.

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

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

Schema description coverage is 100%, with limit, cursor and doc_id all documented inline including ranges and pagination intent, so the schema carries the load. The description adds no extra meaning about parameter behavior, 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?

States a specific verb and resource ('List all permission entries (ACL) for a Coda doc') and immediately scopes what an entry contains. It is clearly distinguishable from sibling ACL tools like coda_get_acl_settings and coda_get_sharing_metadata by naming the ACL/permission-entry object explicitly.

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_add_permission for granting and coda_delete_permission for revoking, which is clear complementary-action guidance. It does not, however, distinguish this tool from other read siblings such as coda_get_sharing_metadata or coda_get_acl_settings, so no true when-not-to-use boundary is drawn.

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 (readOnlyHint, idempotentHint, openWorldHint), so the description only needs to add context — and it does: pagination via cursor, the default of column names over IDs, and the presence of column values in results. It doesn't state what happens on an invalid cursor/query or rate-limit behavior, but that is a minor gap against 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?

Five short sentences, front-loaded with the core action and ending with the pagination mechanic; no filler. Slight redundancy in the query-parameter sentence, which largely echoes the schema, keeps it from being fully tight.

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 an 8-parameter read tool with no output schema, the description covers the essential call flows (filter, sort, paginate, column-name output) and the sibling handoff. It doesn't describe the shape of the returned rows beyond 'column values', but with no output schema that is a modest gap rather than a blocking one.

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 limit, query, cursor, sort_by, use_column_names, and response_format. The description restates the query-as-filter and column-names-by-default behaviors rather than adding syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('List rows in a Coda table') plus the supported modifiers (filtering, sorting), and explicitly names the sibling it is not (coda_get_row for a single row by ID). An agent can distinguish this from coda_insert_rows/coda_update_row/coda_delete_rows 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?

Gives clear context for the query parameter and routes the single-row case to coda_get_row, which is the one realistic ambiguity among siblings. It stops short of stating exclusions for the mutation siblings (insert/update/delete) or when to prefer list_tables/list_columns first, so it is clear but not exhaustive.

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 beyond that: the exact metadata returned (name, ID, type, row count, parent page) and the explicit exclusion of row data. It does not describe pagination behavior despite limit/cursor parameters, which is the only real gap.

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

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

Three short sentences, front-loaded with the core action, then the return shape, then the negative scope and alternatives. Every sentence earns its place with no redundancy.

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

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

With no output schema, the description usefully enumerates the returned fields and clarifies the read-scope boundary, which is the main thing an agent needs. Pagination semantics (limit 1-200, cursor chaining) are left entirely to the schema, so it is not quite complete for a paginated list tool.

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

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

Schema description coverage is 100%, so doc_id, limit, cursor, and table_types are already fully documented in the schema. The description adds no additional parameter meaning (e.g., it never mentions filtering by table_types or paging with cursor), 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 all tables and views in a Coda doc") and immediately scopes it against siblings by declaring it does not return row data and pointing to coda_list_rows and coda_list_columns. An agent can distinguish this from coda_list_rows, coda_get_table, and 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 names the alternative tools and the condition that selects them: use coda_list_rows for row data, use coda_list_columns for a specific table's schema. This is genuine when/when-not routing rather than implied usage.

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

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

Annotations only declare readOnlyHint=false and openWorldHint=true; the description adds the important consequence that the doc becomes publicly reachable and how discoverable escalates that exposure. It also discloses the return content (published URL and settings), which matters since no output schema exists. It does not mention required scopes/permissions or whether prior publish settings are overwritten, 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?

Three tight sentences, front-loaded with the core action and outcome, then the discoverability nuance and the revert path. No filler or restated title.

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 public-exposure mutation with no output schema, the description covers purpose, the key flag's effect, reversal, and return values. The remaining gap is permission/scope requirements and what happens on republish, which an agent might need for correct invocation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces the discoverable/gallery distinction and mentions URL slug, but adds no meaning for 'mode' or 'category_names' beyond the schema, and largely restates what the parameter descriptions already say.

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') along with the outcome ('make it publicly accessible'). It also names the sibling used to reverse it (coda_unpublish_doc), so an agent can place it among the doc-management tools 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?

Gives concrete context: publishing alone makes the doc public by link, while discoverable=True is a separate, more public gallery step, and coda_unpublish_doc reverts it. Missing is any exclusion against similar mutations (e.g. coda_update_doc, coda_add_permission) or prerequisite permissions, but the when-to-use condition and the alternative are clear.

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

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

Annotations already declare a mutating, open-world operation, and the description adds genuinely new behavior: the effect is non-deterministic and depends on the button's doc configuration, and the call returns a requestId for async mutation tracking. It does not mention permissions or error modes, but the async/non-deterministic disclosure is substantial.

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

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

Front-loaded with the action, then constraints, then return behavior — a sensible ordering with little waste. The second sentence ('The effect depends on the button's configuration') partially restates the parenthetical about the configured action, costing a point.

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

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

With no output schema, the description correctly compensates by naming the returned requestId and its async purpose, and it states the column-type precondition. It misses the obvious next step for the agent — that requestId is consumed by the sibling coda_get_mutation_status — so polling guidance is absent.

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 all four parameters are already documented in the schema. The description adds one constraint relevant to column_id_or_name (it must reference a Button-type column), but otherwise contributes no syntax or format 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 concrete verb and resource ('Push a button in a Coda table row') and explains what it causes ('triggers the button's configured action'). It is distinguishable from the many read/list siblings, though it never explicitly contrasts itself with the adjacent coda_trigger_automation.

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

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

Provides a real precondition ('The button must be in a Button-type column'), which tells the agent when the call is valid. However, it offers no guidance on when to prefer this over coda_trigger_automation or what to do when the target column is not a button 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 safety and repeatability are covered. The description adds value beyond them by disclosing the return shape (a type field plus resolved IDs) and the breadth of resource kinds handled. It omits error behavior for malformed URLs, 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 core action, then purpose, then usage, then return value; each sentence pulls weight. Slightly verbose with the parenthetical example, 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?

For a single-parameter read tool with no output schema, the description covers what it does, when to use it, and what it returns (type field and IDs). An agent has everything needed to invoke it correctly.

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

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

Schema coverage is 100% for the single url parameter, so the baseline is 3. The description marginally extends the schema by noting the URL can come from the address bar or a shared link, but adds no format or constraint details beyond that.

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) and resource (Coda browser URL to API resource IDs), and the scope is concrete: server, doc, page, table, row, or column. An agent can distinguish this from siblings like coda_get_doc, which take IDs rather than URLs.

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 the triggering condition: 'Use this as the first step when a user provides a Coda URL instead of IDs.' This clearly positions it relative to every ID-consuming sibling. It does not spell out exclusions or failure cases (e.g. invalid/non-Coda URLs), keeping it just 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 cover the safety profile (readOnlyHint, idempotentHint, openWorldHint), so the bar is lower; the description adds value by disclosing the return payload ('type, email, and name') in the absence of an output schema. It stops short of mentioning pagination, result limits, or matching semantics.

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

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

Three short sentences, front-loaded with the core action and followed by return content and the recommended next call. Slight redundancy between 'users and groups' and '(users and groups)', but no wasted 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 2-parameter read tool with no output schema, the description supplies the missing return-field context and the downstream dependency (coda_add_permission). Only result-count/pagination behavior is unaddressed.

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

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

Schema description coverage is 100%, so both parameters (query, doc_id) are already documented. The description restates 'query string' and the doc scope without adding format or matching-behavior detail, 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 (search) and resource (users and groups that can be added to a doc's permissions), which cleanly separates it from siblings like coda_list_permissions and coda_get_sharing_metadata that read existing state. An agent can identify the tool's job from the first sentence 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 names the downstream use case ('before calling coda_add_permission') and the lookup scenarios (user's email, groups). It gives clear when-to-use guidance but does not state when-not to use it (e.g., use coda_list_permissions to view current grants).

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 write (readOnlyHint=false) and open-world effects, so the safety profile is already covered. The description adds useful behavior: firing a rule, optional payload dependence, and a requestId return for tracking. It stops short of permission/auth or failure-mode 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?

Front-loaded with the action, then five short lines covering prerequisite, payload variance, return value, and rule_id location. 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 3-param mutation with no output schema, the description notes the requestId return and the API-triggerable prerequisite, which compensates for the missing output schema. It leaves auth/permission and error handling unstated, but annotations cover the main safety profile.

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

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

Schema coverage is 100%, so baseline is 3; the description adds that rule_id is found in automation settings and that payload shape depends on the target automation, which is meaningfully beyond schema text. Still, payload content itself remains opaque.

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 specific verb 'Trigger' and resource 'Coda automation rule' make the core action unambiguous, and the required doc_id/rule_id context is clear. However, the description does not differentiate this from the sibling coda_push_button, which may also initiate automations, so it falls short of the highest bar.

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 prerequisite ('must have an API-triggerable event type') and tells where to find rule_id, which helps invocation. But it does not say when to choose this over coda_push_button or other trigger mechanisms, nor when not to use it.

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

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

Annotations already flag this as a non-read-only, destructive, open-world mutation, and the description usefully adds what actually happens (the public URL stops working), that it is reversible, and that it returns a confirmation with doc_id. The reversibility note materially refines the impact beyond the bare destructiveHint, though it doesn't cover permissions or side effects on existing viewers.

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 core action and effect in the first sentence, then adds impact and reversibility. Slightly redundant between 'removing public access' and 'the public URL will stop working,' but each sentence otherwise 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?

With no output schema, the description steps in to describe the return (confirmation with doc_id), states the effect on the public URL, and notes reversibility. It is complete enough to call correctly, missing only permission/auth prerequisites that the annotations do not supply.

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

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

Schema coverage is 100% for the single doc_id parameter, so the schema already carries the semantics. The description only references doc_id in the return value and adds no format or constraint 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 (unpublish) and resource (Coda doc) with the concrete effect (removing public access). It is cleanly distinguishable from its obvious sibling coda_publish_doc, which it names directly.

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?

Clearly frames the use case — reverting a previously published doc to private — and names the alternative (coda_publish_doc) for the reverse operation. It stops short of an explicit when-not or a prerequisite/permission statement, so it is strong but not fully prescriptive.

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