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

Annotations already declare destructiveHint=true and idempotentHint=false, but the description adds substantial context beyond them: sequential processing with per-document workspace and category permission checks, possible partial success, and failure-stop behavior on auth or rate-limit errors. Rich, non-redundant disclosure of 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?

Front-loaded with the core contract (one action, 1–25 IDs) before enumerating actions and behavior. Every clause carries information; no filler or repetition.

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

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

For a complex oneOf-based batch mutation tool with an output schema present, the description covers action set, scope limits, permission model, partial-failure semantics, and failure-stop behavior. An agent has everything needed to invoke it correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description restates the action list and the 1–25 bound that the schema already documents; it adds no format, default, or null-handling detail beyond what the per-branch schema descriptions provide.

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 (apply one action) and resource (documents), enumerates all seven supported actions, and distinguishes the tool from siblings by declaring that permanent purge and version restore are separate tools. An agent can identify this as the batch-mutation 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 constrains usage to 1–25 explicitly selected IDs with no search expansion, and names the alternative tools for the excluded operations (permanent purge, version restore). Both the when and the when-not are stated.

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

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

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 readOnly=false, so the safety profile is partly covered. The description adds genuinely new context beyond that: this is a recoverable trash operation that preserves content and versions, and it only applies to writable documents. It does not discuss permissions or repeat-restore behavior, so not a 5.

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

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

Two sentences, zero filler, and the highest-value information (recoverable soft delete) is front-loaded before the routing hint. 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?

An output schema exists, so return values need no explanation. Combined with the use-condition, the named alternative, and the recoverability/writability constraints, an agent has everything needed to invoke this correctly.

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

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

With one parameter and 100% schema description coverage, the schema already fully documents the required 'id' (UUID from a list/read operation). The description adds no format or sourcing detail for the parameter, 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 a writable document to trash') plus the exact effect on content and versions. It also names the contrasting sibling, so an agent can distinguish this soft-delete from permanently_delete_document without opening either schema.

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

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

Explicitly conditions use ('Use only on an explicit delete request') and names the alternative action (permanently_delete_document) with its distinguishing trait (irreversible). Nothing about when to pick this tool is left to inference.

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

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

Annotations already 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 write/idempotency/destructive profile, so the bar is lower. The description adds real behavioral context beyond them: the work is asynchronous and queued, and routine edits are auto-indexed, implying this is for exceptional cases only. It could say more about what happens on a redundant call given idempotentHint=false, but the added value is solid.

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

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

Two sentences, zero filler, with the core action front-loaded and the caveat plus prerequisite check following. 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?

An output schema exists, so return values need not be described. The description covers purpose, timing, and prerequisite adequately; only edge-case behavior on a no-op or already-indexed call is left unstated, which is a minor gap.

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

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

There is only one parameter and schema description coverage is 100%, so the schema fully documents documentId as a UUID. The description adds no format or sourcing detail beyond the schema, making the baseline 3 correct.

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

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

The description states a specific verb and resource ('Queue an explicit asynchronous reindex for one document') and scopes it to a single document. It also names the sibling tool get_document_index_status, so an agent can distinguish it from neighboring tools without opening a schema.

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

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

It explicitly states when NOT to use it ('Routine content and placement changes already schedule indexing') and routes the agent to a prerequisite check ('check get_document_index_status first'). The condition that selects this tool versus its alternative is spelled out.

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 the full safety profile (destructiveHint=false, idempotentHint=false, openWorldHint=false), so the agent knows this is a non-destructive local mutation. The description adds the useful fact that the document is returned to the active library and what it restores, but says nothing about failure when a document is not trashed or the non-idempotent behavior the annotations imply.

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 waste, and the core action is front-loaded ahead of the sibling disambiguation. 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?

For a single-required-parameter restore tool with an output schema (so return values need no explanation) and annotations covering safety, the definition gives the agent what it needs. Only the non-idempotent/not-trashed failure behavior is left implicit.

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

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

With one parameter at 100% schema description coverage, the schema already documents the id fully ('UUID returned by the corresponding list or read operation'). The description adds no syntax or format detail beyond that, so the baseline 3 applies.

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

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

States a specific verb+resource ('Return one soft-deleted document to the active library') and explicitly contrasts itself with the confusable sibling restore_document_version. An agent can select this tool 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?

Names the alternative it could be confused with (restore_document_version) and the discriminating condition (restores the document vs. changes content). It stops short of routing guidance against other siblings like permanently_delete_document or list_trash, so it is clear but not exhaustive.

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

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

Annotations already declare 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 flag mutation and destructiveness (readOnlyHint=false, destructiveHint=true), but the description adds real value beyond them: the permission model per action and the side effect that content or placement changes queue normal indexing, which is important asynchronous behavior an agent must anticipate.

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 primary purpose, followed by permissions and then the indexing side effect. No filler; each sentence carries actionable 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 mutation tool that already has annotations and an output schema, the description supplies the remaining essentials: dual-mode behavior, access requirements per mode, and the asynchronous indexing consequence. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents title, content, folderId, categoryId, id and the action constraints, making 3 the baseline. The description only elaborates the action values and their access requirements, adding marginal semantic 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?

The description names a specific pair of operations (create and update) on a clear resource (document), so an agent immediately knows this is the upsert-style save tool. It distinguishes itself de facto from save_category/save_folder/save_tag by resource, but it never explicitly states that differentiation in text.

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 concrete conditions for choosing between the two modes: action=create needs write access, action=update needs edit access for content and possibly write access for placement. That is useful routing context, though it does not mention alternative tools (e.g., restore_document_version) or when-not-to-use this tool.

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

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

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 readOnlyHint=false, destructiveHint=true, idempotentHint=false, so the safety profile is covered. The description adds genuinely non-obvious behavior: removal destroys only the assignment and preserves the underlying tag, plus the edit-access requirement. It does not explain re-adding an already-present tag (relevant given idempotentHint=false).

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 waste, front-loaded with the operation and followed by the two most important constraints (permission, remove semantics). Nothing to trim.

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 definition need not explain return values. It covers scope, permission and remove semantics; the only remaining gap is the add path's behavior when the tag is already assigned.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces that the tag must already exist and that exactly one assignment is affected, but adds no format or lookup guidance beyond what the schema already says about tagId/documentId.

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

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

States a precise verb pair (add/remove) and a precise resource (one existing tag *assignment* on a document), which cleanly separates it from siblings like save_tag/delete_tag that operate on tags themselves. The clause 'action=remove preserves the tag itself' actively draws that boundary for the agent.

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

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

Gives a real precondition ('requires edit access to that document') and implies when remove is preferable to delete_tag, but never states when to use this tool versus alternatives or any when-not conditions. Usage is inferable rather than explicit.

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