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

Annotations already declare readOnlyHint, destructiveHint, and idempotentHint. The description adds value by clarifying that this is a convenience view not audit-complete, that it never reads Cascade directly (thus cached), and describes oversized responses returning bounded _cache metadata. No contradiction with annotations.

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

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

The description is five sentences, front-loaded with the main purpose. Each sentence adds meaningful information without redundancy. It is appropriately sized for the tool's complexity.

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

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

For a read tool with no output schema and 4 parameters, the description explains response format (JSON text), authoritative structuredContent, and oversized response behavior. It also references cascade_read for context. While additional details on response structure could help, it is largely complete given the annotations.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds context about JSON Pointer, bounded subtree, and authoritative structuredContent, but does not provide parameter-specific details beyond the schema. It adds some value but not significant.

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

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

The description clearly states the verb 'fetch' and the resource 'exact structuredData nodelet or bounded subtree at a JSON Pointer', and situates the tool after cascade_read. It distinguishes from siblings by noting it is a convenience view over structuredDataNodes, not an audit-complete view, and that it never reads Cascade 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?

The description explicitly says 'Use after cascade_read', providing clear context. However, it does not explicitly state when not to use this tool or list alternative tools for different scenarios, though it implies that for full asset reads one should use cascade_read.

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

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

Beyond annotations (readOnly, idempotent), the description reveals that the tool never reads Cascade directly, supports slicing with offset/length, returns JSON text, and that structuredContent is authoritative for fitting responses. This adds valuable behavioral context.

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

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

Four front-loaded sentences concisely convey purpose, usage, behavior, and edge cases. No redundant information; every sentence adds value.

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

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

Without an output schema, the description explains response types (JSON text, structuredContent, oversized cache metadata) and links to cascade_read_response. It covers parameter behavior (slicing, pointer) and dependency on cascade_read, providing a complete picture.

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

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

Schema coverage is 50% (asset_handle and pointer have descriptions; offset and length lack descriptions). The description adds context for JSON Pointer and slicing, but does not fully define offset and length parameters. Baseline 3 due to partial coverage, with slight improvement from description.

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

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

The description uses specific verbs and resources: 'Retrieve the exact raw cached value at a JSON Pointer' and states it should be used after cascade_read, clearly distinguishing from sibling tools like cascade_read and cascade_read_response.

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

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

The description explicitly says 'Use after cascade_read' and explains when to use structuredContent vs _cache metadata. It also contrasts with cascade_read for oversized responses, but does not provide explicit when-not-to-use or alternative tool names.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description adds critical behavioral details: never reads Cascade directly, complete flag behavior, response format (JSON text vs structuredContent), overflow handling with _cache metadata, and relationship to cascade_read read_mode.

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

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

The description is concise yet comprehensive, with every sentence adding value. It front-loads the primary purpose and efficiently packs behavioral, usage, and response details.

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

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

Given the tool's complexity (11 parameters, no output schema), the description covers key aspects: data source, filtering capabilities, pagination, response format, and integration with cascade_read. It lacks detailed parameter descriptions but is otherwise complete for a list tool.

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

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

With only 9% schema description coverage (only asset_handle described), the description mentions filter types (pointer, key, value, scalar, reference) and cursor pagination, but does not explain each of the 11 parameters individually, leaving significant ambiguity.

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

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

The description clearly states the tool lists cached raw asset facts, with specific mention of object, array, key, and scalar facts, filters, and pagination. It avoids tautology but does not explicitly differentiate from sibling tools like cascade_asset_list_nodelets.

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

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

The description advises 'Use after cascade_read' and explains the tool never reads Cascade directly, providing context for when to use. However, it does not exclude alternatives or specify 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 readOnlyHint, destructiveHint, idempotentHint, openWorldHint. The description adds valuable context: it never reads Cascade directly, handles oversized responses by returning bounded _cache metadata, and states that structuredContent is authoritative when the response fits. This goes beyond annotations.

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

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

The description is a single paragraph of 4 sentences, each adding unique value. It is concise but could benefit from breaking into logical sections or bullet points for readability. No fluff.

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

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

Given 4 parameters, no output schema, and rich annotations, the description covers usage dependency on cascade_read, pointer semantics, caching behavior, and response format. It lacks details on cursor and parameters, but those might be standard. Overall adequate.

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

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

Schema coverage is 50% (cursor and lack descriptions). Description adds meaning for asset_handle and pointer (e.g., 'REQUIRED' and usage of empty string for root), but does not elaborate on cursor and . Baseline 3 with low coverage; description partially compensates.

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 title and description clearly state the tool lists cached Cascade asset nodelets for a given JSON Pointer. It distinguishes from siblings like cascade_asset_get_nodelet (single nodelet) and cascade_read (direct read). The verb 'list' and resource 'cached asset nodelets' are specific.

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

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

The description explicitly says 'Use after cascade_read' and how to use pointer for root nodelets. It contrasts with cascade_read's read_mode control. However, it does not provide explicit when-not-to-use scenarios or alternative tool names beyond cascade_read.

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, destructiveHint, and idempotentHint, setting a safe baseline. The description adds important behavioral details: the tool never reads Cascade directly, responses are JSON text, structuredContent is authoritative within size limits, and oversized responses return bounded _cache metadata. These go beyond annotations to inform the agent about response handling.

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

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

The description is compact, using four sentences to convey purpose, usage context, and key behavioral traits. It front-loads the critical instruction ('Use after cascade_read'). While efficient, it could be slightly improved by integrating parameter guidance without adding bloat.

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

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

Given the tool's complexity (6 parameters, no output schema), the description covers high-level context (purpose, cache behavior, tie to cascade_read) but lacks parameter explanations and detailed output structure. It mentions response format (JSON, structuredContent, _cache) but does not describe fields or pagination, leaving gaps for an agent to use the tool effectively.

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

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

Schema description coverage is only 17%, with only asset_handle documented. The main description does not explain any of the other five parameters (pointer_prefix, reference_kind, etc.), nor does it provide usage hints for filtering. The description fails to compensate for the low schema coverage, leaving agents without guidance on how to customize queries.

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

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

The description clearly states the tool lists Cascade-native references from a cache, with specific sources (id/path pairs, asset nodes, metadata, etc.). It explicitly positions the tool as a companion to cascade_read and distinguishes itself by noting it never reads Cascade directly, differentiating it from cascade_read and other tools.

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

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

The description explicitly says 'Use after cascade_read,' providing clear context for when to invoke this tool. It implies the tool is for accessing cached data without live reads, but does not explicitly list when not to use it or name alternative tools for other scenarios. The guidance is functional 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 readOnly, idempotent, and non-destructive behavior. The description adds valuable details beyond annotations: 'never reads Cascade directly,' explains response format (JSON text with structuredContent authority and _cache metadata for oversized responses). This enhances transparency.

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

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

The description is relatively concise and front-loaded with the core purpose. It uses multiple sentences but each adds meaningful information. However, it could be more structured by separating usage guidelines from behavioral notes.

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 8 parameters with low schema coverage and no output schema, the description provides some behavioral context (response handling, cursor? not mentioned) but lacks details on return structure beyond 'JSON Pointer and offset provenance.' Pagination and parameter usage are not explained, making it incomplete for complex scenarios.

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 only 13% (only asset_handle described). The description does not explain other parameters like artifact_kind, pointer_prefix, cursor, limit, etc. It lists artifact types but doesn't map them to parameters, leaving the agent without sufficient guidance on how to filter or paginate.

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

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

The description clearly states the tool enumerates derived link/path-like artifacts from cached raw string scalar facts, listing specific types like http_url, site_link, href, etc. It distinguishes from siblings like cascade_asset_list_facts by focusing on scalar artifacts rather than general facts.

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

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

The description explicitly says 'Use after cascade_read,' providing clear context for when to invoke the tool. It does not explicitly mention alternatives or when not to use it, but the instruction is sufficient given the sibling context.

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

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

Annotations already declare readOnlyHint and idempotentHint. The description adds valuable context: 'This tool never reads Cascade directly,' explains response format ('JSON text') and handling of oversized responses ('bounded _cache metadata'). No contradiction with annotations.

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

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

The description is 5 sentences and fairly concise. The last sentence about read_mode could be moved to cascade_read description, but overall it is not overly long and mostly relevant.

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

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

No output schema exists, so description should detail return values. It mentions returning 'JSON Pointer to the keyed value plus parent pointer' and handling oversized responses. However, it omits pagination via cursor/limit and does not explain the key parameter semantics, leaving gaps.

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

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

Schema coverage is only 17% (only asset_handle described). The description does not explain the other five parameters (key, key_contains, pointer_prefix, cursor, limit), so despite low coverage, the description fails to compensate, leaving the agent without necessary detail.

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

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

The description clearly states the tool's purpose: 'Find object key occurrences anywhere in the cached raw Cascade response.' It specifies the verb and resource, and distinguishes from siblings by noting it operates on cached data after cascade_read, not directly reading Cascade.

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

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

Explicitly says 'Use after cascade_read,' providing context for proper usage. It also explains that the tool never reads Cascade directly, implying the prerequisite. However, it does not explicitly state when not to use or list alternatives, so a 4 is appropriate.

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

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

Beyond annotations (readOnlyHint, etc.), the description adds critical behavioral details: it never reads Cascade directly (cached operation), response format (JSON text with structuredContent authoritative), oversized behavior (bounded _cache metadata), and dependency on cascade_read's read_mode. These significantly enhance transparency without contradicting annotations.

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

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

The description is five sentences, each adding distinct value: usage gate, core function, return details, data source caveat, oversized behavior, and read_mode relationship. No redundant or extraneous content; tightly packed with 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 tool with 9 parameters and no output schema, the description covers high-level behavior but lacks details on parameter usage (e.g., value_contains, cursor, limit) and full return structure. While it references cascade_read and cascade_read_response for context, the omission of parameter descriptions and output format leaves gaps in completeness.

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

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

The input schema has only 11% coverage (only asset_handle described as REQUIRED). The description adds no parameter-specific information, failing to compensate for the low schema coverage. It does not explain the other 8 parameters (value_contains, pointer_prefix, etc.), leaving their semantics entirely to the schema's empty descriptions.

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

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

The description clearly states the tool searches full scalar values in the cached raw Cascade response, distinguishing it from shortened previews. It specifies the resource (cached raw asset scalar values) and the action (search), and mentions a prerequisite (use after cascade_read), making the purpose highly specific and actionable.

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

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

The description explicitly instructs to use after cascade_read, providing a clear prerequisite. It contrasts with shortened previews, implying when not to use, but does not name alternative tools like cascade_asset_search_keys or cascade_asset_get_value. The mention of oversized responses and cascade_read_response gives additional context without exhaustive exclusion.

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 indicate readOnlyHint=false, destructiveHint=false, idempotentHint=false. The description adds that the lock is released, working copy becomes the new version, and comments are stored. It lists error messages ('Asset not found', 'not checked out', etc.). However, it doesn't explicitly address idempotency (that calling twice fails) or clarify if the operation is reversible, which would enhance transparency.

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

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

The description is well-structured with sections (Args, Returns, Examples, Error Handling). However, it ends with an irrelevant block about 'Responses are JSON text... cascade_read_response' that seems copied from another tool, adding clutter. This reduces conciseness and focus.

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

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

Despite no output schema, the description fully explains the return format (OperationResult with success/message). It covers the lifecycle with check_out, error handling, and prerequisites. All necessary information for an agent to invoke the tool correctly is 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% but the main description goes beyond by detailing the nested structure of 'identifier' (id, path, type) and the required nature of 'comments'. It provides concrete examples and error conditions, adding significant value over the schema alone.

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

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

The description clearly states the tool's function: release a checked-out asset, commit the working copy, and store comments in version history. It distinguishes itself from sibling 'cascade_check_out' by explicitly pairing with it. The verb 'check in' is precise and unambiguous.

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

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

The description includes explicit 'Use when' and 'Don't use when' examples, specifying that it should be used to commit changes and not if the asset isn't checked out or if another user holds the lock. It also states the caller must be the same user who checked out, providing clear decision guidance.

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

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

Discloses behavioral traits: required for some asset types, creates working copy, only user can edit, others see previous version, response includes workingCopyIdentifier, must pair with check_in. Annotations already indicate non-readonly and non-destructive. The description adds context beyond annotations. Minor deduction for irrelevant tail about structuredContent.

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

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

Description is long but well-structured with sections. However, it includes irrelevant text about structuredContent and cascade_read that doesn't belong, reducing conciseness.

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

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

Given no output schema, the description provides a clear return schema and error handling. Examples and pairing with sibling are provided. Slightly incomplete due to irrelevant tail, but overall adequate for the tool's complexity.

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

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

Schema description is minimal ('The asset to check out...'). The description's Args section adds nested structure (id, path, type) with constraints (type required, id preferred). This adds significant meaning beyond the schema.

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

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

The description clearly states that the tool locks a Cascade asset for exclusive editing, creating a working copy. It distinguishes from sibling tools like cascade_check_in for releasing the lock.

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 when-to-use guidance (before editing, for certain asset types) and when-not-to (finished editing, read-only operations). Also references cascade_check_in as the counterpart.

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 indicate non-read-only and non-destructive; description adds that the original stays and copy gets its own ID, destination and name are required, and workflow can be run. However, there is a trailing paragraph about response formats and cascade_read that seems irrelevant and slightly confusing.

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 structured with clear sections (Args, Returns, Examples, Error Handling). However, the error handling section includes unrelated text about JSON responses and cascade_read, and there is minor repetition ('both required'). Still mostly concise.

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 tool with 3 complex parameters and no output schema, the description covers purpose, parameter details, examples, error handling, and usage guidelines. It provides a complete picture despite the minor irrelevant text.

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

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

The input schema has minimal descriptions (100% coverage but vague). The description elaborates on each parameter, including nested structure, required fields within copyParameters, and examples. This adds significant meaning beyond the schema.

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

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

The description clearly states the tool copies an asset to a new container with a new name, creating an independent copy. It distinguishes itself from siblings like cascade_move (original stays) and cascade_site_copy (for sites).

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

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

Provides explicit when-to-use (duplicate an asset) and when-not-to-use (rename in place → cascade_move, copy site → cascade_site_copy). Includes an example and error handling scenarios.

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

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

Beyond annotations (readOnlyHint false, etc.), the description details the creation behavior: returns asset ID, error handling cases (parent folder not found, asset name collision, permission denied), and text encoding warnings. No contradiction with annotations.

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

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

The description is lengthy due to the complexity of handling 48 asset types, but it is well-structured: purpose, payload conventions, shapes, examples, error handling. Could be slightly more concise, but the structure earns a high score.

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

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

Given the tool's complexity (multiple asset types), lack of output schema, and rich annotations, the description covers purpose, usage, parameters, return value, error handling, examples, and alternatives. It is comprehensive.

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 parameter 'asset' is explained in depth: envelope structure, common shapes for all asset types, required fields, admin-area differences, and payload conventions (prefer IDs, omit optionals). This adds immense value beyond the schema's minimal description.

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

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

The description starts with 'Create a new asset in Cascade CMS,' a specific verb+resource. It distinguishes from sibling tools (cascade_edit, cascade_copy) by stating when not to use it.

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

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

Provides explicit 'Use when' examples and 'Don't use when' with alternatives. Also includes payload conventions for every create call, guiding proper usage.

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

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

Annotations already mark destructiveHint and idempotentHint. The description adds crucial details: operation is irreversible, no recovery, permission checks, and error handling messages. No contradiction with 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?

Well-structured with clear sections (Args, Returns, Examples, Error Handling). However, the final paragraph about cascade_read and responses is unrelated to this tool and adds noise, slightly reducing conciseness.

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

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

For a simple tool with one parameter and no output schema, the description covers purpose, parameters, usage, errors, and expected behavior completely.

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?

Despite 100% schema coverage, the description explains the identifier parameter structure, required fields (id, type), and that id comes from cascade_list_messages. Adds meaningful context beyond the schema.

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

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

The description clearly states it permanently deletes a message from the authenticated user's Cascade mailbox. It distinguishes from siblings like cascade_mark_message (archive) and indicates it's not for bulk deletion.

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

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

Provides explicit when-to-use (permanently clear spam) and when-not-to-use (use archive instead, no bulk deletion). Also specifies that messages must belong to the authenticated user.

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 (readOnlyHint=false, destructiveHint=false) are present. The description adds important behavioral details: edit replaces the entire asset body (not a partial patch), some types require check-out, and error conditions (not found, permission, locked, validation). This goes beyond the annotations, though the replacement behavior could be seen as partially contradicting destructiveHint=false, but it is not a true contradiction.

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 long but well-structured into sections (intro, workflow, conventions, args, returns, examples, don't use, errors). Every sentence adds value; however, some redundancy exists (e.g., error handling is repeated in two places). Front-loaded with the core verb+resource.

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

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

Given the complexity of editing assets (multiple types, check-out requirement, full replacement semantics), the description covers workflow, parameter structure, return format (OperationResult), and common errors. No output schema exists, but returns are described. For a mutation tool, this is highly complete.

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

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

Schema coverage is 100% with a single 'asset' parameter. The description adds crucial meaning: 'Must include id to identify the target asset', 'Parent-folder fields are ignored on edit', and payload conventions like preferring id over path. This significantly enhances the bare 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 begins with 'Edit an existing Cascade CMS asset,' which clearly states the verb ('edit') and resource ('Cascade CMS asset'). It explicitly distinguishes from sibling tools like cascade_create, cascade_read, and cascade_move by contrasting when to use this tool vs. others.

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

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

The description provides explicit guidance on when to use the tool (examples like 'Update a page's metadata'), when not to use it ('Don't use when: The asset doesn't exist — use cascade_create'), prerequisites ('requires a prior cascade_check_out'), and the recommended workflow (symmetric with cascade_read in raw mode).

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 indicate non-readonly, non-destructive, non-idempotent, open-world. The description adds critical behavioral details: it replaces the ACL wholesale (any omitted users lose explicit entry and fall back to allLevel), the recommended workflow (read first, modify array, then write), and that applyToChildren propagates recursively. No contradictions with 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?

Description is well-structured with sections for Args, Returns, Examples, Error Handling. Uses bolding and bullet points. However, it is somewhat verbose; could be trimmed slightly without losing clarity. Still effective for agent comprehension.

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

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

Given no output schema, the description fully explains return values (Cascade OperationResult). It covers all parameters, behavioral nuances, error cases, and provides multiple examples. Completely equips the agent to use the tool correctly.

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

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

Schema coverage is 100%, baseline 3. The description goes beyond schema by explaining the semantics of aclEntries (optional but if omitted only allLevel applies), the structure of identifier (id vs path), and the behavior of applyToChildren (for containers only, default false). Examples clarify usage.

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

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

The description clearly states the tool modifies access rights (ACL) for a Cascade asset, optionally applying to descendants. It uses specific verbs ('modify', 'replaces') and resources ('access rights', 'ACL'). It distinguishes from siblings by naming alternatives like cascade_read_access_rights and cascade_edit_workflow_settings.

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 provides when-to-use examples ('Grant group editors write access', 'Lock a folder tree down') and when-not-to-use ('Don't use when: You only want to read', 'Don't use when: You want to change workflow policy') with direct references to sibling tools.

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

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

Annotations indicate readOnlyHint=false (mutation) and no destruction or idempotency. The description adds critical context: changes take effect server-wide immediately, requires system-admin credentials, and details error handling (preference not found, invalid value, permission denied). No contradiction with annotations.

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

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

The description is front-loaded with the main action and usage guidelines, but it includes a large boilerplate block after 'Error Handling' that discusses generic response handling and unrelated tools (e.g., cascade_read_response, cascade_read). This extraneous text reduces conciseness and relevance.

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

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

The tool is simple with one parameter and no output schema. The description explains the return format (OperationResult), error cases, and essential behavior. However, the irrelevant boilerplate at the end slightly detracts from coherence, but the core information is adequate.

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

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

Schema coverage is 100%, but the description adds substantial meaning beyond the schema: it explains the name must exactly match an existing key, value is always a string (even for numbers/booleans), and Cascade parses it. The Args section mirrors and elaborates on the schema, providing clear constraints.

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

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

The description clearly states 'Update a single Cascade system preference,' specifying a precise verb and resource. It distinguishes from siblings by referencing cascade_read_preferences for reading and implying system-level scope, differentiating it from user-scoped tools.

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

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

Explicit 'Use when' and 'Don't use when' examples guide the agent on appropriate usage, including alternatives like cascade_read_preferences and clarifying that it is not for user-scoped preferences. This provides clear context for when to invoke this tool versus others.

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

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

Discloses that it 'replaces configuration wholesale' and explains propagation flags. Adds error handling details. Annotations (destructiveHint: false) are consistent; no contradictions.

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?

Well-structured with sections and bullet points, but includes an irrelevant block about bounded _cache metadata and cascade_read response, which bloat the description.

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

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

Covers all 4 params, return type (OperationResult), error handling, and examples. No output schema but description explains return values. Slightly verbose on unrelated content.

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

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

Schema coverage is 100%, baseline 3. Description adds significant detail: propagation logic, workflowSettings shape, optionality, and usage examples, elevating meaning beyond schema.

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

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

The description uses a specific verb (Update) and resource (workflow settings for a Cascade container). It distinguishes from siblings by explicitly naming cascade_read_workflow_settings and cascade_perform_workflow_transition.

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

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

Provides explicit when-to-use examples (e.g., 'Require workflow on /releases') and when-not-to-use with alternatives ('Don't use when... cascade_perform_workflow_transition'). Advises reading settings first.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds significant behavioral context: lists both unread/read, active/archived depending on server defaults, pagination details, error handling (authentication failed, permission denied). A minor deduction for including a somewhat tangential note about JSON structuredContent and cache metadata, which may confuse rather than clarify.

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 well-structured with clear sections (Args, Returns, Examples, Pagination, Error Handling) and front-loaded purpose. However, it includes a somewhat generic paragraph about JSON structuredContent and cascade_read that is not directly relevant to this tool, slightly reducing conciseness.

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

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

Despite no output schema, the description thoroughly documents the return format (including fields like total, count, offset, has_more, next_offset, messages array with subfields) and error responses. Pagination and error handling are fully explained, making it complete for a list tool with two optional parameters.

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

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

Schema coverage is 100% with good descriptions for limit and offset. The description adds value by explaining pagination usage (e.g., 'Use with limit + has_more to iterate') and providing default values and ranges beyond the schema. This extra context justifies a 4 rather than a baseline 3.

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

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

The description clearly states it lists in-Cascade mailbox messages for the authenticated user, with specific verb 'list' and resource 'messages'. It distinguishes from siblings by noting that message IDs can be used with cascade_mark_message or cascade_delete_message, and gives explicit examples of when not to use this tool (e.g., for asset subscribers use cascade_list_subscribers).

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

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

The description provides explicit guidance on when to use (e.g., 'What's in my Cascade inbox?') and when not to use (e.g., 'Don't use when: You want an asset's relationships or subscribers — use cascade_list_subscribers'). It also gives alternatives and a clear example for checking workflow messages.

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 indicate read-only, non-destructive, idempotent, and open world. The description adds useful context about return structure (identifiers only) and error handling scenarios, but no additional behavioral traits beyond 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?

Well-structured with sections (args, returns, examples, error handling) but overly verbose with generic boilerplate about responses and _cache metadata that is not specific to this tool. Could be trimmed.

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

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

Given no parameters, no output schema, and strong annotations, the description covers purpose, typical usage, return structure, and error handling. It is complete for an agent to use effectively.

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

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

No parameters exist; baseline is 4. The description correctly notes '(none)' args, so no added meaning needed beyond schema.

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

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

The description clearly states the tool lists all sites accessible with current credentials and returns identifiers. It distinguishes itself from sibling tools like cascade_read by specifying it only returns basic info, not full configuration.

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

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

Explicitly states when to use (first call to discover sites) and when not to (already know site name/id, need full config). Includes examples of natural language queries that map to 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 declare readOnlyHint=true, consistent with listing. Description adds directionality constraints, error handling cases, and response structure. No contradictions.

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?

Well-structured with sections and examples, but slightly verbose. Every sentence adds value, but could be slightly tighter. Front-loaded with purpose.

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

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

Despite no output schema, description provides full return structure and error scenarios. Covers all key behaviors for a complex 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 has one parameter with minimal description, but the tool description extensively documents identifier properties (id, path, type), including valid type strings and fallback behavior. Greatly enriches 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 explicitly states it lists relationships (assets referencing this one) and subscribers. It distinguishes two discovery questions and contrasts with sibling tools like cascade_list_messages and cascade_search. Clear verb+resource.

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

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

Provides explicit 'Use when' and 'Don't use when' examples, explains directionality, and names alternative tools (cascade_list_messages). Excellent guidance.

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

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

Annotations already declare idempotentHint=true, but the description reinforces this by explaining idempotency. Discloses error types like 'Message not found' and 'Permission denied'. However, includes an irrelevant paragraph about cascade_read_response and cascade_read that adds noise and reduces clarity.

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?

Most content is valuable, but the final paragraph about cascade_read_response and cascade_read is irrelevant to this tool and adds unnecessary length. The examples and error handling are well-structured but the extraneous section hurts conciseness.

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

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

Covers purpose, parameters, return format (OperationResult), error handling, and usage examples. Lacks an output schema but provides a structured return description. The irrelevant tail about cascade_read_response slightly detracts from completeness.

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

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

Schema has 100% description coverage, but the description adds critical context: identifier.id comes from cascade_list_messages, identifier.type must be 'message', and markType allowed values are explicitly listed. This goes beyond the schema's minimal descriptions.

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

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

Description clearly states the tool marks a Cascade inbox message as read/unread/archive/unarchive. It distinguishes from siblings like cascade_delete_message and cascade_list_messages by explicitly naming them in the 'Don't use when' section.

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

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

Provides explicit when-to-use examples (e.g., 'Mark a workflow notice as read') and when-not-to-use with alternative tool names. Covers both common use cases and 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 indicate the tool is not read-only, not destructive, not idempotent, and open world. The description adds value by explaining automatic reference updates and providing detailed error handling messages. However, it does not discuss reversibility or side effects beyond reference updates, and the description includes some redundant system-level notes about responses that might not apply solely to this tool.

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

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

The description is well-structured with sections (overview, args, returns, examples, error handling). It front-loads the core behavior. However, it is somewhat verbose, especially in the args section where it repeats schema details, and the system-level notes about structuredContent and oversized responses add noise but are likely required by the platform.

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 complexity of moving/renaming assets with optional workflow and reference updates, and no output schema, the description covers all essential information: return format, error handling, examples, and parameter interactions. It also refers to external documentation for complex subfields (workflowConfiguration), ensuring completeness for AI agent selection and invocation.

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

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

Schema coverage is 100%, and the description adds significant meaning beyond the schema. It explains the three operational modes (rename only, move only, both), details each parameter's subfields (e.g., identifier, moveParameters), and provides concrete examples showing how to structure calls for different use cases.

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

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

The description clearly states the tool moves or renames a Cascade asset, distinguishing it from sibling tools like cascade_copy (for duplication) and cascade_remove (for deletion). It uses a specific verb ('move or rename') and identifies the resource ('Cascade asset').

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

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

The description explicitly states when to use (move/rename) and when not to use ('Don't use when: You want to duplicate — use cascade_copy'). Examples with 'Use when' and 'Don't use when' provide clear context. It also details three scenarios (rename only, move only, both) and specifies that references are updated automatically.

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 indicate readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true. The description adds behavioral context: it executes a named action, may trigger publishing/deletion upon final step, stores comments in history, and provides error scenarios. No contradiction with annotations.

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

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

The description is well-organized with labeled sections (Args, Returns, Examples, Error Handling). It is somewhat lengthy but each sentence adds value. Could be slightly more concise but remains clear and focused.

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

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

Given no output schema, the description thoroughly explains the return format and error messages. It covers prerequisites, side effects, and error handling, making it complete for a workflow transition tool with good annotations.

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 describes each parameter briefly. The description adds meaningful context: workflowId comes from a prior call, actionIdentifier from workflow.actions[].identifier, and transitionComment is recommended for reviewers. This enhances schema coverage of 100%.

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

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

The description clearly states it advances an in-flight workflow to its next step (approve, reject, publish, etc.), with a specific verb and resource. It distinguishes itself from siblings by explicitly referencing the prerequisite tool cascade_read_workflow_information and by contrasting with read-only tools.

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

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

The description provides explicit when-to-use and when-not-to-use guidance, including examples (approve, reject) and negative conditions ('Don't use when: You don't yet know which actions are valid...', 'Don't use when: No workflow exists'). It also explains prerequisite calls.

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

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

The description adds significant behavioral context beyond annotations: it replaces existing generated rules, preserves unrelated rules, and details the return report and response handling. No contradiction with annotations.

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

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

The description is well-structured, front-loaded with purpose, then details mechanics, return format, and edge cases. Every sentence adds value without redundancy.

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

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

With no output schema, the description fully explains the return value and handles edge cases like oversized responses. It covers all necessary aspects for a zero-parameter 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?

There are zero parameters, so baseline is 4. The description does not need to explain parameters.

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

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

The description clearly states the tool persists blocked-call rules to prevent removal of Cascade sites and root folders. It uses specific verbs and resources, distinguishing it from sibling tools like cascade_remove or cascade_tool_blocks.

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

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

The description implies usage for protecting sites from removal by describing the blocking mechanism. However, it lacks explicit guidance on when not to use or direct comparisons with alternatives like cascade_tool_blocks.

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 indicate destructiveHint=true. The description adds valuable context: async behavior, production impact, error handling. However, it includes an irrelevant paragraph about cascade_read responses that may confuse agents, slightly reducing transparency.

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

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

Well-organized with clear sections and examples, but includes an off-topic paragraph about cascade_read responses that adds verbosity without contributing to this tool's description. Could be more concise.

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

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

Covers all necessary aspects: operation, parameters, usage, error handling, return shape (OperationResult), and examples. No output schema exists, but the description adequately compensates. Extremely complete for a tool of this complexity.

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

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

Schema coverage is 100%, and the description goes far beyond by detailing identifier and publishInformation subfields, providing examples, and listing error conditions. This adds substantial meaning 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 uses a specific verb (publish/unpublish) and resource (Cascade asset) and clearly distinguishes the dual operation. It explicitly contrasts with the sibling tool cascade_remove, which is used for deletion.

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

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

Provides explicit when-to-use scenarios (publish page, unpublish, schedule) and when-not-to-use (delete, not committed edit). It names the alternative cascade_remove, making selection 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?

Discloses that preview mode is not audit-complete, raw mode is expensive, and lists possible error responses. Annotations already indicate read-only and idempotent, and the description adds context about behavior and limitations.

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?

Well-organized into sections with clear headings. While lengthy, every section adds necessary detail. Slightly verbose but still concise for the complexity.

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

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

Given no output schema, the description fully specifies return shapes for both modes and error handling. All necessary context for correct invocation is provided.

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

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

Schema coverage is 100% with descriptions; the description adds examples, clarifies id priority over path, and explains read_mode options, providing additional value beyond the schema.

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

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

The description clearly states it reads an asset from Cascade CMS by identifier. It distinguishes preview vs raw mode and references sibling tools for follow-up inspection, making the purpose 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?

Explicit 'Use when' and 'Don't use when' examples guide the agent, including naming alternative tools like cascade_edit for modifications and cascade_read_access_rights for access checks.

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

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

Annotations already mark the tool as read-only and idempotent. The description adds useful behavioral context (e.g., error handling, response format includes structuredContent, and oversized responses return _cache metadata). However, it includes a tangential mention of cascade_read and read_mode that may be slightly confusing.

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 well-structured with sections but contains redundant or extraneous details (e.g., 'Responses are JSON text...' paragraph seems generic and not specific to this tool). It could be more concise without losing clarity.

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

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

Despite having only one parameter and no output schema, the description thoroughly explains the input structure, return shape (including ACL entries and allLevel), error messages, and usage examples, making it fully self-contained.

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

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

Schema coverage is 100% with a brief description. The description significantly adds value by detailing the identifier's nested structure (id, path, type) and providing concrete examples, greatly aiding correct parameter usage.

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

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

The description clearly states the tool reads access rights for a Cascade asset, details the ACL and permission levels, and distinguishes itself from siblings like cascade_edit_access_rights and cascade_read_workflow_settings.

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

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

The description explicitly provides when-to-use (e.g., 'Who has edit access to /about?') and when-not-to-use (e.g., for changing permissions, use cascade_edit_access_rights; for workflow settings, use cascade_read_workflow_settings). It also includes error handling guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds significant behavioral context: results are always newest-first, all filter fields are optional, default limit is 50, max 500, pagination via has_more/next_offset, error handling for invalid dates, audit types, and permission denied. This goes well beyond the annotations without contradiction.

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 structured with clear sections (Args, Returns, Examples, Pagination, Error Handling) and front-loaded with purpose. It is verbose but every section adds value. Minor repetition (e.g., error handling mentions cascade_read_response boilerplate) prevents a 5, but it remains well-organized and informative.

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

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

Despite no output schema, the description provides a sample return structure (success, total, count, offset, has_more, next_offset, audits) with field descriptions. It covers pagination loops, error scenarios, and example queries. For a read operation with filter complexity, this is comprehensive and leaves little ambiguity.

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

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

Schema coverage is 100% with detailed descriptions for each parameter. The description adds value by explaining the meaning of auditParameters fields more contextually (e.g., allowed values for auditType, optional nature) and clarifying pagination behavior. While the schema covers syntax, the description enhances semantic understanding.

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

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

The description states 'Read Cascade audit log entries matching the specified filters.' It clearly identifies the verb 'Read' and resource 'audit log entries.' The tool name 'cascade_read_audits' reinforces this. The description further distinguishes from siblings like 'cascade_read' (current state) and 'cascade_list_messages' (user inbox) through explicit 'Don't use when' notes.

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

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

The description provides explicit 'Use when' examples (e.g., 'Who edited /about today?') and 'Don't use when' alternatives ('use cascade_read', 'use cascade_list_messages'). It also advises on when to apply date range filters to avoid large volumes, giving clear contextual guidance.

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

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

Annotations already declare readOnlyHint and idempotentHint, but description adds credential requirements, error handling details, and the return format. No contradiction. The extra paragraph on structured content seems irrelevant but does not mislead.

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

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

Front-loaded with purpose and return format, but includes a somewhat irrelevant boilerplate paragraph about read_mode and structured content that appears copied from another tool. This adds unnecessary length.

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

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

Despite the extraneous boilerplate, the description covers behavior, error handling, usage examples, and differentiation from sibling tools. No output schema exists, but the return format is described. Mostly complete for a zero-parameter 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?

No parameters exist, and the description explicitly states 'Args: (none)' with example usage showing empty input. Schema coverage is 100%, so no additional parameter info needed. Baseline 4 applies.

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

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

The description clearly states 'Read all Cascade system preferences' and elaborates with examples of preference types. It distinguishes from siblings like cascade_edit_preference by advising to check current values before editing, and from user-level tools by noting preferences are system-wide.

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 stated when to use (to inspect or check before editing) and when not to use (for user-level settings). It also requires system-admin-level credentials, providing clear prerequisites.

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

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

Annotations already indicate read-only, idempotent, non-destructive. The description adds valuable behavioral context: caching mechanism (last 50 oversize responses), LRU eviction, error strings, and that slice_text contains the response. It does not contradict 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?

Well-organized with sections: summary, parameter details, return format, examples, error handling. No wasted sentences; every part adds value. Concise for the information provided.

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

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

Given the tool's complexity (caching, slicing, error states) and lack of output schema, the description fully equips an agent to use it correctly: parameter semantics, return structure, iteration pattern, and eviction handling are all covered.

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

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

Schema coverage is 100%, so baseline is 3. The description adds context: handle source (structuredContent._cache.handle), offset usage (use next_offset), length cap (25000), and default values. This goes beyond schema descriptions.

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

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

The description clearly states the tool retrieves a slice of a cached MCP response by handle, with specific context about when it's needed (oversize responses). This distinguishes it from all sibling cascade tools, which are for asset operations or other functions.

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

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

Explicitly explains when to use (response exceeds budget, handle returned) and when not to use (response fit under limit, handle evicted). Provides examples and error handling guidance, including re-running the originating tool if handle is missing.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and no destructive actions. Description adds behavioral context: what the tool returns (workflow state, actions, history), error conditions ('Asset not found', 'No workflow in progress', 'Permission denied'), and handling of oversized responses with _cache metadata. No contradiction with 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?

Well-structured with clear sections (Args, Returns, Examples, Error Handling). Every sentence serves a purpose; no fluff. Despite length, it is efficiently organized for an agent to parse quickly.

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?

Completely covers all necessary context: purpose, usage guidance, parameter details, return format (OperationResult with workflow object), error handling, and examples. No gaps; an agent can fully understand how and when to use this tool.

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

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

Schema coverage is 100% (parameter identifier documented), so baseline is 3. Description adds significant meaning: explains identifier can use id or path object with siteId/siteName, requires type, and provides examples with concrete shapes. This far exceeds the schema's minimal description.

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

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

Clearly states it reads workflow information for an asset, with specific verb 'read' and resource 'workflow information', and distinguishes from sibling 'cascade_read_workflow_settings' by explicitly stating 'Don't use when: You want workflow policy — use cascade_read_workflow_settings'.

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

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

Provides explicit when-to-use examples ('What step is /about/team in?') and when-not-to-use scenarios ('Don't use when: No workflow is in flight' and 'Don't use when: You want workflow policy'), with alternative tool named.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds context: error messages ('Asset not found', 'Not a container', 'Permission denied'), response format (JSON text, structuredContent authority, oversized responses with _cache metadata), and that workflow settings apply only to containers. This supplements the annotations effectively.

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?

Well-organized into sections: purpose, args, returns, examples, don't use, error handling. Every section adds value. A few boilerplate sentences about response handling are slightly lengthy but not detrimental. Overall efficient for the tool's complexity.

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

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

Given the tool has one parameter and no output schema, the description is highly comprehensive. It details the return structure, error cases, usage scenarios, and mentions inheritance behavior. It also references sibling tools, making the context complete for an AI agent.

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

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

Schema coverage is 100% for the single identifier parameter. The description goes beyond: explains the param is a container (folder/site), provides structure for id and path (with siteId or siteName), and gives examples. This adds significant meaning not present in the schema alone.

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

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

The description clearly states 'Read workflow settings for a Cascade container (folder or site).' It specifies the verb (read) and resource (workflow settings of a container). It distinguishes from sibling tools like cascade_read_workflow_information and cascade_edit_workflow_settings by clarifying scope and usage.

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

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

Provides explicit 'Use when' and 'Don't use when' sections with concrete examples, such as 'Does /about require workflow?' and mentions alternatives like cascade_read_workflow_information for in-flight workflows. It also warns against querying non-containers.

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 indicate destructiveHint=true; description adds value by detailing default recycle-bin behavior, hard-delete/unpublish options, rejected operations (site removal), workflow requirements, and a warning label. No contradiction with 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?

Well-structured with Args, Returns, Examples, and Error Handling sections. Front-loaded with key purpose. Slightly lengthy due to examples and error details, but remains efficient and organized for a complex 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?

Covers all inputs with examples and error handling, explains return format, and references relevant sibling behavior (cascade_read_response). Despite no output schema, description provides complete guidance for safe usage.

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

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

Schema coverage is 100% with param descriptions; description further enriches by explaining default behavior (recycle bin), specifying shape of identifier, detailing deleteParameters (doWorkflow, unpublish), and workflowConfiguration with examples. Adds significant meaning beyond schema.

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

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

The description clearly states 'Delete an asset from Cascade CMS' with specific verb and resource, and explicitly distinguishes from siblings like cascade_move and cascade_publish_unpublish in the 'Don't use when' examples.

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

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

Provides explicit when-to-use scenarios (delete, unpublish then delete) and when-not-to-use with alternatives (cascade_move, cascade_publish_unpublish). Also includes error handling for common failure modes, guiding correct invocation.

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

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

Annotations indicate readOnly, non-destructive, idempotent, open-world. The description adds pagination behavior (client-side, has_more, next_offset), error handling details, and notes on response format (JSON text, structuredContent, oversized responses). This adds significant context beyond annotations.

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

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

The description is well-structured with sections (Args, Returns, Examples, Pagination, Error Handling). It is slightly lengthy but each part adds value; front-loaded purpose sentence. Loses a point for minor redundancy (some schema descriptions also present).

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

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

Given the tool's complexity (multiple parameters, pagination, error cases), the description is thorough: covers pagination loop, error messages, examples, and return format. No output schema, but the description provides a clear return shape.

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

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

Schema coverage is 100%, but the description provides rich parameter details: allowed values for searchFields, default behaviors for searchFields and searchTypes, and constraints (non-empty searchTerms). Examples further clarify parameter usage.

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

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

The description clearly states the tool searches for assets across Cascade CMS by search terms, field subset, and asset type filter. It distinguishes itself from siblings like cascade_read (direct access by id/path) and cascade_read_audits (audit events), providing precise verb+resource+scope.

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

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

The description includes explicit 'Use when' and 'Don't use when' examples, guiding the agent to use this tool for keyword searches and avoid it when the id/path is known (use cascade_read) or for audit events (use cascade_read_audits). It also explains scoping to a single site or all sites.

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 and idempotent. Description adds return format and example, plus some generic response handling notes. No contradictions.

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

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

Front-loaded with purpose. Some boilerplate about responses and cascade_read is unnecessary but not harmful. Overall concise.

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 parameterless tool with full annotations, the description covers purpose, return shape, and example. No gaps.

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

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

No parameters, so schema coverage is 100%. Description explicitly states 'Args: (none)', which is clear. Baseline for 0 params is 4.

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?

Purpose is explicit: 'Read this MCP server's name and version'. Verb and resource are specific, and the tool is clearly distinct from sibling cascade tools.

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

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

States when to use: 'when you need to confirm which cascade-cms-mcp-server version is running'. No alternatives mentioned, but for a version check this is sufficient.

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

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

Discloses that the operation is long-running and asynchronous, requiring polling via cascade_list_sites. Lists specific error messages (e.g., 'Source site not found'). Annotations (readOnlyHint=false, destructiveHint=false) are consistent with the description's disclosure of a non-idempotent mutation.

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?

Well-structured with sections (Args, Returns, Examples, Error Handling), but includes an irrelevant concluding paragraph about cascade_read and cascade_read_response that appears to be a copy-paste error, adding unnecessary verbosity and potential confusion.

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

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

Covers the full context: purpose, parameter relationships, asynchronous behavior, polling recommendation, return structure (success/error), and error cases. No output schema is needed because the description adequately explains the response.

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

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

Schema coverage is 100%, but the description adds critical semantics: the mutual exclusivity and precedence of originalSiteId over originalSiteName, and the explicit requirement for newSiteName (not captured in the required array).

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

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

The description clearly states 'Copy an entire site to a new site with a new name', a specific verb-resource pair. It explicitly distinguishes itself from the sibling tool cascade_copy by stating 'Don't use when: You want to copy a single asset — use cascade_copy'.

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

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

Provides explicit usage examples ('Use when: ...') and contraindications ('Don't use when: ...'). It explains when to prefer originalSiteId over originalSiteName and warns against using for single-asset copies or when the new site name already exists.

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 indicate destructive and non-read-only behavior. The description adds context: writes only local repository, blocked-call check runs before other tools, and explains response format. No contradiction with annotations.

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

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

The description is well-structured with clear sections and bullet points. It is slightly verbose but every sentence adds value. Could be trimmed slightly but remains efficient.

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

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

Despite lacking an output schema, the description sufficiently explains response behavior (JSON text, structuredContent, cache metadata). It also clarifies the tool's role in the broader toolset, making it complete for an agent.

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

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

Schema coverage is 100% but parameter descriptions are minimal. The description adds significant meaning: action can be 'list' or 'add', and rule requires specific fields (tools, url, type+id/path). This compensates well.

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

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

The description clearly states the tool manages blocked Cascade tool-call rules with explicit actions (list, add). It distinguishes itself from siblings by focusing on guardrail persistence, which no other sibling tool addresses.

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

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

The description gives explicit when-to-use guidance ('persist a guardrail') and details required fields for rules. It also advises user approval for the add action, but does not explicitly state 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.