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

Goes well beyond the annotations: sequential processing, a permission check per document, per-ID results, partial success, and a hard stop on auth or rate-limit failure. It also explicitly states it never permanently purges and never expands a search result, which clarifies the destructiveHint=true boundary. This is exactly the operational detail annotations cannot carry.

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

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

Dense but front-loaded: the primary selection rule comes first, then capabilities, then failure semantics, then non-goals. Every clause carries information, though the semicolon-chained sentences are slightly heavy to parse.

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

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

With an output schema present, return-shape detail is unnecessary, and the description covers selection scope, action set, ordering, failure mode, and explicit non-goals. An agent has everything needed to invoke this correctly across all seven action variants.

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

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

Schema coverage is 100% and the schema itself documents each action's const and the documentIds range, so the baseline is 3. The description adds value by listing the action vocabulary in one place and stating the 1–25 ID limit and the no-search-expansion rule, letting an agent choose the right oneOf branch without reading every variant.

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

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

The description opens with a precise scope statement — batch operations for multiple explicitly selected documents sharing one action — and immediately contrasts it with the single-document siblings. It enumerates the supported actions (move, set_category, add_tag, remove_tag, trash, restore, refresh_index), so an agent knows exactly what the tool does without opening the schema.

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

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

Explicit routing: 'for one document prefer the matching single-document tool,' plus the constraint that it never expands a search result and that version restore is a separate tool. The 1–25 ID bound is called out for automation compatibility. When-to-use and when-not-to-use are both stated.

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

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

The description adds that the snapshot is restorable, which is useful context beyond the annotations. However, the annotations declare idempotentHint=false, meaning repeated calls create additional snapshots, and the description never warns that calling this twice produces duplicate snapshots or what happens on label collisions.

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

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

Two tight sentences, front-loaded with the action and its purpose. Every clause 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?

An output schema exists, so return-value explanation is unnecessary, and the operation is simple enough that little else is required. A brief note on duplicate labels or snapshot retention behavior would make it complete.

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

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

Schema description coverage is 100%, so documentId, label, and description are already fully documented in the schema. The description adds no parameter-level detail (e.g., label uniqueness or naming conventions) beyond what the schema provides. 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?

Specific verb+resource ('Save a named snapshot of an existing document') with the timing rationale ('before a planned change'). It clearly distinguishes itself from siblings like save_document and restore_document_version.

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

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

Gives explicit context for when to use it (prior to a planned change) and names the counterpart tool restore_document_version for the reverse operation. No explicit when-not guidance, but the usage context is clear.

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

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

Annotations already flag destructiveHint=true and idempotentHint=false, but the description adds the critical qualifier that documents are only detached and preserved — the single most important fact for an agent deciding whether this destructive op is safe. It also discloses the authorization boundary that category-scoped credentials will fail.

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

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

Two tight sentences with zero filler; the scope-defining side effect (documents preserved) is front-loaded, and the authorization constraint follows as a secondary condition.

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

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

An output schema exists, so return values need no explanation, and the description covers side effects, auth scope, and a single fully-documented parameter. It stops short of stating whether the deletion is recoverable or requires confirmation, which matters for a destructive, non-idempotent operation.

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

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

Only one parameter, and schema coverage is 100% with the schema itself explaining that the UUID comes from a preceding list/read operation. The description adds no syntax, format, or sourcing detail beyond what the schema already provides, so the baseline of 3 applies.

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

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

Names a specific verb (Delete) plus resource (workspace category) and immediately states the distinguishing side effect (documents are detached, not deleted). This separates it cleanly from siblings like delete_document, delete_folder, and delete_tag, whose cascade semantics differ.

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

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

Gives an explicit prerequisite and a negative condition: full workspace write access is required and category-scoped credentials are denied. It does not, however, name an alternative tool or say when to prefer this over e.g. delete_tag or delete_folder in ambiguous cases.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false and readOnlyHint=false, but the description adds meaningful context: the operation is a reversible trash move rather than a purge, and it requires write access plus an explicit delete request. It does not discuss error behavior or restore paths, but the recoverability framing is genuinely additive.

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

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

Three tight sentences that front-load the core action, then alternatives, then prerequisites and the dangerous look-alike. No filler.

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

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

An output schema exists so return values need no explanation, and the description covers the recoverability semantics, alternatives, and access requirement an agent needs to invoke this destructive-looking but non-purging 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?

Only one parameter and schema coverage is 100%, with the schema already explaining that id is the UUID from a list/read operation. The description adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource (move one document to trash) plus the crucial scope detail that content and versions are not purged. It is immediately distinguishable from batch_documents and permanently_delete_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?

Explicitly routes single-ID use here versus batch_documents(action=trash) for multiple IDs, and names permanently_delete_document as the separate irreversible alternative. When-to-use and when-not-to-use are both covered.

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

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

Annotations already flag destructiveHint=true, but the description adds genuine value beyond them: it discloses that documents survive, that child folders/documents are detached, and that write access is required. This is the kind of mutation-behavior detail annotations cannot convey.

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

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

Two tight clauses with zero waste; the core action and its key consequence are front-loaded before the permission 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?

For a single-param destructive tool with an output schema and full annotation coverage, the description is essentially complete: it covers the mutation effect, side effects, and permission need. Only explicit alternative-routing is missing.

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

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

Schema description coverage is 100%, so the single 'id' parameter (UUID from a list/read operation) is already fully documented. The description adds no syntax or format detail, 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 states a specific verb+resource ('Delete a folder') and clarifies the scope semantically ('while preserving its documents'), which meaningfully differentiates it from delete_document and delete_category. It stops just short of naming the sibling alternatives, but the operation is unambiguous.

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

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

Usage is implied by the behavioral note that documents are preserved and children detached, which suggests when this tool is preferred over a hard delete. However, it never states when to use this versus delete_document or permanently_delete_document, nor any exclusions.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the mutation profile is covered. The description adds real value beyond that: it names the required permission level (full workspace write access) and clarifies the blast radius (tag assignments removed, documents 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?

Two short sentences, zero filler, with the destructive scope and permission requirement front-loaded ahead of the reassurance about documents.

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

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

An output schema exists, so return values need not be explained, and the annotations plus description cover permissions and side effects. It stops short of stating whether the deletion is recoverable or whether tags must be unassigned first, a minor gap for a destructive operation.

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?

Single id parameter with 100% schema description coverage, so the schema fully documents syntax and origin. The description adds no parameter-level detail, which is the expected baseline when the schema does the work.

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

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

States a specific verb (delete) plus resource (workspace tag) and its side effect (removing document assignments) in one front-loaded clause. This clearly differentiates it from siblings like delete_document, delete_folder, and delete_category.

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 explicit when-to-use or when-not-to-use guidance relative to alternatives such as delete_category or set_document_tag. However, 'documents themselves remain' implicitly signals this is not a document-deletion path, which is useful disambiguation.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description's added value is the conceptual difference between a query-free traversal and a query-ranked search, but it says nothing about result volume, limits, or authorization beyond what the schema states.

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 tightly packed sentences with zero filler; the mode contrast is front-loaded after the core purpose statement. Every clause carries distinct information.

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

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

An output schema exists, so return values need not be described, and both union branches of the input are explained at a conceptual level. It is nearly complete; only limit/pagination behavior and any authorization prerequisites are left implicit in the schema.

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

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

Schema description coverage is 100%, so every parameter already carries documentation (mode consts, limit bounds, UUID formats, docIds 1-50, query max length). The description merely restates the mode/query relationship, adding no syntax or format detail beyond the schema, which is the expected baseline of 3.

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

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

States a specific verb (explore) and resource (graph relations) plus the origin of the data (readable seed documents). The two operating modes are named and contrasted, which makes the tool easy to tell apart from the CRUD-oriented siblings, though it never explicitly notes that it is the only graph tool among them.

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

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

Gives clear mode-selection conditions: neighbors for a single document with no query, search for one or more seed IDs with optional query text. It does not address when to prefer this tool over read_document or find_documents, so it stops short of full alternative routing.

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

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

Annotations already cover readOnly, idempotent, openWorld=false and destructive=false, so the safety profile is established. The description adds real context beyond that: results are limited to 'readable' documents, are scoped to the 'active scope', and search is hybrid text-plus-semantic rather than plain substring matching.

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

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

Two sentences, zero filler, with the core purpose front-loaded and the mode branches laid out in parallel clauses. Every clause earns its place by driving a distinct invocation path.

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

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

With a full output schema, rich annotations, and 100% schema description coverage, the description only needs to supply mode-selection intent, which it does. Minor gaps remain on pagination semantics, but those are adequately carried by the schema.

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

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

Schema description coverage is 100%, so the baseline is 3. The description's 'by folder or tag UUID' vs 'with tag names' phrasing mirrors the type distinction the schema already encodes, adding little beyond it, and it says nothing about page/limit behavior.

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

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

States a specific verb and resource ('Find readable documents in the active scope') and immediately disambiguates its two operating modes. However, it never distinguishes itself from nearby siblings such as read_document or list_trash, so an agent must rely on names alone to route among them.

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

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

Explicitly prescribes when to pick each mode: list for 'paginated browsing by folder or tag UUID' and search for 'hybrid text and semantic retrieval with tag names'. There is no guidance on when not to use this tool versus read_document, but the internal when-to-use routing is clear.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world behavior. The description adds meaningful context beyond them: this call does not start indexing work, and retry behavior belongs to a separate tool. It does not discuss returns, but an output schema exists.

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

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

Two sentences, front-loaded with the tool's purpose and followed by the key alternative-tool condition. There is no wasted wording.

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

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

For a single-parameter read-only status tool with rich annotations and an output schema, the description supplies the missing behavioral context: it does not trigger work and should not be confused with an explicit retry. Nothing essential for correct invocation is absent.

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

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

The single documentId parameter has 100% schema description coverage and is already well documented in the schema as a UUID from a list or read operation. The description adds no additional parameter semantics, so the baseline 3 is appropriate.

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

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

The description states a specific verb+resource+scope: reading indexing and pipeline status for one document, without starting work. It also explicitly distinguishes itself from the sibling refresh_document_index, so an agent can route correctly without opening the schemas.

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

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

It gives an explicit when-to-use condition and names the alternative sibling: use this to read status, and use refresh_document_index only for an intentional retry. That is clear routing guidance with a when-not condition.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior, but the description adds substantial context beyond them: folder uses a direct API getter, category and tag lookups use complete permission-filtered lists, and absent or out-of-scope IDs are reported as not found. These details materially help an agent understand runtime behavior.

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

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

The description is front-loaded with the core operation, followed by three succinct sentences that each add useful context. There is no redundant or filler 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 simple read operation, annotations covering safety, a full schema with 100% description coverage, and an output schema, the description provides all remaining context an agent needs: discovery guidance and error behavior. Nothing material is missing.

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

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

Schema coverage is 100% and both parameters (id and kind) are fully described in the schema. The description confirms the kind values and UUID lookup, but adds no additional semantic detail beyond what the schema already provides, so the baseline of 3 is appropriate.

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

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

States a specific verb (read) and resource (one visible folder, category, or tag by UUID), and distinguishes itself from list_workspace_structure. An agent can identify the exact operation without needing to open the schema.

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

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

Explicitly directs the agent to use list_workspace_structure to discover IDs first, providing clear context for when this tool is appropriate. It does not include exclusions for other read alternatives, but the guidance is sufficient for a lookup tool.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world behavior, so the description need not restate safety. It still adds two pieces of value beyond the structured data: the read-access requirement and the explicit guarantee that no restore or purge occurs, which is exactly the concern an agent has for a trash-listing call.

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

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

Two short sentences, front-loaded with what is listed and then scoped, with the disclaimer last. Every clause carries information: resource, visibility scope, access requirement, and disposition guarantee.

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

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

For a zero-parameter read tool with an output schema and rich annotations, the description covers the essentials; return values need not be explained. The one residual gap is that 'category scope' is ambient rather than parameterized, leaving the mechanism by which an agent selects a category scope unstated.

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

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

The tool takes zero parameters, so there is no parameter semantics for the description to clarify; the baseline for a parameterless tool is 4. Schema coverage is 100% and additionalProperties is false, leaving nothing ambiguous to compensate for.

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

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

States a specific verb and resource ('List soft-deleted documents') plus a scope qualifier ('visible to the active workspace or category scope'). It also distinguishes itself from the destructive siblings (restore_trashed_document, permanently_delete_document) by explicitly disclaiming restore/purge behavior, so an agent can separate it from them without opening a schema.

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

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

The scope clause establishes when this tool applies, and 'does not restore or purge anything' functions as a when-not signal that steers the agent toward restore_trashed_document or permanently_delete_document for those actions. However, no sibling is named explicitly, so the routing still requires inference.

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

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

Annotations already fully cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is low. The description adds the 'visible' qualifier, hinting results are permission-filtered, but says nothing about ordering, pagination, or depth 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, zero padding, with the core purpose front-loaded and the kind=folders usage hint second. Every clause earns its place.

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

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

With a rich output schema, complete annotations, and full schema coverage, the description only needs to convey purpose and the discriminator usage, which it does. The only gap is the undefined meaning of 'visible'/scope filtering.

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 each discriminator field is documented inline, so the baseline is 3. The description reinforces that parentId drives child listing, but adds no format or constraint detail beyond the schema.

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

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

States a specific verb (List) and the resources it returns (visible folders, categories, or tags) with explicit scope (active workspace or category scope). The resource set cleanly distinguishes it from siblings like list_trash or read_document, though no sibling is named directly.

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

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

It gives one concrete usage cue – 'Set kind=folders to inspect root folders or children of parentId' – which tells the agent when the folders branch applies. However it offers no guidance on choosing between categories and tags, nor any exclusions or named 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?

Annotations already flag destructiveHint=true and idempotentHint=false, so the safety profile is covered structurally. The description goes beyond them by disclosing that version history is destroyed too and that the document must already be in trash, which is exactly the kind of consequence an agent needs to warn about.

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

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

Two sentences, zero filler, with the irreversible scope stated first and the precondition second. Every clause 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?

Output schema exists so return values need not be explained, and the description covers the destructive scope, irreversibility, and the gating precondition. Nothing an agent needs to invoke this safely is missing.

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

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

Schema description coverage is 100% and the single 'id' parameter is fully documented as a UUID from a list or read operation. The description adds no further meaning (no note that the id must reference a trashed item), so baseline 3 applies.

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

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

States a specific verb ('purge'), resource ('document'), and scope ('already in trash, including its version history'), which cleanly distinguishes it from the sibling delete_document (soft delete) and restore_trashed_document. An agent can route correctly without opening any schema.

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

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

Explicitly constrains usage to an explicit user request and sequences it after list_trash, which is strong guidance. It stops short of naming delete_document as the softer alternative to prefer when the user has not asked for permanent removal.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered; the closing 'All views are read-only' reinforces rather than adds. The per-view behavioral distinction (what each branch returns) is the real added value beyond structured data.

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

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

Three tight sentences: purpose first, option semantics second, safety note last. No filler, no repetition, and the front-loaded sentence carries the identity of the tool.

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

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

With an output schema present, return values need not be described, and both parameters plus the modal branches are covered. Nothing essential to invoking this tool correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The schema's own view descriptions are circular ('Select the detail operation explicitly'), so the description genuinely adds meaning by explaining what detail, markdown and versions actually yield; onlySnapshots remains schema-documented only.

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

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

States a specific verb (read), resource (one document) and lookup key (UUID), and enumerates the three view modes, which is more than a restatement of the name. It does not, however, distinguish itself from sibling read-ish tools such as find_documents or get_document_index_status, so the agent must infer the boundary.

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

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

Gives explicit selection criteria for each mode: detail = content and metadata, markdown = portable export, versions = saved revisions and snapshots. That is genuine when-to-use guidance for the tool's own branches, though it offers no guidance on when to prefer this tool over sibling readers.

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

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

Annotations already declare the safety profile (destructiveHint=false, idempotentHint=false), so the description's job is to add what they can't. It discloses the asynchronous queueing model, that routine edits auto-schedule indexing, and that a status check should precede the call — real behavioral context. It stops short of describing throttling, latency, or what the returned job handle looks like, so not a full 5.

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

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

Two clauses, zero filler, and the primary action is front-loaded ahead of the routing alternative and the prerequisite caveat. Every sentence carries information an agent needs to act correctly.

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

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

For a single-parameter async operation with full schema coverage, existing annotations, and an output schema defining the return, the description covers the remaining burdens: the async model, the sibling alternative, the auto-indexing caveat, and the prerequisite status check. Nothing necessary to call it correctly is missing.

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

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

Schema description coverage is 100% and there is only one parameter, with the schema already documenting the UUID format and its origin. The description adds no syntax, format, or constraint detail beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb and resource ('Queue an explicit asynchronous reindex for one document') and immediately distinguishes itself by naming the sibling alternative for the multi-document case, batch_documents(action=refresh_index). An agent can route between the two without opening either schema.

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

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

Gives explicit when-to-use (single explicit ID), the alternative for multiple IDs (batch_documents), and a when-not-to-bother condition: routine content and placement changes already schedule indexing. It also names a prerequisite step, checking get_document_index_status first, which is named exactly as a sibling tool.

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

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

Annotations already declare destructiveHint=true and non-idempotent, but the description adds valuable behavior beyond them: the operation mutates current content and queues re-indexing, and it explicitly excludes trashed-document restoration. It stops short of stating reversibility (whether the restored state can itself be rolled back), which is the one gap for a destructive write.

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 filler, with the primary action front-loaded and the scope exclusion placed at the end where it reads as a guardrail. Every clause carries information.

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

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

For a two-param destructive restore with an output schema and full annotation coverage, nothing essential is missing: the source of the version, the mutation effect, the indexing side effect, and the trashed-document exclusion are all present.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaning by pointing to read_document(view=versions) as the origin of the versionId, which is more actionable than the generic schema text 'UUID returned by the corresponding list or read operation.'

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

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

States a specific verb+resource ('Restore content from a version or snapshot') and immediately scopes it by naming the source of the version. The final clause distinguishes it from restore_trashed_document, so the agent can separate the two without opening either schema.

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

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

Gives explicit when-to-use context -- restore from a version listed by read_document(view=versions) -- and an explicit exclusion ('does not restore a trashed document'). It would be a 5 if it named restore_trashed_document as the alternative for that excluded case, but the condition itself is unambiguous.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=false, so safety is structured. The description adds meaningful semantics about what is restored ('the document itself, unlike restore_document_version which changes content'), but does not cover permissions, side effects, or reversibility beyond that.

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

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

Two compact sentences with no wasted words. The core action is front-loaded, and the alternatives are appended 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?

An output schema exists, so return values need not be explained, and annotations cover safety. The description covers purpose, alternatives, and the semantic distinction from restore_document_version. It could mention the prerequisite that the document must currently be in trash, but this is strongly implied.

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

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

Schema description coverage is 100% and there is only one parameter (id), whose format and meaning are fully documented in the schema. The description adds no parameter-level detail beyond what the schema already provides, so the baseline 3 is appropriate.

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

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

The description uses a specific verb and resource ('Return one document from trash to the active library') and explicitly distinguishes itself from two siblings: batch_documents for multiple IDs and restore_document_version for content changes. An agent can select this tool without opening schemas.

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

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

It names the alternative for multiple explicit IDs (batch_documents(action=restore)) and contrasts with restore_document_version, giving clear positive routing. It lacks an explicit when-not condition (e.g., permanently deleted items, already-active documents), so it stops short of a 5.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false, and readOnlyHint=false, so the safety profile is covered structurally. The description adds genuine value beyond that by disclosing the credential scope requirement, a failure mode the annotations do not capture. It stops short of saying what an update overwrites or that the operation is not idempotent, so it is not a 5.

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

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

Two tightly written sentences with the action stated first and the constraint second. No filler, no restating of the title, nothing that fails to earn its place.

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

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

With an output schema present and annotations covering the safety profile, the description only needs to add purpose and any non-obvious constraints, both of which it does. The one gap is that it does not clarify partial-update behavior for the update branch, but for a tool of this complexity that is a minor omission.

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

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

Schema description coverage is 100%, and the oneOf branches document action, name, id, and order with their own descriptions, so the schema does the heavy lifting. The description only refers generically to 'create or update' and adds no format, ordering, or partial-update semantics beyond that.

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

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

States a specific verb pair and resource ('Create or update a workspace category'), which is clear enough to distinguish it from delete_category and save_tag/save_folder. It does not, however, explicitly call out that it is the only category-writing sibling, so sibling routing is inferential.

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

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

The description gives a real prerequisite (full workspace write access; category-scoped credentials cannot manage categories), which is useful context for when the call will succeed. It never names alternatives or states when to prefer this tool over delete_category or save_tag, so usage guidance is implied rather than explicit.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false; the description adds real value beyond them by stating the access level required per operation (write for creation/placement, edit for content) and that content or placement changes queue normal indexing. It does not, however, warn that update can clear content or placement, which is the main reason the tool is flagged destructive.

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 dense sentences with the core purpose front-loaded and no filler; the semicolon-clause on permissions is slightly compressed but every clause carries distinct information.

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

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

An output schema exists so return values need no explanation, and the description covers modes, alternatives, permissions, and indexing side effects. The one gap is not surfacing that update with empty content/null placement clears existing data, a material behavior for a destructive-annotated tool.

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

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

Schema description coverage is 100%, so baseline is 3. The description goes beyond the schema by explaining the action discriminator as the branch selector and by contrasting the placement-change case with batch_documents, which helps an agent pick parameters correctly rather than just reading field docs.

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

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

Opens with a specific verb+resource ("Create or update one document") and immediately differentiates the two modes and the sibling that handles the multi-document case, batch_documents. An agent can distinguish it from save_folder/save_category/save_tag without opening a schema.

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

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

Explicitly states action=create for new documents and action=update for existing ones, names batch_documents as the alternative for the same placement change across multiple existing documents, and lists the permission prerequisites per operation type. When-to-use, when-not, and alternatives are all present.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false, and readOnlyHint=false, so the mutation profile is covered structurally. The description adds genuinely new behavior: the API enforces category boundaries and queues affected documents for reindexing, which goes beyond what annotations convey.

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

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

Two tight sentences with the core capability front-loaded and the side-effect detail second. No filler, no redundancy with the title or schema.

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

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

An output schema exists, so return values need not be explained, and annotations carry the safety profile. The description covers the two operations and the reindexing side effect, leaving only minor gaps like whether category assignment is required or how moves across boundaries fail.

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

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

Schema description coverage is 100%, so the schema already documents name, id, parentId, categoryId, order, and the action discriminators. The description only names the two actions and the rename/move intent; it adds no syntax or format detail beyond the schema, making the baseline 3 appropriate.

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

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

The description states a specific verb+resource ('Create or update a folder') and elaborates the two modes, distinguishing action=create from action=update (rename/move). It is clear on its own, though it does not explicitly contrast with siblings such as save_category or delete_folder.

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 implies when each action applies ('action=update can rename or move an existing folder'), giving some routing guidance, but never states when to prefer this tool over siblings (e.g., delete_folder, list_workspace_structure) or any prerequisites for calling it.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so safety is covered. The description adds genuinely new behavioral context: the permission requirement and the side effect that renaming or recoloring reindexes affected documents, which the agent could not infer from the annotations.

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

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

Two tightly written sentences with the core action front-loaded and the operational caveats second. No redundant restatement of the title or schema.

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

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

With an output schema present and full parameter coverage, the description only needs to carry the behavioral and permission context, which it does. It stops just short of routing guidance to sibling tools, which is the only real gap.

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

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

Schema description coverage is 100%, so the create/update oneOf branches, name, color and id constraints are all documented in the schema itself. The description adds no parameter-level detail, so baseline 3 applies.

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

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

States a specific verb+resource ('Create or update a workspace tag'), clearly distinguishing it from the delete_tag sibling by its save semantics. It does not explicitly contrast with save_category or save_folder, but the resource noun makes the target unambiguous.

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

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

Gives one precondition (full workspace write access required) and one consequence (renaming/recoloring triggers reindexing), which implies when it is appropriate. However, it never says when to prefer delete_tag, set_document_tag, or the create vs. update action branches beyond what the schema enforces.

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

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

Annotations already declare destructiveHint=true and non-idempotent, but the description adds two things they don't: an authorization prerequisite ('requires edit access to each document') and a critical nuance that action=remove unlinks the assignment without deleting the tag itself, which reframes what 'destructive' means here. Missing detail on failure behavior for duplicate adds keeps it from a 5.

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

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

Three short sentences, front-loaded with the core action, then routing guidance, then the caveat. No filler or restated schema 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?

An output schema exists, so return values need no explanation, and annotations carry the safety profile. For a single-target mutation with an explicit alternative and an auth prerequisite, an agent has everything needed to invoke it correctly.

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

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

Schema description coverage is 100% and all three parameters are already documented in the schema, including the enum meaning for action. The description's 'Add or remove' phrasing mirrors the schema text rather than adding format or constraint detail, so baseline 3 is correct.

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

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

States a specific verb pair and resource ('add or remove an existing tag assignment') plus the scope constraint 'on one document', which immediately separates it from batch_documents. An agent can classify the tool without opening the schema.

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

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

Explicitly names the alternative (batch_documents) and the condition that selects it ('for the same tag action across multiple explicit IDs'). It also enumerates both modes of operation (add vs remove), leaving nothing to inference.

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