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

Annotations supply idempotentHint=true and destructiveHint=false, so the description's added value is the conflict behavior ('Returns conflict if another user holds the lock'), a genuinely useful failure mode. It omits lock lifetime/expiry and whether an unattended lock blocks other users indefinitely.

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

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

Two compact sentences with zero filler; the action and scope come first and the error semantics second. Nothing is wasted or buried.

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

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

For a one-parameter lock tool with no output schema, the key missing context is lifecycle: how long the lock persists, whether it auto-expires, and that release_content_lock must eventually be called. Annotations cover idempotency, but the operational contract is only partially conveyed.

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

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

Only one parameter, fully documented in the schema at 100% coverage ('Content item ID,required'). The description adds no syntax or format detail beyond what the schema already states, so baseline 3 applies.

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

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

States a specific verb (acquire) and resource (advisory lock on a content item), scoped to the current API user. It is clearly distinguishable from get_content_lock and release_content_lock by the 'acquire' semantics, though no sibling is named explicitly.

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

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

There is no statement of when to acquire a lock versus using get_content_lock to inspect one, and no mention that release_content_lock (or force_unlock_content) is the counterpart action. The locking lifecycle an agent must follow is left entirely to inference.

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

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

The annotations only declare destructiveHint=false, so the description carries most of the burden and does disclose the consequential side effect: content is automatically published once all required approvals are collected. That is exactly the kind of cascading effect an agent needs before calling a mutation. It still omits whether approval is reversible and what permissions are required.

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

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

Two short sentences, front-loaded with the action, with no redundant restatement of the title or resource name.

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 small two-parameter mutation with no output schema, the description covers the action and its main consequence, which is minimally sufficient. It leaves out authorization requirements, whether the approval can be withdrawn later, and what the response contains, which matters for an agent operating in an approval workflow.

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

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

Schema description coverage is 100% and both parameters (id, comment) are documented in the schema, so the baseline of 3 applies. The description adds no meaning about the id format or what the comment is used for beyond the schema.

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

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

States a specific verb and resource (approve an approval request) that is unambiguous against the nearest siblings reject_request and cancel_approval_request, and the second sentence adds the outcome. It stops short of naming the analogous sibling operations, so an agent still infers the routing from the verb alone.

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

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

There is no guidance on when to approve versus reject or cancel, and no prerequisites such as the caller needing to be a designated approver or the request needing to be in a pending state. The agent must infer all preconditions from the workflow 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 declare idempotentHint=true and destructiveHint=false. Description adds critical behavioral context: the fork and pages are 'preserved' (explaining destructive=false), becomes 'read-only' (state change), and 'Requires admin role' (authorization barrier not in annotations). Adds significant value beyond structured hints.

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

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

Three tightly constructed sentences: 1) Action + sibling distinction, 2) Preservation semantics + state change, 3) Authorization requirement. Zero redundancy; every word earns its place. Excellent information density.

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

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

For a single-parameter state-change tool with no output schema, the description adequately covers the operation outcome (read-only preservation), authorization boundary, and sibling distinction. Completeness is appropriate for the tool's complexity; no critical 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 has 100% description coverage ('Fork workspace ID to archive,required'), so baseline is 3. Description does not add parameter semantics, constraints, or examples beyond what the schema provides, but none is needed given complete schema coverage.

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

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

Description uses specific verb 'Archive' with resource 'fork', states the exact outcome (becomes read-only), and explicitly distinguishes from sibling merge_fork with 'without merging it'. Also distinguishes from delete_fork by stating data is preserved.

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 references the alternative action (merging) via 'without merging it', establishing the choice point. States prerequisite 'Requires admin role'. Could be improved by explicitly stating when to choose archive vs delete, but clearly signals this is a preservation alternative to merging.

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, destructiveHint=false, and openWorldHint=false. The description adds meaningful context beyond them: it is metadata-only, pages do not re-render, the target population is narrowly defined, and dry_run can preview the count. It does not discuss permissions or reversibility, but the annotation set already covers the safety profile.

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 four sentences, front-loaded with the core operation and scoped condition. Each sentence adds distinct information (target population, effect, metadata-only behavior, dry-run guidance) with no redundancy.

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

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

No output schema exists, but the description explains the mutation, its target set, its non-rendering nature, and the dry-run preview. It is nearly complete for a single-parameter maintenance tool; only permissions and exact return format are unstated, and the annotations largely cover operational safety.

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 100% schema coverage, the schema already defines dry_run as counting pages that would change. The description adds sequencing value by instructing the agent to use dry_run first, which is meaningful guidance beyond the schema's static 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?

States a specific action (give published pages a published date), the exact target population (published pages lacking a published date, created before v7.3.2), and the effect (date equals creation date). It is clearly distinguishable from generic update tools like update_content or bulk_update_content.

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

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

Specifies the condition for using the tool (pages without published dates, pre-v7.3.2) and adds an operational guideline: use dry_run first to see the count. It does not name an alternative tool or state when not to use it, keeping it just short of a 5.

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

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

With annotations only declaring openWorldHint=false and destructiveHint=false, the description carries real behavioral weight: best-effort partial-failure semantics ('the rest continue'), the underlying InsertMany path, parallel HTML generation capped at 10 concurrent, and the upsert override for duplicates. This is exactly the operational detail annotations cannot express.

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 tight sentences, front-loaded with the verb and limit, then failure behavior, then the upsert escape hatch, then the return shape. No sentence is redundant and the length is justified by the tool's batch 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?

There is no output schema, so the description correctly compensates by specifying the return payload (attempted/succeeded/failed counts plus per-item id, full_path, success, error). Combined with failure and concurrency semantics, an agent has everything needed to call and interpret this tool.

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

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

Schema description coverage is 100%, so the schema already documents items, upsert, and version_comment, and the description's restatement of upsert adds only the 'instead of failing on duplicates' framing. The 100-item cap and per-item field semantics are otherwise left to the schema, so baseline 3 is appropriate.

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

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

The first sentence gives a specific verb (Create), resource (content items), and a hard scope bound (up to 100 in a single call), which cleanly separates it from create_content (single) and bulk_update_content (existing items). An agent can distinguish it from all siblings without opening the schema.

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

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

It clearly states the condition that changes behavior: set upsert: true to overwrite existing pages at the same path instead of failing, and it explains that a single failure does not abort the rest. It stops short of naming when to prefer create_content or bulk_update_content over this tool, so it is clear context rather than full when/when-not routing.

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

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

Annotations only supply destructiveHint=true and openWorldHint=false, so the description carries real added weight: it reveals that clear blanks a field, that dry_run avoids saving, and that fork copies surface in a 'skipped' array with {id, reason}. It stops short of stating permission requirements or rollback/versioning behavior, though the version_comment param hints at versioning.

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 purpose statement, tight bulleted operation list, then scope/dry-run guidance, then a concrete example. Every block earns its place and a reader can skim to the relevant part.

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

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

For an 11-param destructive bulk tool with no output schema, the description covers operations, scoping, dry-run safety, and the skipped-result shape. It does not address permissions, locking (siblings include acquire_content_lock), or rate considerations, leaving a small gap.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds genuine meaning by defining what each operation value does (e.g., wrap consumes before/after, append adds text after the existing value) — semantics the schema enum does not enumerate — plus the skipped-return behavior tied to content_ids.

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

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

The description states a precise verb and resource ('Apply a single field operation to all matching content pages in one call') and the enumerated operation set (clear/set/prepend/append/wrap) clearly distinguishes it from sibling bulk tools like bulk_update_content and scoped_search_replace_execute.

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

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

It gives clear operational context: scope filters select the affected pages, dry_run previews changes without saving, and only live pages mutate. The example call shows a realistic invocation, but no explicit when-not-to-use guidance or named alternatives are provided.

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 establish destructiveHint=true (mutation), while description adds merge semantics ('only the fields you want to change'), explains dry_run validation behavior, distinguishes clear_fields from merge updates, and details return structure ('total attempted, succeeded, failed counts') compensating for lack of output schema.

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

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

Front-loaded with core purpose and sibling distinction; structured logically from operation definition → semantics → return values → workflow tip → optimization. No wasted words; each sentence advances understanding of how to invoke correctly.

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

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

Despite lacking output_schema, description fully specifies return values ('total attempted, succeeded, failed counts, and per-item success/error details'). Covers batch limits (100 max, 50 recommended), destructive behavior (annotations + merge semantics), and workflow integration for a complex nested update operation.

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

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

With 100% schema coverage, description adds crucial semantic context: explains merge semantics on data field vs explicit clearing via clear_fields, clarifies dry_run validates 'IDs exist without committing', and contextualizes version_comment as applying to 'all updates' in the batch.

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 opens with specific verb ('Update') and resource ('content items'), explicitly quantifies scope ('up to 100'), and immediately distinguishes from sibling tool 'update_content' by stating 'Use instead of calling update_content in a loop'.

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 identifies when to use this tool versus alternative ('Use instead of calling update_content in a loop'), provides workflow prerequisites ('Tip: call list_content...first'), and includes performance guidance ('Recommended batch size: up to 50 per call').

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 destructiveHint annotation already signals that this is a destructive operation. The description adds the useful constraint that only pending requests can be canceled, but it does not explain reversibility, permissions, or what exactly happens to the request after cancellation.

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

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

The description is a single front-loaded sentence with no filler. For a simple one-parameter cancellation tool, this is appropriately sized and every word earns its place.

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

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

Given the simple parameter set and the destructiveHint annotation, the description is minimally sufficient to invoke the tool. However, it omits how this tool relates to sibling approval operations such as reject_request and does not describe post-cancellation behavior or return values.

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

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

Schema description coverage is 100%, so the single id parameter is already documented in the schema. The description adds no additional parameter meaning, syntax, or format details beyond what the schema provides, making 3 the appropriate baseline.

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

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

The description uses a specific verb and resource: 'Cancel a pending approval request.' It clearly distinguishes cancellation from reading or listing, but it does not differentiate from siblings like reject_request or approve_request, which would require explicit comparison.

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 phrase 'pending approval request' implies the tool should only be used when the request is still pending, which is a basic usage condition. However, it gives no explicit guidance on when to choose cancel versus reject_request or other approval-related 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 already declare destructiveHint=true and openWorldHint=false, so safety is covered structurally. The description adds the meaningful detail that only a *running* job is a valid target, but says nothing about reversibility, what happens to already-imported content, or auth/permission requirements.

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

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

A single front-loaded sentence with no filler or redundancy. It is tersely efficient, though arguably it could spend one more clause on the caller's obligation without becoming bloated.

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

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

For a one-parameter tool with destructive annotations and no output schema, the description covers the essentials. It is adequate but leaves gaps on job-state preconditions and what happens to partial import state, which for a destructive operation would be worth a sentence.

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

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

Schema description coverage is 100% and the single 'id' parameter is already documented as 'Import job ID to cancel'. The description adds nothing beyond the schema, so the baseline 3 for a fully-covered schema applies.

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

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

States a specific verb ('Cancel') and resource ('import job') with the qualifier 'running' that scopes the operation. The agent can distinguish it from cancel_approval_request and cancel_scheduled_publish by resource, though the description never explicitly contrasts with those siblings.

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

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

No when-to-use guidance, no prerequisites (e.g. job must be running), and no mention of alternatives like cancel_approval_request. The 'running' qualifier faintly implies a precondition but stops short of stating it as 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 and destructiveHint=false, so the safety profile is covered and the description's only added detail is that the specific field being cleared is the scheduled publish time. It does not say what happens if no schedule exists, whether the content's published/draft state changes, or what permissions are required.

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

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

A single sentence with zero filler, front-loading the verb and the target of the operation. It is arguably too terse for the behavioral gaps it leaves, but as a sizing judgment it is efficient and well-structured.

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

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

For a simple one-parameter mutation whose idempotency and safety are covered by annotations, this is mostly adequate. Gaps remain around the resulting content state after cancellation and whether a missing schedule is an error or a no-op.

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

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

There is a single required parameter with 100% schema description coverage, so the schema fully documents content_id and the description adds nothing beyond it. Baseline 3 is appropriate when the schema carries the parameter semantics.

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

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

States a specific verb (clear) and object (the scheduled publish time) scoped to a content item, which is easy to distinguish from its inverse sibling schedule_content_publish. It does not explicitly name that sibling or clarify the relationship, but the action itself is unambiguous.

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

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

There is no explicit guidance on when to use this tool versus alternatives such as schedule_content_publish, unpublish_content, or delete_content. The use case is only inferable from the tool name and purpose statement.

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

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

Annotations supply only destructiveHint=false and a title, so the description carries most of the behavioral burden for a mutation tool. It says nothing about whether existing workflows are affected, conditional requirements (e.g. trigger_value needed only for folder_path/template_id), permission needs, or what happens on success. The two sentences merely restate values already present in the schema.

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

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

Two short sentences, front-loaded with the action before the field enumerations. It is compact and easy to scan, though the second sentence is largely redundant with schema-documented enum values.

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

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

There is no output schema, six parameters at full schema coverage, and only a minimal annotation set. The description is adequate for identifying the tool but leaves real gaps for a create-mutation call: conditional parameter requirements (trigger_value), approver ordering semantics under each mode, and any post-creation behavior.

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

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

Schema description coverage is 100%, so the baseline is 3 and the schema already documents name, mode, trigger, approvers, description, and trigger_value. The description repeats the trigger and mode value sets but adds no conditional logic, e.g. which trigger types require trigger_value or how approver 'order' interacts with sequential vs concurrent mode.

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

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

States a specific verb and resource ("Create a new approval workflow"), making it distinguishable from update/get/delete/list approval-workflow siblings. It stops short of explicitly contrasting with destructive-sounding or overlapping siblings like submit_for_approval, but the intent is unambiguous.

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

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

The description never says when to use this tool versus update_approval_workflow, list_approval_workflows, or submit_for_approval, nor does it mention prerequisites such as required permissions. The trigger-type and mode lists are enumerations of field values, not usage 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 indicate this is non-destructive (destructiveHint: false) and closed-world (openWorldHint: false). The description adds value by explaining what collections do behaviorally ('display grouped content with custom templates'), but omits other behavioral details like error conditions (e.g., slug uniqueness constraints), authentication requirements, or what the tool returns.

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 efficiently structured with two sentences: the first states the action, the second provides behavioral context. No words are wasted, and the information is front-loaded appropriately.

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

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

Given 9 parameters and no output schema, the description adequately covers the basic purpose but leaves significant gaps. It lacks information about the created resource's structure, error scenarios (e.g., duplicate slug handling), or how this relates to sibling operations like update_collection or list_collections.

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 100% schema description coverage, the schema carries the full documentation burden for all 9 parameters. The description references 'custom templates' which loosely maps to item_template and page_template parameters, but adds no semantic details beyond the schema such as valid slug formats, category filtering logic, or the relationship between sort_field and sort_order.

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

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

The description clearly states the action ('Create') and resource ('content collection'), and adds distinguishing context that collections 'display grouped content with custom templates.' However, it does not explicitly differentiate from siblings like create_content or create_folder, leaving ambiguity about when to use collections versus individual content items or folders.

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

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

The description provides no guidance on when to use this tool versus alternatives (e.g., create_folder for organization, create_content for individual items) or prerequisites needed before invocation. There are no explicit when/when-not conditions.

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

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

Annotations are thin (only destructiveHint=false), so the description carries most of the disclosure burden. It usefully adds the required permission scope, but says nothing about whether mentions trigger notifications, whether comments are moderated, or what side effects posting has.

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

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

Two short sentences with zero filler, and the core action is front-loaded before the permission caveat. Every sentence earns its place.

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

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

For a simple 3-parameter creation tool with full schema coverage, the description covers the action and the permission gate. It is adequate but incomplete: with no output schema, an agent gets no signal about the return value (e.g., the created comment ID) or the behavior of mentions.

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% (text, mentions, content_id all documented in the schema), so the baseline of 3 applies. The description adds no syntax, ID format, or semantics for the mentions array or content_id beyond what the schema already states.

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

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

The description states a specific verb and resource ('Post a discussion comment on a content item'), making it clearly distinguishable from list_comments and delete_comment by the create action. It stops short of explicitly differentiating itself from sibling comment tools, but the purpose is unambiguous.

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

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

It discloses a prerequisite ('Requires discussion.post permission'), which tells the agent the operation may fail without that scope. However, it gives no when-to-use framing, no exclusions, and never points to alternatives like list_comments or delete_comment, so usage context is only implied.

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

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

Annotations only declare openWorldHint=false and destructiveHint=false; the description adds substantial behavioral context beyond them, including publish-time Markdown conversion, wikilink auto-updating on path changes, snippet inclusion, hashtag-based tagging, and {{.lc_toc}} injection. It omits permission/auth requirements and side effects like index/feed regeneration, so it is strong but not complete.

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

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

Front-loaded with the core action and required inputs, then a numbered workflow, then flag guidance. The bulleted markup feature list is longer than strictly necessary for tool selection, but each item describes how the data parameter is interpreted, so it is largely load-bearing.

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 20-parameter create tool with full schema coverage and no output schema, the description covers the required flow, layout flags, and content-data conventions. It is silent on several optional params (hold, upsert, noindex, og_image, folder_path) and on duplicate-slug failure behavior, but the schema carries those.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it explains that data must match template field names (discoverable via list_templates), that use_header/use_footer/use_theme apply the site layout, that version_comment should always be set for readable history, and that published=true overlaps with publish_content.

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

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

States a specific verb and resource ('Create a new content item') and immediately names the required inputs, so it is clearly separable from create_template, create_collection, and create_snippet. It does not explicitly distinguish itself from single-item vs. bulk creation (bulk_create_content) or import paths, which keeps it below a 5.

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 an explicit three-step workflow (list_templates -> create -> publish_content) and states the alternative condition for combining steps with published=true. It does not say when NOT to use this tool (e.g., for many items use bulk_create_content, or for edits use update_content), so guidance is clear but not exhaustive.

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

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

Adds valuable context that folders create URL path segments (behavioral effect beyond creation), which complements the non-destructive annotation. However, omits error conditions, return value structure, and side effects like validation rules.

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

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

Two sentences with zero waste. Front-loaded with the core action, followed by functional context. Every word earns its place.

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

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

Adequate for a simple 3-parameter creation tool with complete schema coverage and safety annotations. Covers the 'what' and 'why' (organization/URLs) but lacks guidance on hierarchical usage patterns and return values expected from the server.

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 100% schema description coverage, baseline is 3. The description reinforces the 'slug' parameter's purpose via 'URL path segments' but does not add syntax details, validation rules, or explicit notes about parent_id being optional for root folders.

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

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

States specific verb 'Create' and resource 'content folder'. The mention of 'URL path segments' adds distinguishing context from sibling tools like create_collection or create_content, though it lacks explicit contrast with those alternatives.

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

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

No guidance on when to use folders vs. collections or content items, nor mention of prerequisites like unique slug requirements or valid parent_id constraints. Purely definitional description.

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-destructive; description adds valuable behavioral context including isolation guarantees ('without affecting the public site'), return value disclosure ('Returns the fork ID needed for subsequent fork operations'), and workflow sequencing. Could mention auth requirements or side effects for a 5.

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

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

Four distinct segments: one-line summary, concept explanation, numbered workflow (4 steps), and return value note. Every sentence earns its place with zero redundancy. Clear front-loading with the essential action stated immediately.

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?

Excellent completeness given no output schema exists: description explicitly states the return value (fork ID). Covers the full lifecycle context (creation through merge), explains relationship to live site, and provides sufficient detail for a workspace creation tool with 100% schema coverage.

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% (both 'name' and 'description' parameters fully documented in schema). Description references 'named fork workspace' which aligns with the name parameter, but adds no syntax, format, or example details beyond what the schema already provides. Baseline 3 is appropriate.

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

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

Opens with specific verb+resource: 'Create a new named fork workspace for staging content changes.' Explains what a fork is (isolated workspace) and distinguishes from siblings by explicitly positioning it as step 1 in a 4-step workflow distinct from fork_page, update_content, and merge_fork.

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 typical workflow with numbered steps showing exactly when to use this tool (step 1: create workspace) versus alternatives (step 2: fork_page, step 3: update_content, step 4: merge_fork). Also clarifies admin restriction applies to merge step, helping users understand this tool's 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 declare destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds that the source automatically pulls feed content, hinting at ongoing/scheduled behavior, but says nothing about permissions or the effect of the schedule/auto_publish flags. With annotations doing the heavy lifting, a 3 is appropriate.

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

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

A single front-loaded sentence with zero waste; the verb and resource lead and the clarifying clause follows immediately. Nothing extraneous and no padding.

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

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

For a 7-parameter creation tool the description is thin: the schema documents every field and annotations cover safety, but there is no usage context, prerequisite info, or mention of what happens after creation. Adequate but with visible gaps an agent must infer.

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

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

Schema description coverage is 100%, so all seven parameters including defaults (active, schedule, auto_publish) are already documented in the schema. The description adds no syntax or behavioral meaning beyond what the structured fields provide, so the baseline of 3 applies.

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

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

The description states a specific verb and resource ('Create a new RSS/Atom import source') and clarifies the effect ('automatically pulls content from a feed'). An agent can distinguish it from list/update/delete/trigger siblings by function, though it never names an alternative to sharpen the distinction.

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

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

No explicit when-to-use guidance, prerequisites, or routing to alternatives such as update_import_source or trigger_import_source. The purpose is inferable but the agent gets no help choosing between this and sibling import 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 declare destructiveHint=false and openWorldHint=false, covering safety profile. The description adds context about redirect permanence (301 vs 302 behavior), but omits details on propagation delay, validation rules, or conflicts with existing paths.

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

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

Two sentences, zero waste. First states purpose; second provides specific HTTP status guidance. Efficiently structured without extraneous text.

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

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

Adequate for a 4-parameter creation tool with complete schema annotations. Given the lack of output schema and simple flat structure, the description covers the essential behavioral context (permanent vs temporary) to supplement the structured data.

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 complete descriptions for all four parameters. The description text reinforces the status_code semantics but adds no new information beyond what the schema already provides. Baseline 3 is appropriate for high-coverage schemas.

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?

Clear verb (Create) + resource (URL redirect). The mention of 301/302 status codes distinguishes this from generic content creation tools like create_content or create_folder. However, it does not explicitly differentiate from sibling update_redirect regarding when to create new vs update existing.

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 specific guidance on status_code values ('Use 301 for permanent...'), which helps parameter selection. However, lacks guidance on when to use this tool versus alternatives (e.g., update_redirect for modifying existing redirects) or prerequisites.

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

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

Annotations declare non-destructive and closed-world. Description adds crucial behavioral context: snippets are Go templates (implementation), render single content items (scope), and integrate specifically into lc:query directives (system integration point). Does not mention idempotency or duplicate name 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?

Three sentences with zero waste: defines action, explains domain concept (Go template + lc:query), and provides usage example. Front-loaded with essential information. Appropriate length for 2-parameter 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?

Complete for a simple creation tool with good annotations. Explains the templating domain, available integration points, and reference syntax. Lacks explicit error behavior documentation (e.g., name collision handling), but otherwise covers the 2-parameter surface adequately.

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

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

Schema coverage is 100% with complete descriptions for both 'name' and 'html' parameters. Description mentions 'Go templates' which reinforces the html parameter type, but does not add semantic detail beyond what the schema already provides. Baseline 3 appropriate for high schema coverage.

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

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

Clear specific verb ('Create') + resource ('snippet'). Distinguishes from siblings (create_template, create_content) by defining snippets as 'Go templates that render one content item in an lc:query index page' and showing the HTML comment reference syntax.

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 context via the lc:query HTML comment example showing how to reference the snippet by name after creation. Explains the specific domain (lc:query index pages). Lacks explicit contrast with create_template, but implied by the specialized definition.

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 destructiveHint=false (safe operation). Description adds context about field definition structure but fails to disclose validation behavior (e.g., conflict handling for duplicate slugs), return value structure, or relationship between fields and html_layout placeholders.

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

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

Two efficient sentences with no redundancy. Second sentence is dense but information-rich. Could benefit from separating field type enumeration from field structure explanation for 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?

With 100% schema coverage and 6 parameters including complex nested structures, the description adequately covers the fields parameter. Missing: explanation of how html_layout references fields via {{.FieldName}}, success indicators, and error conditions.

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% coverage establishing baseline of 3. Description adds significant value by enumerating valid type values (text, textarea, richtext, date, image, select) not constrained in schema, and clarifies the fields array structure implicitly.

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

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

States specific verb 'Create' and resource 'template'. Lists specific field types (text, textarea, richtext, date, image, select) which helps distinguish from sibling creation tools like create_content or create_collection. However, lacks explicit differentiation from update_template.

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 no guidance on when to use this versus update_template, no prerequisites mentioned (e.g., slug uniqueness requirements), and no workflow context. The agent must infer usage solely from the name.

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

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

Annotations only cover openWorldHint and destructiveHint; the description adds the genuinely important trait that the HMAC-SHA256 secret is returned ONCE and must be saved immediately — critical operational context the agent could not infer. It stops short of stating permission/auth requirements or whether delivery is verified by the caller.

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 one-time-secret warning is front-loaded right after the purpose statement, and the event list is compact. Slightly deductive that the event enumeration arguably belongs in the schema rather than prose, but every sentence carries weight.

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 covers the key return value (the secret) and the full event vocabulary, and the schema handles defaults for `active`. Gaps are modest: no auth/permission prerequisites and no note on whether an inactive webhook can be created.

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

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

Schema coverage is 100%, so the baseline would be 3, but the description supplies the closed list of valid event types for the `events` array while the schema has no enum and only an 'e.g.' example. That materially improves correctness of the most error-prone parameter.

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

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

States a specific verb and resource ('Create a new webhook') that cleanly separates it from the create/update/delete/list webhook siblings in the tool set. It goes further by enumerating the valid event types, so an agent understands the resource's domain without opening the schema.

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

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

Usage is only implied: the agent can infer this is the tool for registering a new endpoint, and the valid-event list implicitly tells it what can be subscribed to. There is no explicit when-to-use guidance and no routing to alternatives such as update_webhook or regenerate_webhook_secret.

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

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

Annotations already declare destructiveHint=true, so the safety profile is covered. The description adds nothing beyond that: no statement about irreversibility, whether in-flight approval requests are affected, or required permissions.

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

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

A single front-loaded sentence with no filler. It is tight, though its brevity reflects under-specification rather than disciplined concision.

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

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

For a destructive mutation with one required id and no output schema, the description omits the consequences an agent needs: irreversibility, effect on existing approval requests, and confirmation expectations. Annotations cover the destructive flag but not these operational details.

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

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

Schema description coverage is 100% and the single id parameter is documented in the schema as 'Workflow ID to delete'. Baseline 3 applies since the schema fully carries parameter detail and the description adds no additional format or syntax meaning.

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

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

States a specific verb (Delete) and resource (approval workflow), matching the title exactly. It does not differentiate from siblings like delete_template, delete_redirect, or delete_webhook, but the resource is unambiguous.

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

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

No guidance on when to use this versus alternatives such as update_approval_workflow or cancel_approval_request, and no prerequisites or warnings about when deletion is inappropriate.

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?

While annotations declare destructiveHint=true, the description adds valuable scope context: 'Removes both the file and database record' clarifies this affects both filesystem and database layers. Does not mention idempotency behavior (covered by annotation) or error conditions (e.g., non-existent ID), but adds concrete destruction scope.

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

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

Optimal two-sentence structure. First sentence delivers core action immediately. Second sentence adds necessary scope clarification without redundancy. Zero padding or generic filler. Front-loaded with critical 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?

Adequate for a single-parameter delete operation: annotations cover safety profile (destructive, idempotent), description covers deletion scope. However, lacks mention of error behaviors (404 if ID missing?), return values, or prerequisites (permissions, asset state constraints).

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

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

Schema coverage is 100% with the ID parameter fully documented as 'Asset ID (MongoDB ObjectID)'. Description provides no additional parameter semantics, but with complete schema coverage, the baseline score of 3 is appropriate—no compensation needed.

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?

Excellent specificity: verb 'Delete' + resource 'asset' + location 'library'. Second sentence clarifies scope (file + database record), distinguishing from logical deletes or metadata-only removals. Clear differentiation from siblings like delete_content, delete_folder, etc. by specifying '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?

No explicit guidance on when to use versus alternatives (e.g., no mention of archive_asset if it existed, or bulk operations), no prerequisites stated (e.g., checking if asset is in use), and no 'when-not-to-use' guidance. Only implicit use case from the verb itself.

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 destructiveHint=true, but the description adds crucial behavioral context: the deletion is container-only and preserves content. This prevents the safety assumption that 'destructive' applies to nested content. 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?

Two sentences with zero waste. First establishes the action, second clarifies scope/safety. Perfectly front-loaded and appropriate length for the tool 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?

Sufficient for a single-parameter destructive operation. Critical safety information (content preservation) is covered. Could optionally clarify what happens to orphaned content, but adequate given annotations cover idempotency and destructiveness.

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 ('Collection ID (MongoDB ObjectID),required'), so baseline applies. Description adds no parameter-specific semantics, but the schema handles this adequately.

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?

Clear verb (Delete) and resource (collection). The second sentence ('This does not delete the content...') begins to distinguish from siblings by clarifying scope, though it could more explicitly differentiate from delete_content or delete_folder.

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

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

Provides implicit guidance through the negative constraint about content preservation, helping prevent misuse. However, lacks explicit 'when to use' guidance or comparison to alternatives like archive_fork or bulk operations.

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

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

Annotations already declare destructiveHint=true, so the destructive nature is covered structurally. The description usefully adds the permission/auth requirement (admin only, comment.delete), which is real context beyond annotations. It does not say whether the deletion is permanent or how threaded replies are handled.

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

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

Two short sentences with zero filler; the purpose is front-loaded and the constraint follows immediately. Every word earns its place.

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

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

For a simple two-parameter delete operation with full schema coverage and a destructiveHint annotation, the description covers purpose and access requirements adequately. The only meaningful gap is cascade/reversibility behavior, which an agent might want for a delete on threaded 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 description coverage is 100%, so both comment_id and content_id are already documented in the schema. The description adds nothing about parameter formats or constraints, so the baseline 3 applies.

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

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

States a specific verb+resource (delete a discussion comment), which is unambiguous. It does not, however, distinguish itself from siblings like create_comment or list_comments, so it stops short of a 5.

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

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

The description gives a prerequisite (comment.delete permission, admin only) but no guidance on when to use this tool versus alternatives or when not to use it. There is no routing or context information for an agent choosing among the many 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?

Adds significant value beyond annotations: clarifies 'soft-delete' semantics (recoverable destruction), states the specific side effect of 'Removes the static HTML page,' and confirms idempotency through the restoration capability. No contradictions with destructiveHint=true or idempotentHint=true.

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

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

Three sentences, all essential: defines operation, states recoverability (critical for soft-delete), and specifies side effect. No redundant or wasted words. Information is front-loaded with the core action.

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

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

Comprehensive for a deletion tool: covers soft-delete semantics, recovery path, and specific side effects (HTML removal). Annotations provide safety hints (destructive, idempotent). No output schema present but unnecessary for this operation type given idempotency disclosure.

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 100% schema description coverage for the single 'id' parameter, the schema fully carries the parameter semantics load. Description adds no parameter-specific details, which is appropriate given the high schema coverage baseline.

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

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

States specific action 'Soft-delete' targeting a 'content item' and distinguishes from hard-delete siblings by noting it 'can be restored later.' Also differentiates from other delete_* tools (delete_asset, delete_folder, etc.) by specifying the content resource type.

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

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

Implies reversibility ('can be restored later') which hints at the restore_content sibling tool, but lacks explicit when-to-use guidance or comparisons against alternatives like archive_fork. Provides minimum viable context for agent selection.

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 destructiveHint=true and idempotentHint=true. The description adds crucial behavioral context: the empty-folder constraint (precondition) and implied failure mode for non-empty targets, which annotations do not cover.

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

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

Two sentences with zero waste: first states the operation, second states the critical constraint. Front-loaded and 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?

Adequate for a simple single-param destructive tool. Annotations cover safety/destructive traits; description covers the primary business logic constraint (empty-only). No output schema exists to document.

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?

Input schema has 100% description coverage for the single 'id' parameter. The description does not reference parameters, but the schema is self-documenting, meeting the baseline score for high-coverage schemas.

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

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

Specific verb (Delete) + resource (folder) with clear scope constraint (empty only). The empty-folder restriction distinguishes it from broader delete operations like delete_content or delete_collection, though it doesn't explicitly name sibling alternatives.

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' (empty folder) and 'when-not' (contains content/subfolders) guidance. Missing specific alternative tool recommendations for handling non-empty folders, but the constraint is clearly actionable.

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

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

Annotations already declare destructiveHint=true and openWorldHint=false, so the safety profile is covered. The description goes well beyond that, disclosing exactly what is destroyed (all page copies), the merged-fork exception where only the history record is removed and live pages survive, and the required admin role. That is exactly the added behavioral context the description should carry.

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

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

Three tight sentences, each earning its place: permanent destruction is front-loaded, the merged-fork exception follows, and the auth requirement closes. Zero filler.

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

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

For a one-parameter destructive tool with annotations covering safety and no output schema to explain, the description covers the critical what-gets-destroyed semantics and the admin prerequisite. The only minor gap is failure/error behavior (e.g., deleting a nonexistent or already-deleted fork).

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

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

Schema description coverage is 100%, and the single fork_id parameter is documented in the schema, so baseline is 3. The description adds only the implication that the fork is targeted for permanent deletion, no format or identifier detail beyond the schema.

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

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

The description gives a specific verb and resource ('Permanently delete a fork') and clarifies scope ('and all its page copies'). This distinguishes it conceptually from siblings like archive_fork, though it never names those siblings explicitly. Clear purpose, but no direct sibling routing.

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

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

It explains a genuine usage split — behavior for merged vs unmerged forks — which helps an agent anticipate the outcome. However, it gives no explicit guidance on when to choose this tool over archive_fork, purge_fork_copies, or remove_fork_page. Usage is implied rather than prescribed.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered structurally; the description adds nothing on top of that. It does not say whether previously imported content is removed, whether dependent import jobs are cancelled, or whether the operation can be undone.

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

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

A single front-loaded phrase with zero waste, but its brevity reflects under-specification rather than disciplined concision. Nothing is padded, yet nothing beyond the title is conveyed.

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

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

For a destructive mutation, the description omits the consequences that matter most: what data is destroyed and what happens to any content already imported from the source. Annotations cover the safety flags and the schema covers the ID, but the destructive-impact picture an agent needs before calling this is missing.

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

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

One parameter with 100% schema description coverage, so the schema already documents the required 'id'. The description contributes no additional semantics about the ID format or source of the value, making 3 the correct baseline.

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

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

States a specific verb and resource ('Delete an RSS import source'), which cleanly separates it from siblings like list_import_sources, create_import_source, update_import_source, and trigger_import_source. It stops short of 5 because it names no sibling explicitly, though the resource noun does the disambiguation work.

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?

There is no guidance on when to delete an import source versus deactivating or triggering it, no mention of prerequisites or side effects, and no warning about irreversibility. The agent must infer all usage context from the tool name alone.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, establishing this is a destructive, repeatable operation. The description adds no additional behavioral context such as whether deletion is permanent, if there are cascading effects on linked content, or recovery options. It does not contradict the annotations.

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

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

While extremely brief and front-loaded, the three-word description is so minimal it constitutes under-specification rather than efficient conciseness. It wastes no words, but also provides no informational value beyond the tool name itself.

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 simplicity (single ID parameter), strong annotations, and complete schema coverage, the description is minimally sufficient for an agent to identify the tool's scope. However, it fails to enrich the structured data with any additional context about redirects or deletion behavior.

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 100% schema description coverage, the parameter 'id' is already well-documented in the schema as 'Redirect ID (MongoDB ObjectID),required'. The description adds no parameter-specific guidance, syntax details, or examples, warranting the baseline score for complete schema coverage.

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

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

The description 'Delete a redirect' is a tautology that restates the tool name/title with only slight modification (adding an article). While it identifies the resource type (redirect), it fails to distinguish this tool from sibling deletion tools like delete_content or delete_asset beyond what is already implied by the tool name.

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

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

The description provides no guidance on when to use this tool versus alternatives such as update_redirect (for modifying vs. removing) or create_redirect. There are no prerequisites, conditions, or exclusion criteria mentioned.

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

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

While the destructiveHint annotation confirms this is destructive, the description adds no behavioral context about what happens to content referencing the deleted snippet, whether this is a hard delete or soft delete, or error conditions if the ID is not found.

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

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

The four-word description is efficiently front-loaded with no redundant information. However, extreme brevity for a destructive operation leaves it under-specified for the risk level involved.

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

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

Given the simple single-parameter input and lack of output schema, the description minimally covers the operation but omits critical context for a destructive tool: cascading effects, restore possibilities, and return status expectations.

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 100% schema coverage describing the MongoDB ObjectID requirement, the description meets the baseline. It mentions 'by ID' which aligns with the schema but adds no additional semantic context about ID format constraints or validation beyond the schema definition.

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 (Delete) and resource (snippet), distinguishing it from sibling delete operations on assets, collections, or folders. However, it lacks explicit scoping details that would elevate it to a 5, such as clarifying this is for permanent single-item removal versus archiving.

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

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

The description provides no guidance on when to use this tool versus alternatives like bulk_field_operation, nor does it mention prerequisites (e.g., whether the snippet must be unreferenced first) or irreversibility warnings beyond the annotation.

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

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

Annotations cover destructiveness and idempotency. The description adds valuable behavioral context: validation rules preventing deletion of system templates and templates with dependencies. This explains failure modes not captured in annotations.

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

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

Two sentences, zero waste. Front-loaded with the action ('Delete a template'), followed immediately by critical constraints. Every word earns its place.

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

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

Appropriate for a single-parameter deletion tool. Captures the essential constraint logic (system/dependency blocks). Lacks mention of return values, but destructiveness and idempotency hints reduce ambiguity for a delete operation without output schema.

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

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

Schema has 100% coverage with clear ID description ('Template ID (MongoDB ObjectID)'). The description references 'a template' implying identification is needed but does not augment the parameter documentation 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?

Clear verb ('Delete') and resource ('template'). The scope is implicit given the tool name and sibling tools (delete_content, delete_folder, etc.), though it could explicitly specify 'content template' to distinguish from potential email/code templates.

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?

Strong explicit constraints: 'Cannot delete system templates or templates that have content using them.' This clearly identifies when the operation will fail. Lacks explicit alternatives (e.g., 'use archive instead'), but the constraints provide critical usage guardrails.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered structurally. The word "Permanently" reinforces irreversibility, which adds a little context, but the description says nothing about side effects (in-flight deliveries, subscriptions) or auth requirements beyond what annotations give.

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?

One sentence, front-loaded with the action and the irreversibility qualifier, with zero filler. It is efficient, though so terse that it does little work beyond the tool name.

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

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

For a single-parameter delete with destructive/idempotent annotations and no output schema, the essentials are present: the action, its permanence, and a fully documented ID. Missing are cascade/irreversibility details and any confirmation or error behavior, which keeps it at minimum-viable 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 single id parameter has 100% schema description coverage, so the schema already carries the semantics. The description adds no format, ID-source, or validity guidance beyond that, making the baseline 3 appropriate.

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

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

States a specific verb (delete) and resource (webhook) plus the permanence qualifier, so an agent can distinguish it from update_webhook, create_webhook, or regenerate_webhook_secret. It stops short of explicitly naming or routing against those siblings, so it lands at 4 rather than 5.

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?

There is no when-to-use guidance, no mention of alternatives (e.g., update_webhook if the agent only wants to modify), and no prerequisite such as needing a valid webhook ID or confirmation before a destructive call. The agent must infer everything from the name.

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

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

Annotations only give a blanket destructiveHint=true; the description resolves that ambiguity by specifying that 'discard' permanently deletes the fork and every change while 'submit' preserves it at /cm/forks/{id}. Disclosing the human-merge governance rule is behavior an agent cannot infer from annotations or schema.

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

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

Three tight sentences, front-loaded with the purpose, then the action semantics, then the governance constraint. No filler and nothing restating the tool title.

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

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

For a single-parameter tool with no output schema, the description covers both execution paths and the policy boundary, which is nearly everything an agent needs. It does not say what the call returns or what state the session is left in after 'submit', a minor gap given no output schema exists.

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

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

Schema coverage is 100% and the schema already defines both enum values, so 3 is the baseline. The description nonetheless adds the fork's review location (/cm/forks/{id}) and the irreversibility contrast between the two actions, which is slightly more than the schema conveys.

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

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

States a specific verb+resource ('End the sandbox session') and then unpacks the two terminal outcomes, keeping the fork for human review versus permanently deleting it. This clearly separates it from merge_fork and delete_fork, which are the nearest siblings an agent might confuse it with.

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 tells the agent which action to pick and why: 'submit' for human review/merge, 'discard' for permanent deletion. It also states a hard constraint (agents cannot merge their own sandbox), which is genuine when-to-use guidance. It stops short of saying when to prefer this over rollback_agent_session or get_agent_session_changes.

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 (safe operation). The description adds valuable return structure disclosure ('page titles, paths, and snippets') which compensates for the missing output schema, but omits other behavioral details like rate limits, result ordering, or empty-result 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?

Two well-structured sentences with zero redundancy. Front-loaded with the action 'Search published content', followed by mechanism (match modes), then return values. Every word earns its place.

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

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

Given 100% schema coverage and readOnly annotations, the description is appropriately complete. It compensates for the missing output schema by specifying the return payload structure ('titles, paths, and snippets'). Could be improved by noting result limits or pagination behavior.

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 clear descriptions for all three parameters (query, mode, limit). The description reinforces the mode options ('full-text exact match', 'semantic (AI)') but does not add syntax guidance, format requirements, or examples beyond what the schema already provides. Baseline 3 is appropriate for high-coverage schemas.

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?

Clear verb ('Search') and resource ('published content') with specific scope. The phrase 'published content' effectively distinguishes this end-user facing search from administrative alternatives like 'search_content' that might include drafts, though it doesn't explicitly name the sibling alternative.

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

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

No explicit guidance on when to use this tool versus the sibling 'search_content' tool, or when to prefer exact vs semantic vs hybrid modes. The description provides no 'when-not-to-use' constraints or prerequisite conditions.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuine behavioral context: only live pages are exported and fork copies appear in 'skipped' as {id, reason}. It does not mention pagination or limits on large exports, but the fork/skipped disclosure is valuable 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?

Front-loaded purpose sentence, then clearly sectioned scope filters, field selection, and return shape. Each line earns its place; the structured formatting makes scanning fast.

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 supplies the return shape (total count and item fields). For a zero-required-param read tool with full schema coverage, everything an agent needs to scope and call it 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 coverage is 100%, so the baseline is 3. The description goes further by annotating template_name as 'most useful for bulk workflows' with concrete examples ('Concept Page', 'Blog Post') and demonstrating the fields array syntax, adding meaning beyond the schema's terse descriptions.

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

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

States a specific verb (export) and resource (content items), plus the output form (structured JSON array with full field data). It is clearly distinguishable from siblings like list_content or get_content, which don't carry the batch-export/full-field intent.

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

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

Gives an explicit workflow (export → transform externally → re-import via bulk_update_content), naming the downstream sibling tool. Scope filters are described with guidance on which to prefer for bulk work.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds genuinely new context: an admin-only authorization requirement and the fact that this breaks a lock held by another party. It does not say what happens to the previous holder's work or whether the action is logged.

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?

One sentence, front-loaded with the authorization gate and the action, with zero redundant or decorative phrasing.

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

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

For a one-parameter admin action with no output schema and annotations covering the safety hints, the description is nearly sufficient. Only minor gaps remain, such as the error behavior when no lock exists or what the caller receives back.

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% for the single content_id parameter, so the schema already carries the semantics. The description adds nothing about the identifier format or how to obtain it; baseline 3 applies when the schema does the work.

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

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

States a specific verb (force-release) and resource (lock on a content item) with the defining scope qualifier 'regardless of who holds it,' which cleanly separates it from the owner-scoped release_content_lock sibling. It stops short of naming that sibling, so the distinction must be inferred.

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?

'Admin only' gives a clear permission prerequisite, and 'force-release any lock regardless of who holds it' implies the override scenario. However, it never explicitly says when to prefer this over release_content_lock or what situation warrants the override, leaving the routing decision implied.

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

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

Annotations provide idempotentHint:true and destructiveHint:false. Description adds valuable behavioral context: confirms idempotency with 'If the page is already in this fork, returns the existing fork copy', mentions output 'Returns the fork page ID', and notes admin requirements for the merge step. 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?

Front-loaded with purpose in first sentence. Efficiently structured with bullet points for parameter options and numbered list for workflow. Every sentence earns its place: purpose, input options, output/workflow, and idempotency edge case. No waste.

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

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

No output schema exists, but description documents return value (fork page ID) and complete lifecycle workflow including verification step. Covers edge case (already forked) and authorization note. Adequate for a complex CMS fork operation with 3 input 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 has 100% coverage (baseline 3). Description adds selection guidance distinguishing path ('preferred when you know the URL') from content_id, and documents their mutual exclusivity via 'Provide either'. Adds semantic value beyond raw 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?

Opens with specific action 'Copy a live page into a fork workspace' plus clear benefit 'edit without affecting the public site'. Distinguishes from siblings like create_content (creates new) vs. forking existing, and explicitly references the workflow endpoint merge_fork.

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 4-step workflow (fork_page→update_content→get_content→merge_fork) with tool names. Explains parameter selection logic ('preferred when you know the URL'). Notes authorization constraint 'admin only' for merge step. Handles idempotency case.

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 establish the safe read-only profile, so the description's job is to add return semantics — and it does, enumerating fork ID, name, changed pages, and per-field diffs against live, plus the inactive case ('if so'). It stops short of stating what an inactive result looks like (null vs empty) or any error/pagination behavior.

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

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

One sentence, front-loaded with the primary question (is it active) before the detail payload. No filler, no repetition of the title or annotations.

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

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

With no output schema, the description carries the full burden of describing the return value, and it does so reasonably well for a zero-parameter status tool. Missing only edge-case behavior: exact shape of the inactive response and whether diff detail is truncated for large change sets.

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?

Zero parameters, so the baseline is 4; there is nothing for the description to disambiguate. No key/ID input is accepted, meaning it operates on implicit session context, which the description does not clarify but also does not need to given the empty schema.

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

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

The description names a specific verb (show) and resource (agent sandbox) and states the scope of what is reported: activity status, fork ID, name, and changed pages. It is distinguishable from start_agent_sandbox/end_agent_sandbox, though its 'pages changed so far' overlap with get_agent_session_changes could blur the line with that sibling. Clear but not explicitly differentiated from every neighbor.

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 read-only status framing implies usage (check sandbox state before acting on it), but it never states when to call this versus get_agent_session_changes, list_forks, or get_fork_diff. No prerequisites, no when-not guidance, no alternatives named.

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