reach

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals that comments are non-destructive (do not change doc content), optionally anchorable to specific text, and require signed-in identity on SSO instances (returns 401 otherwise). This is good, though it could mention visibility scope or comment persistence.

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

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

The description is a single paragraph that front-loads the main purpose and then adds essential details about anchors and authentication. Every sentence contributes meaning; there is no fluff or repetition. It is concise yet informative.

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

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

Given the tool has 5 parameters (2 required), a nested object, and no output schema, the description covers the key aspects: purpose, anchor usage, auth requirements, and that comments are freeform. It does not describe the return value or comment visibility, but overall it gives sufficient context for an AI agent to use the tool correctly.

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

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

Schema coverage is 80%, so parameters are mostly documented. The description adds value beyond the schema by explaining the anchor parameter in detail: how to use quote, prefix, suffix for re-location after edits, and that the version defaults to the current head. This reduces ambiguity for the complex nested parameter.

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

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

The description clearly states the tool's purpose: 'Leave a comment on a document so people and other agents can see it (advisory feedback; it does not change the doc content).' This specifies the action (leave a comment), the resource (document), and the nature (advisory, non-destructive). Among sibling tools like resolve_comment, edit_doc, and share_doc, this tool is distinctly for adding comments.

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

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

The description provides context on when to use the tool: for advisory feedback that does not change content. It explains optional anchor usage for specific passages and mentions authentication requirements on SSO instances. However, it does not explicitly exclude alternatives or contrast with sibling tools like edit_doc or resolve_comment, missing a clear when-not directive.

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

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

With no annotations provided, the description carries full responsibility. It discloses important behavioral traits: the need for a write credential in SSO contexts, the role of ownerKey in ownership and future edits, and the return of a slug and URLs. It does not describe error responses or rate limits, but the core creation behavior is transparent.

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

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

The description is two sentences with the core action front-loaded. The second sentence provides essential context about authentication and output. It is efficient and avoids fluff, though it could be slightly more structured by separating the authentication note from the output note.

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

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

Given the tool has 6 parameters (1 required) and no output schema, the description covers the main purpose, critical authentication requirements, and output format. It lacks details on default values for optional parameters and error conditions, but for a creation tool, it provides sufficient context for an agent to use it correctly.

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

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

Schema description coverage is 50% (3 of 6 parameters have descriptions). The description adds value by explaining the purpose of ownerKey and token requirements, which goes beyond the schema. However, it does not provide additional detail for parameters like title, format, or visibility, which are missing schema descriptions. Thus, it partially compensates but not fully.

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 starts with a clear verb+resource statement 'Create a new document.' It further distinguishes from sibling tools like 'create_file' by specifying SSO enforcement, token requirements, and the concept of ownerKey for ownership and authorization. The return value (slug and URLs) is also stated, making the tool's functionality unambiguous.

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

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

The description provides specific guidance on when to use this tool in relation to authentication requirements (SSO-enforced instances need a write credential) and ownership (ownerKey for my_docs and edit authorization). However, it does not explicitly state when not to use this tool or suggest alternatives among the many sibling tools, which would improve clarity.

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

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

Discloses key behaviors: file ownership, default privacy, share URL return, org handling. No annotations exist, so description carries full burden. Could be improved by mentioning rate limits or failure modes, but sufficient for basic usage.

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

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

Three sentences, all essential, front-loaded with purpose. No redundancy or filler.

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

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

Covers purpose, return value (share URL), ownership, privacy, org handling. Missing error cases or overwrite behavior, but adequate given no output schema.

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

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

Schema coverage is 100%, baseline 3. Description adds context: path defaults to 'untitled-<n>.md', folder defaults to org root, orgId explanation. The note parameter is not elaborated beyond schema but overall adds value.

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

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

The description clearly states the tool creates a markdown file and returns a share URL. It specifies ownership and distinguishes from other tools like create_doc or write_file by focusing on file creation and URL retrieval.

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

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

Explicitly mentions requirement for signed-in account, privacy defaults, and behavior of orgId (omit for default, required for multiple orgs). Provides 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?

No annotations provided, but description fully discloses behavioral traits: auth requirement, two possible return types based on session state, and what each return contains (org id, access key, or pending flow details).

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

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

Three sentences, front-loaded with main purpose, then details on auth and returns. 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?

Covers purpose, prerequisites, return values (two scenarios), and alternative tools. With no output schema, description sufficiently explains return types 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% with a single parameter 'name' described as optional with default. The description adds no extra meaning beyond the schema, 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?

The description clearly states the tool creates an organization, describes its role as a container for folders and files, and distinguishes it from siblings like create_workspace by mentioning the tenant concept.

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 (create an org), requires signed-in account, and provides alternative flow using create_workspace + poll_workspace_create for human-in-the-loop scenarios.

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

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

Discloses the creation behavior, anonymous-only requirement, and return structure (workspaceId, key, claimUrl). No annotations provided, so description carries full burden; it could mention expiration or quotas for completeness, but is otherwise transparent.

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

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

Three sentences, front-loaded with purpose, then conditions, then return info. Every sentence adds essential context with no 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?

Covers purpose, conditions, and return values well, but lacks documentation for the single parameter. Overall mostly complete given no output schema.

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

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

Parameter 'name' is optional string with 0% schema coverage, and description does not explain its purpose or effect on the created workspace. No compensation for missing schema documentation.

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

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

Description clearly states it creates a temporary workspace in headless/CI/fleet mode, distinguishes from siblings by noting that on reachpad.dev it 403s and users should use create_org/create_workspace instead.

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

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

Explicitly explains when to use (anonymous workspace creation, headless) and when not to (reachpad.dev), providing alternative tools. Also describes return values including claimUrl for later adoption.

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

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

With no annotations, the description carries the full burden. It discloses the async behavior (awaiting_login state) and clarifies that nothing is usable until sign-in. While it covers the core interaction, it omits potential error conditions (e.g., if login fails or times out).

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

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

The description is three sentences, each essential: declaring the purpose, detailing the async flow with instructions, and summarizing the outcome. It is front-loaded with the main action and contains no filler.

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

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

Given the tool's complexity (async with human interaction, no output schema), the description covers the flow, return states, and references the polling sibling. It could be more complete by specifying the format or limits of the 'name' parameter, but the schema handles that.

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

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

Schema coverage is 100% and the description adds no additional meaning beyond the schema's note about server-side defaults. The parameter 'name' is adequately described in the schema, so the description does not need to elaborate.

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

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

The description clearly states the tool creates a 'SECURE, account-owned org/workspace' and distinguishes it from siblings like 'create_temporary_workspace' by emphasizing the need for human sign-in. The verb 'Create' and resource 'workspace' are specific and aligned with the tool name.

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 instructs to use 'when a HUMAN is present to sign in'. It details the asynchronous flow: if no session, returns a pending state with loginUrl, and directs to call 'poll_workspace_create' to obtain the workspaceId. This provides clear when-to-use and alternative steps.

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?

Describes soft-delete behavior and that it's recorded in change history and restorable. Without annotations, this carries the burden but doesn't disclose permissions or side effects like access revocation.

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

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

Single sentence that is front-loaded and concise, with no extraneous information.

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

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

For a simple 1-parameter tool with no output schema, the description covers the key behavioral aspect (soft-delete restorable) adequately.

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 has 0% description coverage and the description does not explain the slug parameter beyond its existence. The pattern provides some constraint but no semantic guidance.

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

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

The description clearly states the tool performs a soft-delete on a document, with the specific verb 'delete' and resource 'doc'. It distinguishes from siblings like restore_doc by mentioning restorability.

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?

Implicitly suggests when to use (soft-delete instead of hard delete) and mentions alternative restore_doc, but lacks explicit context for when to use vs other edit or delete operations.

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

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

No annotations are provided, so the description carries full burden. It discloses soft-delete, recoverability, history preservation, and access requirements. It could additionally mention idempotency or error behavior.

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

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

Three sentences that front-load the purpose and separate the behavioral note, access requirement, and addressing method. No wasted words.

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

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

Given no annotations and no output schema, the description covers key points but omits common details like error handling on missing files or return information.

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

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

Schema coverage is 100%, but the description adds meaning by grouping addressing methods ('fileId or legacy workspaceId+path'), which is not explicit in the schema.

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

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

The description clearly states it soft-deletes a file, is recoverable, and requires write/owner access. It distinguishes from restore_file and other tools by specifying the resource and behavior.

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

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

It provides context on when to use (soft-delete, recoverable) and prerequisites (write/owner access). However, it does not explicitly exclude alternatives like delete_doc for permanent deletion.

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

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

With no annotations, the description must disclose behavioral traits. It mentions 'bounded' and 'unified' diff and the default comparison (previous to head), which adds some behavioral context. However, it does not discuss whether the tool mutates data, authentication requirements, or rate limits, leaving gaps.

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

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

The description is exceptionally concise, consisting of two short sentences that cover the core purpose and addressing modes without any redundant or extraneous information.

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

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

Despite having 6 parameters and no output schema, the description does not explain what the tool returns (e.g., the format of the diff output), possible errors, or how it differs from similar tools like 'get_diff' or 'file_history'. It is minimally adequate but lacks essential context for an agent to use it correctly.

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

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

Schema description coverage is 67% (4 of 6 parameters described). The description adds implicit meaning by stating the default from/to values, which is not captured in the schema. However, the two unreviewed parameters ('from' and 'to') lack descriptions, and the description does not elaborate on parameter constraints beyond the schema, warranting a baseline score of 3.

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

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

The description clearly states the tool produces a 'bounded unified diff between two versions of a file', which is a specific verb+resource. However, it does not explicitly differentiate from the sibling tool 'get_diff', which may serve a similar purpose.

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 by indicating the tool can be addressed by fileId or legacy workspaceId+path, but it does not provide guidance on when to use this tool versus alternatives like 'file_history' or 'get_diff', nor does it mention any prerequisites or limitations.

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

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

With no annotations, the description partially discloses behavior (creates a new version, conflict detection), but does not mention other effects like whether it's destructive or if old versions are preserved.

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

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

The description is two sentences, front-loaded with the main purpose, and each sentence adds value without redundancy.

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

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

Given 6 parameters, 2 required, and no output schema, the description is too minimal to fully guide an agent. It omits expected return values, parameter dependencies, and error cases beyond the 409 conflict.

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 low (17%), and the description only adds meaning for baseVersion (concurrency safety). Other critical parameters like slug, content, and visibility are not explained beyond the schema.

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

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

The description states 'Create a new version of a document' which clearly defines the action and resource, distinguishing it from sibling tools like create_doc or delete_doc.

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 mentions when to use baseVersion for safe concurrent edits and the 409 error, but does not explicitly state when to use this tool over siblings like edit_section or 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?

With no annotations, the description carries full burden. It explains merge behavior and conflict-free nature but omits edge cases like section creation, error handling, or details on how merge is applied. More specificity on behavior would raise the score.

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 extremely concise (two sentences) with all essential information front-loaded: purpose, behavior, and addressing. Every word adds value with no redundancy.

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

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

Given 9 parameters, 2 required, and no output schema, the description covers main behavior but misses details on parameters like 'note', 'linkToken', and operation semantics. It sufficiently explains core use but lacks completeness for all input nuances.

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 44% (4/9 params described). The description adds meaning for 'section' and 'content' (heading+body) but does not elaborate on format or operation parameter 'op'. It partially compensates for schema gaps but could provide more detail on how parameters interact.

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

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

The description clearly states the tool edits ONE markdown section (heading and body), merged onto head, and is conflict-free for agents editing different sections. It specifies the need for write access and addressing by fileId or legacy workspaceId+path, distinguishing it from siblings like edit_doc or edit_section.

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

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

The description provides clear context on when to use (editing sections in a file), mentions conflict-free behavior for different sections, and prerequisites (write access, identifier). It implicitly advises against editing same section concurrently, but lacks explicit exclusions or alternatives.

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

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

With no annotations, the description covers key behaviors: conflict-free merging, merge modes via the 'op' parameter, and section creation if absent. It does not mention auth or rate limits but adequately describes the non-obvious 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?

Two sentences, both essential: the first states the core purpose, the second provides key usage and constraint information. No fluff, front-loaded with purpose.

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

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

Given no output schema, the description explains behavior (conflict-free, merge modes) and constraints (Markdown only). It could mention what the tool returns, but for a mutation tool, the behavior description is sufficient. Parameters are mostly covered.

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 80%, and the description adds meaningful context: 'section' is case-insensitive heading text and created if absent; 'op' describes merge strategies with default replace. The 'slug' pattern is not explained, but the schema covers it. The description enhances parameter understanding.

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

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

The description clearly states the tool edits one section of a markdown doc, specifying the verb 'edit' and resource 'section'. It distinguishes itself from sibling tools like edit_doc by focusing on a single section.

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

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

The description explicitly mentions conflict-free operation for different sections, indicating when to use this tool (section editing) and implying when not to use it (if baseVersion handling is needed). It also limits usage to Markdown docs.

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

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

No annotations are provided, so the description carries the burden. It mentions chainValid for tamper evidence, indicating a security trait. But it doesn't disclose permissions needed, side effects, or behavior when parameters conflict.

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

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

The description is a single, clear sentence that covers the core functionality. It is front-loaded and efficient, though could be slightly more structured.

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

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

While the description covers the main outputs (version, change history, chainValid), it lacks details about pagination, response format, or error cases. Given no output schema, this is a marginal gap.

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

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

Schema description coverage is 100%, and the description adds value by explaining the two addressing modes (fileId vs workspaceId+path) and key parameter usage. This goes beyond what the schema alone provides.

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

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

The description clearly states the tool retrieves a file's full version and change history, including chainValid for tamper-evident ledger. It specifies addressing options, distinguishing it from siblings like get_history.

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 explains how to address the file (by fileId or workspaceId+path), providing practical guidance. However, it does not explicitly compare to sibling tools like get_history or detail when to use this over others.

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

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

No annotations are provided, so the description must convey behavioral traits. It mentions 'bounded unified diff' and cost savings, but does not disclose read-only status, error conditions, size limits, or output format. This is insufficient for safe invocation.

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?

A single, well-structured sentence that conveys the core purpose and a key benefit. No wasted words.

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

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

The description covers the primary use case but lacks details on output format, error handling, and behavior when versions are invalid. Without an output schema, the description should have provided more context.

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 67%, with 'to' and 'from' having descriptions in the schema. The tool description adds no parameter-level detail beyond the defaults already stated. It does not explain the 'slug' parameter, which lacks a description in schema.

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

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

The description clearly states it retrieves a 'bounded unified diff between two versions' with defaults, and mentions it's cheaper than alternatives. This is specific and distinguishes the tool from siblings like get_history.

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 explains when to use the tool (getting a diff between versions) and why it's beneficial (cheaper). However, it does not explicitly state when not to use it or suggest alternatives, leaving some ambiguity.

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

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

No annotations provided, and the description does not disclose behavioral traits such as authentication requirements, rate limits, or error behavior (e.g., what happens if document not found).

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

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

Single sentence that is clear and front-loaded. Could be slightly more compact but acceptable.

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

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

Given no output schema, the description could mention return format or behavior for missing documents. It is adequate but not thorough for a moderately complex tool with 2 parameters.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description adds minimal value beyond echoing 'optionally a specific version'.

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

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

The description clearly states the tool retrieves the raw source of a document, specifying markdown or HTML, and optionally a specific version. It distinguishes from siblings like get_doc_meta which would return metadata.

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

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

No guidance on when to use this tool versus alternatives like get_doc_meta or list_docs. No context about prerequisites or exclusions.

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

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

With no annotations provided, the description must disclose behavioral traits. It describes the return as a manifest including change history with chainValid, implying a read operation without side effects. However, it does not explicitly state read-only, mention authentication requirements, or clarify response format, limiting full transparency.

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

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

The description is a single, concise sentence of 19 words. It front-loads the primary action ('Get a document's manifest') and efficiently lists the return components. Every word adds value with no redundancy.

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

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

Given no annotations and no output schema, the description partially covers the tool's purpose and return structure (metadata, version list, change history). However, it lacks details on output format, parameter usage, and specifics of each component (e.g., what metadata fields are included), leaving gaps for an agent.

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

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

The description adds no information about the single parameter 'slug'. With 0% schema description coverage, the description must compensate but fails to explain what slug represents or how to use it (e.g., it's the document identifier). The agent receives no parameter context beyond the schema's regex pattern.

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

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

The description clearly states the tool retrieves a document's manifest, listing specific components: metadata, version list, and tamper-evident change history with chainValid. This verb+resource structure is precise and distinguishes it from sibling tools like get_doc or get_history, which likely focus on content or history separately.

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

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

The description provides no guidance on when to use this tool versus alternatives like get_doc, get_history, or verify_doc. It simply states what it does without contextual hints or exclusions, leaving the agent to infer usage from the purpose alone.

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

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

With no annotations provided, the description must fully disclose behavioral traits. It only states the purpose and fails to mention whether the operation is read-only, requires authentication, or has rate limits. The return format or pagination behavior is also omitted.

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

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

The description is a single, concise sentence with no unnecessary words. It is front-loaded with the core action.

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

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

Given the tool's simplicity (1 parameter, no output schema, no annotations), the description is minimal. It does not clarify the output format, potential errors, or when to use this over similar tools like get_diff or get_doc_meta. The agent may be under-informed for effective selection.

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 only parameter 'slug' has no description in the schema (0% coverage) and the tool description adds no meaning beyond the schema's pattern constraint. It does not explain what a slug is or how to obtain it.

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

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

The description clearly states the tool retrieves the full version and change history of a document, using a specific verb ('Get') and resource ('history of a document'). It distinguishes itself from sibling tools like get_diff (which compares versions) and get_doc (which retrieves the current document).

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

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

The description provides no guidance on when to use this tool versus alternatives, nor does it mention any prerequisites or exclusions. For instance, it does not indicate that this tool is for historical data rather than current state, leaving the agent to infer context.

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

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

With no annotations, the description carries full burden. It discloses that the tool creates a doc and returns rawUrl, which is adequate for a creation tool. However, it does not mention any side effects beyond creation, such as ownership or visibility implications.

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

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

Single sentence that efficiently conveys the essential information: purpose, action, output, and relationship to sibling. No unnecessary words.

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

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

Given the tool is a simple alias with 6 parameters and no output schema, the description covers the key contextual points: it's for handoff, creates a doc, returns rawUrl. However, it could be slightly more detailed on the output format or parameters, but it's sufficient for its simplicity.

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 50%, borderline. The description does not add parameter-level meaning beyond the schema, but the schema itself provides descriptions for half the parameters. The tool's description implies the parameters are those of create_doc, which is acceptable for an alias.

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

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

The description clearly states the tool's purpose: 'Hand a document off to another agent' with the action of creating a doc and returning its rawUrl. It explicitly identifies as an alias of create_doc, distinguishing it from siblings like create_doc itself.

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?

Implies usage for handoff scenarios by stating 'to pass along', but does not explicitly say when to use this versus the sibling create_doc, nor when not to use it. No alternative tools mentioned.

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

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

Discloses key behaviors: returns an inviteUrl, quota-aware, requires signed-in account. No annotations provided, so description carries full burden; it does so effectively but could mention side effects like pending invitation state.

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

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

Two sentences, front-loaded with purpose, no redundant information. Every sentence adds value.

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

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

Covers return value, auth constraints, quota usage. Lacks details on error handling, idempotency, or invitation life cycle, but adequate for a simple invite tool with no output schema.

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

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

Schema coverage is 67% (2 of 3 params described). Description adds no extra meaning beyond schema; role parameter lacks description in both schema and description, so marginal added 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?

Clearly states 'Invite a person by email into an org/workspace' with specific verb and resource. Also identifies itself as an alias of invite_to_org, distinguishing it from siblings like create_org or remove_member.

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 not to use (workspace key cannot invite) and notes quota usage ('any member can invite, spends their quota'), providing clear context vs alternatives.

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

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

Without annotations, the description thoroughly discloses behavioral traits: quota-bounded, returns accept link + remaining quota, informs when out of invites, default role 'member', any member can invite but it spends the inviter's quota, and requires a signed-in account. This is comprehensive.

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

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

Two sentences that are well-structured and front-loaded. The first sentence communicates purpose and key outputs, the second adds role and access details. No unnecessary words.

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

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

Given no output schema, the description explains return values (accept link, remaining quota, out-of-invites message). It covers preconditions (signed-in account, not workspace key) and quota bounding. The tool is simple, and the description is complete.

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

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

Schema coverage is 100%, so the schema already describes all parameters. The description adds minimal value beyond schema, such as confirming default role and source of orgId. This meets the baseline for high coverage.

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

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

The description clearly states the tool invites a person by email into an org, which is a specific verb+resource. It distinguishes from sibling tools like invite_member by specifying 'org', but does not explicitly differentiate from invite_member, which could cause confusion.

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

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

The description provides clear context on when to use: inviting to an org, with quota-bounded and authentication requirements. It mentions that a workspace key cannot invite, giving an explicit exclusion. No direct mention of alternatives, but the scope is well-defined.

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

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

With no annotations provided, the description carries the full burden. It discloses that comments have 'anchor' and 'resolved' fields and states 'Same read access as the doc itself', which informs about permissions. It does not mention pagination or rate limits, but for a simple list tool, this is sufficient.

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

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

Three sentences with no waste. The first sentence front-loads the purpose, and subsequent sentences add necessary context. 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 no output schema, the description mentions key fields (anchor, resolved) but does not explain the complete return structure. The tool is simple with one parameter; the description covers most aspects except parameter meaning, which is a notable omission.

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

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

Schema description coverage is 0% for the only parameter 'slug', and the description does not explain what 'slug' represents (likely a document identifier) or provide any format guidance beyond the schema pattern. This is a critical gap as the agent cannot infer the parameter's meaning from the description.

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

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

The description explicitly states 'List the comments people and agents have left on a document' and distinguishes from 'version history'. It clearly identifies the verb (list), resource (comments on document), and scope. Sibling tools like add_comment and resolve_comment are distinct, so no confusion.

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

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

The description advises 'Use this to see what a reader flagged before revising the doc', which gives a clear use case. It implies when-to-use but does not explicitly state when-not-to-use or mention alternatives. However, given the context of siblings, the guidance is adequate.

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

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

No annotations provided, so description carries full burden. Discloses account-scoping, that workspace key is ignored, and return fields (fileId url and perm). Does not mention rate limits or pagination, but these are less critical for a list tool. No contradictions with annotations (none 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?

Four sentences, front-loaded with core purpose. Every sentence adds value without redundancy. Efficiently communicates essential information.

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

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

Given no output schema, description covers return format (fileId url and perm), account scoping, filtering options, and signed-in requirement. Lacks pagination or ordering details, but overall complete for a 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 67% (two out of three params have descriptions). Description adds clarity: explains scope enum values and default ('all'), and notes orgId for filtering. Provides meaning beyond schema, especially for the scope parameter which lacked a schema description.

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

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

Clearly states it lists files the user can access (owned or shared), not the whole org. Specifies account-scoping and filtering options, distinguishing it from other file 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?

Provides clear context: requires signed-in account, workspace key not honored, account-scoped. Mentions filtering by orgId and scope. Does not explicitly contrast with sibling tools like create_file or delete_file, but the description is sufficient for typical 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?

No annotations are provided, so the description carries the full burden. It discloses the required role and indicates a read-only listing operation. However, it does not explicitly state that it is read-only or describe any side effects, leaving some ambiguity.

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

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

The description is two sentences long, front-loading the purpose and returning fields, followed by the required capability. Every sentence adds value with no fluff.

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

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

Given the absence of an output schema, the description compensates by listing the returned fields. It covers the required parameter, role requirement, and key details, making it fairly complete for a list operation with two parameters.

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 have descriptions in the schema. The tool description does not add significant meaning beyond what the schema already provides, resulting in a baseline score of 3.

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

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

The description clearly states the tool lists pending invites for an organization and specifies the fields returned (id, email, role, expiry, who issued). This distinguishes it from sibling tools like revoke_invite or invite_member.

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 mentions the required capability ('Owner/admin (manage) capability required'), providing clear context for when the tool is applicable. However, it does not explicitly state when not to use it or suggest alternatives.

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

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

The description says keys are non-secret and requires manage capability, but since no annotations are provided, more details about side effects or authorization would be helpful.

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

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

Two concise sentences with no unnecessary information, front-loaded with the primary action and resource.

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

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

For a simple list tool with no output schema, the description covers key aspects (resource, scope, prerequisite), but lacks details about the return format.

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

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

Schema coverage is 100%, so the description does not add extra meaning beyond the parameter descriptions already in the schema.

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

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

The description clearly states it lists non-secret access keys on a workspace, distinguishing it from sibling tools like mint_key and revoke_key.

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

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

The description mentions 'Requires manage capability' as a prerequisite but does not explicitly state when to use this tool versus alternatives or when not to use it.

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

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

No annotations are provided, and the description does not disclose behavioral traits such as return format, error handling, or side effects, leaving the agent uninformed about important runtime behaviors.

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, front-loaded sentences with no unnecessary words; every sentence adds value.

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

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

No output schema is provided, and the description omits information about what the list contains (e.g., user IDs, roles, pagination), leaving the agent without a clear picture of the tool's output.

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

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

The schema covers both parameters with descriptions, and the tool description adds no additional parameter context beyond the schema, meeting the baseline.

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

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

The description clearly states the verb 'list' and the resource 'workspace's members', and distinguishes it from sibling tools like invite_member or remove_member by specifying the action.

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 condition 'Requires manage capability' provides clear context for when to use the tool, but no explicit alternatives or when-not-to-use guidance is given.

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

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

No annotations are provided, so the description carries the full burden. It discloses that invite quota is not listed, and describes the behavior of the key parameter (overrides REACH_WORKSPACE_KEY but keys can't own or be shared). It does not explicitly state this is a read-only operation, but that is implied.

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

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

The description is two sentences plus a parenthetical, with no unnecessary words or repetition. It is front-loaded and efficient.

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

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

Given the tool's simplicity (one optional param, no output schema, no annotations), the description is complete: it covers purpose, when to use, what not to use for, the parameter's role, and even references a sibling tool. No gaps are evident.

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

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

Schema coverage is 100% for the single parameter 'key'. The description adds behavioral context beyond the schema description: it explains that the key overrides REACH_WORKSPACE_KEY and notes the scope limitation (org-scoped create/list/manage only) and that keys can't own or be shared. This adds meaningful value.

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

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

The description clearly states it lists organizations the user belongs to and their role. It distinguishes from siblings by noting that invite quota is not here but on list_members, which is manager-only.

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

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

It explicitly says when to use this tool: 'to discover which org to write to (pass its id to create_file when in more than one)'. It also advises when not to use it by noting that invite quota is not listed and that list_members (manager-only) carries that information.

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

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

The description adequately discloses the read-only nature (listing) and the scope of data (organizations reachable by key/account). No contradictions with annotations (none provided). Suitable for a simple list operation.

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

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

The description is a single sentence with a parenthetical clarification. It is succinct, front-loaded with the main verb and resource, and contains no superfluous information.

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

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

For a simple list tool with no output schema, the description sufficiently conveys what is listed and under what conditions. It acknowledges the alias relationship, which is helpful given sibling list_orgs. Lacks details on return format but acceptable for this complexity.

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

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

Schema coverage is 100%, with the schema description already detailing the key parameter's behavior. The main description adds no additional parameter information, meeting the baseline expectation but not exceeding it.

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

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

The description clearly states the tool lists organizations (workspaces) accessible by the user, and explicitly notes it is an alias of list_orgs. However, it does not differentiate from list_orgs beyond stating the alias, which may leave the agent uncertain which to use if both are available.

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

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

No guidance is provided on when to use this tool versus alternatives. The alias mention offers some context, but there is no explicit when/when-not or comparison with sibling tools like create_workspace or list_members.

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

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

With no annotations, the description carries the full burden. It discloses that the secret is returned once, that the minted key acts as the org owner, and the ownership constraint. It is fairly transparent, though could mention revocation possibilities or key limits.

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

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

The description is a single paragraph of two sentences, front-loading the core purpose and then adding critical usage constraints. Every word earns its place.

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

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

Given no output schema, the description mentions that the secret is returned once, which addresses return value. It covers ownership and security context. It could briefly note error conditions but is otherwise complete.

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

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

Schema description coverage is 60%, and the tool description does not add significant detail beyond what the schema provides for parameters like key, actor, workspaceId. The label and ttlSeconds parameters lack additional context.

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

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

The description clearly states the tool mints a new access key for a workspace, with a specific use case example. It distinguishes itself from sibling tools like list_keys and revoke_key.

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

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

The description explicitly states that only the org owner may mint (or a live key on unclaimed/temp space), and that admins cannot. This provides clear when-to-use and who-can-use guidance, though it doesn't mention alternatives.

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

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

With no annotations, the description carries full burden. It explicitly discloses identity-preserving traits (fileId, history, sharing survive, URL keeps working) and mentions legacy addressing. However, it does not cover permissions, error conditions, or whether moves across orgs are allowed.

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

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

Two sentences with no wasted words. First sentence states purpose, second sentence adds critical behavioral and calling information. Front-loaded and efficient.

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

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

For a 5-parameter move tool with no annotations or output schema, the description covers the core behavior and two usage patterns. However, it does not clarify that some parameters are effectively required (contradicting the schema's 'none required'), nor does it describe return values or error states. This leaves gaps for an AI agent.

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

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

Schema coverage is 100%, so baseline is 3. The description adds the relational context of which parameters go together (fileId+to vs workspaceId+from+to) but does not add meaning beyond the schema's detailed parameter descriptions. The value added is moderate.

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

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

The description clearly states the tool renames/moves a file to a new path, with a specific verb ('Rename/move') and resource ('file'). It distinguishes from other tools by detailing identity-preserving behavior and two addressing modes, which is unique among siblings.

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

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

The description implies the tool is for renaming/moving files and mentions two calling conventions but does not explicitly state when to use this tool versus alternatives (e.g., copy or link tools). It lacks when-not guidance and does not address prerequisites or limitations.

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

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

With no annotations, the description must carry behavioral context. It discloses that the tool lists documents tied to an owner key and that the same key enables edits, indicating a read operation. However, it omits details about side effects, pagination, or result format.

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

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

The description is two sentences, front-loaded with purpose, and every sentence adds value without redundancy. It is highly concise and well-structured.

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

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

Given the single parameter, no output schema, and no annotations, the description covers the basic context. However, it lacks details on output format, sorting, or filtering, and does not clarify how 'my_docs' differs from sibling 'list_docs'.

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

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

Schema coverage is 100% with a good description for ownerKey. The description adds value by explaining the key's header name ('X-Reach-Owner-Key') and the optionality with default key, going beyond the schema.

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

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

The description clearly states 'List the documents owned by your owner key,' specifying the verb 'List' and the resource 'documents owned by your owner key.' It differentiates from sibling 'list_docs' by focusing on ownership, but does not explicitly contrast it.

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 use for listing personal documents and notes that ownerKey is optional with a default key. However, it does not provide guidance on when not to use this tool or compare it to alternatives like 'list_docs'.

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?

Description discloses key behavioral traits: the tool polls until the human finishes, returns intermediate and final statuses, and warns that the 'ready' response is given only once. No annotations are present, so the description carries the full burden, and it does so adequately.

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

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

Description is two sentences with no filler, front-loading the purpose and providing essential behavioral details efficiently.

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

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

Given the tool's simplicity and lack of output schema, the description covers the polling flow and return states adequately. It does not address error conditions or validation, but for this context it is mostly 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 only 50% (pollToken has a description, pendingId does not). The tool description does not elaborate on pendingId, and for pollToken it merely restates the schema description. Thus, little additional meaning is added beyond what the schema provides.

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

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

Description clearly states the verb 'poll' and the specific resource 'pending secure create', distinguishing it from sibling tools like create_workspace and create_temporary_workspace. It precisely describes the tool's role in the secure create flow.

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?

Description implies usage after the human opens the loginUrl, providing clear context. However, it does not explicitly exclude other scenarios or mention alternatives, leaving some ambiguity.

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

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

No annotations provided, so description must carry full burden. It mentions returning content and version, and a 404 error if not shared. However, it does not explicitly state that the tool is read-only and has no side effects, which would be beneficial for an agent.

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

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

The description is concise with two to three sentences. It front-loads the primary purpose and quickly covers addressing and error conditions without unnecessary words.

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

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

Given 6 parameters, no output schema, and no annotations, the description adequately covers usage patterns and error conditions. However, it could mention the return format (e.g., raw text) for completeness.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds practical guidance on parameter usage (prefer fileId, legacy workspaceId+path, linkToken for share links, version defaults to head), which adds value beyond what the schema provides.

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

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

The description clearly states the action (Read), resource (file), and what is retrieved (content + current version). It distinguishes from siblings like write_file, delete_file, etc., by specifying the read 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?

Provides explicit guidance on which addressing method to prefer (fileId vs workspaceId+path) and how to use linkToken for share links. It gives context for usage but does not explicitly mention when not to use this tool compared to alternatives.

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

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

No annotations present, so description carries full burden. It discloses that access is revoked promptly (immediacy) and that the owner is protected from removal. Also mentions required capability. Lacks details on reversibility or side effects.

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

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

Single concise sentence with parenthetical qualifiers. No extraneous words; front-loaded with the core action.

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

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

No output schema, so description should hint at return value or error conditions; it does not. Also does not specify whether the member must currently exist. Adequate for simple removal but leaves some gaps.

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

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

Schema description coverage is 67% (key and workspaceId documented, accountId missing). Description adds that removal is 'by accountId', clarifying the role of accountId. Does not elaborate on the key parameter's usage in context of removal.

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

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

Description clearly states 'Remove a member' with the specific identifier 'accountId', and adds scope constraints (owner cannot be removed). This distinguishes it from sibling tools like invite_member or list_members.

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

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

Explicitly states requirement for 'manage capability', guiding authorization. Does not provide explicit when-not-to-use or alternatives, but context of removal vs. invitation is clear.

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

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

No annotations are provided, but the description discloses the action (resolve/reopen) and access requirement. It does not detail side effects or error handling, but for a simple toggle, this is adequate.

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

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

Two sentences plus a parenthetical note, every piece of information is essential and no redundancy. Highly concise and efficiently structured.

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

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

For a mutation tool without output schema, the description covers the main action, access requirements, and a notable limitation (file comments). Missing details like error cases, but overall sufficiently 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 67%, with descriptions already provided for resolved and reviewId. The description adds minimal extra meaning beyond the schema, so baseline score of 3 is appropriate.

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

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

The description clearly states the tool marks a comment as resolved or reopens it, using an analogy to GitHub review threads. It distinguishes from sibling tools like add_comment and list_comments.

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

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

Explicitly mentions required write access and clarifies that file comments under /f/:fileId are handled via HTTP, not this tool. This provides clear context for when to use this tool versus alternatives.

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

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

No annotations are provided, so the description bears full burden. It only says 'Restore a soft-deleted document' without explaining side effects, permissions needed, or how restoration interacts with change history. With zero annotations, this is insufficient.

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

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

The description is a single, short sentence with no wasted words. However, it is slightly under-specified, but still efficient for its brevity.

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

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

Given the tool's complexity (a restore action), lack of output schema, and only one parameter, the description is incomplete. It omits details about return value, prerequisites (document must be soft-deleted), and post-restore state.

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 0%. The description does not mention the 'slug' parameter at all, leaving the AI agent to rely solely on the schema pattern, which lacks semantic context (e.g., what document slug refers to, how to obtain it).

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

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

The description states a specific verb ('Restore') and resource ('a soft-deleted document'), and clarifies scope ('recorded in the change history'). This distinguishes it from sibling tools like 'delete_doc' (which performs the soft-delete) and 'get_history' (which shows change history).

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 for documents previously soft-deleted, but does not explicitly state when to use this tool versus alternatives (e.g., after 'delete_doc'), nor provides exclusions or prerequisites.

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

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

The description notes that history and sharing are restored intact, which is good. However, with no annotations, it lacks details on required permissions, error cases, or behavior when file is already restored.

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?

A single sentence that conveys essential information without any fluff. Every word earns its place.

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

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

For a 4-parameter tool with no required fields and no output schema, the description adequately covers the main operation and addressing. Could include more on error conditions or prerequisites, but sufficient for typical use.

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 3. The description adds value by grouping parameters into two addressing patterns and labeling workspaceId+path as 'legacy', which is not in the schema.

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

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

The description clearly states 'Restore a soft-deleted file', which is a specific verb+resource. It distinguishes from sibling tools like delete_file (delete) and restore_doc (restore doc vs file).

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

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

It explicitly says 'Address by fileId or legacy workspaceId+path', providing two addressing methods. This gives clear usage context, though no direct comparison to alternatives like restore_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?

No annotations are provided, so the description carries the burden. It discloses quota refund and required capability, which are behavioral traits. However, it could mention what happens if the invite is already accepted or missing, making it slightly incomplete.

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

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

Two sentences, no redundant words, front-loaded with the primary action. Every word is necessary.

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

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

Given the simple nature of the tool (3 params, no output schema), the description covers purpose, prerequisite, side effect, and parameter sources. It lacks explicit return value info, but that is acceptable for a revocation action.

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

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

Schema description coverage is 100%, meaning the schema already documents all parameters. The description adds minimal value by clarifying that 'id' comes from list_invites and 'orgId' from list_orgs, but this is already implied by sibling 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?

The description clearly states the action (revoke a pending invite), identifies the resource type (invite by id from list_invites), and includes a specific side effect (refunds quota). It distinguishes from sibling tools like list_invites and invite_member.

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 specifies a prerequisite (Owner/admin manage capability required), which guides when the tool is applicable. It does not explicitly mention when not to use or provide alternatives, but the context makes the usage clear.

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

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

With no annotations, the description carries full burden. It discloses that only the specified key is revoked and others are unaffected, and mentions the required permission level. This adds valuable behavioral context beyond the input schema.

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

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

The description is a single sentence, front-loaded with the core action ('Revoke an access key by id'), and contains no fluff. Every part earns its place.

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

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

For a simple tool with no output schema and three parameters, the description covers the action, scope, and prerequisites adequately. It does not explain the return value, but for a revocation action, this is often self-evident.

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

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

The input schema already has 100% coverage with descriptions for all three parameters. The description does not add new semantic information beyond what is in the schema, so a baseline score of 3 is appropriate.

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

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

The description clearly states the action (revoke) and resource (access key), and explicitly mentions that other keys and members are unaffected, distinguishing it from sibling tools like mint_key or list_keys.

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

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

It specifies the prerequisite ('Requires manage capability'), giving clear context for when to use. However, it does not explicitly contrast with alternatives like mint_key or list_keys, which would have been helpful but is not strictly necessary given the clear purpose.

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

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

No annotations provided, but description fully discloses behavioral traits: ownership requirement, URL token return on enable, token rotation on disable. This is comprehensive.

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

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

Two sentences, front-loaded with purpose, no wasted words. Each sentence provides essential information.

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

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

With 2 parameters and no output schema, the description covers all necessary aspects: purpose, usage constraints, modes, side effects (token rotation), and return value.

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 50%, but description adds meaning: enumerates mode values explicitly and explains fileId as the unguessable id from create_file. Adds value beyond schema.

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

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

Clearly states the verb 'Set' and resource 'file link access' with specific modes (none, view, edit). Distinguishes from siblings like share_file by specifying 'anyone with the link' 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 explicit context: 'Owner only' and the three modes. Does not explicitly mention when not to use or alternatives, but the ownership constraint is a strong usage guideline.

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

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

Given no annotations, the description only states it creates a doc and returns a URL. It omits any side effects, authorization needs, or behavioral constraints (e.g., whether it overwrites, requires ownerKey, etc.).

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 very short and front-loaded with the core purpose. However, it may be too terse for the number of parameters and context needed.

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 six parameters, no output schema, and the alias relationship, the description is insufficient. It doesn't explain parameter roles, return value structure, or how this tool differs from others.

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 description adds no information about the six parameters. With only 50% schema coverage, it fails to clarify the meaning or usage of parameters beyond what the schema already provides.

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

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

The description clearly states the tool shares a document by creating it and returning its URL, and explicitly notes it's an alias of create_doc. However, it does not distinguish when to use this vs. the sibling create_doc.

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

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

No guidance is given on when to use this tool over its sibling create_doc or other tools. The description simply labels it as an alias without use-case differentiation.

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

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

With no annotations, the description carries the full burden. It discloses that only the owner can share, the URL is stable and requires login, and how to unshare. Missing details like rate limits or side effects (e.g., email sent) but sufficient for core 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 three short sentences, front-loaded with the main action, and each sentence adds distinct information without redundancy. No fluff or unnecessary details.

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

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

Given no annotations and no output schema, the description covers the core operation well: ownership, permission types, unsharing, and recipient access. Missing information on response structure or error cases, but acceptable for a focused 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 baseline is 3. The description adds value by explaining the remove parameter's effect ('true to unshare') and clarifying the fileId format ('unguessable /f/:fileId id returned by create_file'). This goes beyond schema descriptions.

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

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

The description clearly states the action ('Share a file'), the resource ('file'), and the constraint ('you OWN'). It differentiates from sibling tools by specifically targeting file sharing, not document sharing or other actions.

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

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

The description provides basic usage context (owner only, pass remove:true to unshare) but does not explicitly state when to use this tool versus alternatives like share_doc or add_comment. No exclusions or conditions are given.

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

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

With no annotations, the description must fully disclose behavior, but it only says 'update with a new version,' implying mutation without detailing effects like overwrite behavior, conflict resolution, or required permissions.

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

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

The description is a single, front-loaded sentence that conveys the main purpose and alias relationship without unnecessary words. It is appropriately sized for its content.

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

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

Given the tool's complexity (6 parameters, 2 required, no output schema), the description is too brief. It does not explain return values, error conditions, or how the 'new version' concept works, leaving gaps 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 only 17%, and the description adds no information about parameters such as slug, content, or visibility. The agent must rely on the schema alone, which has limited descriptions.

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

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

The description clearly states the tool updates a shared document with a new version, and identifies it as an alias of edit_doc, making the main action obvious. However, it does not differentiate from the sibling edit_doc beyond noting they are aliases.

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

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

The description provides no guidance on when to use this tool versus alternatives like edit_doc (which is the same) or other update mechanisms. No prerequisites or context are mentioned, leaving the agent to infer 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?

No annotations are provided, so the description carries the full burden. It mentions 'recompute' which might imply state modification, but 'verify' suggests read-only. No disclosure of side effects, authorization needs, or what happens to the document during this operation.

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

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

The description is a single sentence, which is concise but lacks front-loading of key details. Every word is used, but it does not earn its place by providing structural clarity.

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

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

Given the tool has one parameter and no output schema, the description should explain the verification process, potential outcomes, and side effects. It fails to do so, leaving the agent with insufficient information to use the tool effectively.

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

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

The input schema has zero description coverage, and the tool description does not explain the 'slug' parameter beyond its existence. No details on how to obtain or format the slug, leaving the agent without necessary context.

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

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

The description clearly states the tool recomputes and verifies the document's history hash chain, specifying the action (recompute/verify) and resource (document's history hash chain). This distinguishes it from siblings like 'get_history' which likely retrieves history without verification.

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

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

No guidance on when to use this tool versus alternatives like 'get_history' or 'edit_doc'. The description lacks context on prerequisites or scenarios, leaving the agent to infer 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?

No annotations provided, so description must cover behavioral traits. It states verification of hash chain but does not mention non-destructive nature, error behavior, output, or authentication requirements.

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

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

Single sentence with 15 words, front-loaded with purpose and addressing options. No wasted text.

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?

Missing critical context: no mention of output (verification result), prerequisites (e.g., key usage), or error handling. Without output schema, description should fill 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 covers all 4 parameters (100%). Tool description adds combinatorial logic: fileId xor workspaceId+path, and notes legacy status, going beyond schema.

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

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

Clearly states the tool verifies a file's tamper-evident hash chain, distinguishing it from other verify tools (verify_doc, verify_org, verify_workspace) and file manipulation tools. Specific verb and resource with mechanism.

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

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

Provides explicit addressing methods (fileId or legacy workspaceId+path), guiding when to use each. However, no explicit when-not-to-use or alternatives to other verification tools.

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

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

With no annotations, the description carries full burden. It discloses the access requirement and error behavior for unauthorized users. While it doesn't explicitly state the operation is non-mutating, 'verify' implies read-only, but could be more explicit about side effects.

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

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

Two sentences, no fluff. First sentence conveys core purpose, second adds critical access info and alternative. Efficient and front-loaded.

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

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

Given the tool has 3 parameters and no output schema, the description adequately covers purpose, access constraints, and alternatives. Could briefly mention return format or what 'tamper-evident history' entails, but overall sufficient.

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

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

Schema coverage is 100% (all three parameters described in schema). The description adds no additional parameter-level details beyond what the schema already provides, so baseline score of 3 is appropriate.

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

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

The description clearly states the tool verifies an org's tamper-evident history, specifying 'every file's hash chain + the structural audit log'. It distinguishes from sibling verify_file by noting the scope difference.

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 that owner/admin (manage) access is required and plain members get 404. Provides an explicit alternative: 'use verify_file for an individual file you can access'.

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

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

Without annotations, the description carries the full burden. It states the action (verify) and scope (org's history), and mentions access requirements, but does not disclose return value, side effects, or whether it is read-only. Some behavioral context is provided but incomplete.

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 extremely concise with two sentences, no filler, and front-loads the core purpose. Every sentence serves a clear function: stating purpose and noting the alias and access requirement.

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

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

Given the tool's simplicity (2 parameters, no output schema, no nested objects), the description adequately covers the primary function and access needs. However, it lacks explanation of the return value or behavior on success/failure, which would be helpful for a standalone description.

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

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

Schema coverage is 100% with both parameters already documented. The description does not add any additional meaning beyond what the schema provides, so it meets the baseline without extra value.

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

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

The description clearly states the tool verifies an org's tamper-evident history and explicitly identifies it as an alias of verify_org, making the purpose unambiguous and differentiated from non-verify tools.

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

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

The description specifies that owner/admin (manage) access is required, which is a prerequisite, but it does not provide guidance on when to use verify_workspace versus its alias verify_org or other sibling tools like verify_doc. Usage context is implied but lacks explicit directives.

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

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

With no annotations provided, the description carries full burden. It discloses core behaviors (upsert, last-write-wins, write access needed, addressing modes, concurrency handling with 409 response). However, it omits details on success response, side effects, rate limits, or reversibility.

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

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

The description is three sentences long, front-loaded with the core action, and each sentence adds distinct value (operation, access, concurrency). It is efficient and informative.

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 complexity (8 params, no output schema, no annotations), the description covers core functionality and concurrency but lacks details on return values, content encoding, or scope of workspaceId. It provides adequate guidance for typical usage but could be more complete.

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

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

Schema description coverage is 63%, so baseline is 3. The description adds meaning for fileId, workspaceId, path, and baseVersion, but does not elaborate on key, note, or linkToken beyond schema descriptions.

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

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

The description clearly states it creates or updates a file's whole body (upsert) and mentions last-write-wins behavior. It implies it is for whole-file operations, distinguishing it from sibling tools like edit_file_section, but does not explicitly compare to create_file or read_file.

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

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

The description specifies when to use this tool (upsert whole file) and provides guidance on safe concurrent edits using baseVersion, along with addressing options. It lacks explicit when-not-to-use guidance and does not compare to alternatives like edit_file_section.

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