Pixelesq

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

Beyond the annotations, the description discloses concrete mechanics: validates section.type === "Uislice", applies a single SET_COLLECTION operation, writes to the page draft under the revision lock, checks the section anchor, and forks the draft from the published head when needed. It also explains mapping fallback behavior, warning behavior when no mapping can be built, and specific error cases including BASE_VERSION_MISMATCH retry guidance with a new idempotencyKey.

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

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

The description is front-loaded with purpose and exclusion, then organized into mapping, mechanics, and errors. It is long and dense, but the complexity of the nested mapping and revision-lock behavior justifies most of the length; a few sentences could still be tightened.

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

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

For a mutation tool with no output schema, nested parameters, and existing safety annotations, the description covers validation, draft/revision behavior, mapping fallback, result reporting, and the key error/retry paths. An agent has enough information to invoke it correctly and interpret failures.

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

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

Schema description coverage is 100%, so the baseline is 3; the description goes further by explaining the connection mapping structure, the special entryName placeholder, where other field names come from (get_collection), and what happens when connection is omitted. The remaining parameters are largely already covered by the schema, so this is meaningful added value but not a complete re-specification of all six parameters.

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

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

The description states a precise verb+resource: connecting a Uislice section on a page to a collection so its items render collection entries. It explicitly distinguishes this from save_section_content / save_page_content / save_partial_content, which do not change collection bindings, and explains the static-placeholder contrast.

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 a clear usage condition — use after inserting a list-style section (cards, grid, listing) that should show collection entries — and explicitly excludes save_* tools from this job. It does not mention the sibling unbind_section_from_collection as the inverse operation, nor does it state when binding should be avoided beyond the partial-section error later in the text.

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 flag destructiveHint=true but say nothing about why; the description explains the real hazard — a retry creates a duplicate collection, so verify with list_collections first. It also discloses the post-create state (only Name/Slug fields present) and the notable side effect of hasPages: entry pages render with no body until a dashboard-designed template is published. This is context annotations cannot convey.

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

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

Front-loaded with the core action, then follow-up, then the hasPages caveat, then retry safety — a sensible priority order with no filler. It is dense and slightly long for one paragraph, and 'Entries feed listings and sections bound to the collection' is background rather than actionable, but the remaining sentences all carry operational 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?

No output schema exists, so the description carries the burden of describing what comes back (the new collection's fields and updatedAt) and how to proceed, which it does. For a mutating, non-idempotent create with a non-obvious downstream template dependency, the description covers the prerequisites, the side effects, and the failure mode.

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

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

Schema description coverage is 100% and the description largely restates schema text — the hasPages explanation ('starts empty and is designed in the dashboard') and the slug's entry-page role both already appear in the parameter descriptions. The only genuine addition is the instruction to keep Name and Slug in the field list on the follow-up call, which is guidance about a sibling call rather than about this tool's parameters.

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

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

States a specific verb and resource ('Create a new content collection') and immediately distinguishes it from sibling update_collection_schema by describing what this tool does and does not create (only Name and Slug fields exist afterward). An agent can differentiate it from create_entry, create_page, and create_form without opening any schema.

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

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

Gives explicit sequencing guidance ('call update_collection_schema with this result's updatedAt to define the rest of the field schema') and explicit recovery guidance ('look for the slug with list_collections before trying again'). It names the alternative tool for each situation, which is exactly the when/when-not routing an agent needs.

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 readOnlyHint=false, and the description adds real behavioral context beyond that: content is validated against the collection schema with warnings on rejection, built-in name/slug keys in content are refused, and a retry creates a second entry (non-idempotent). That non-idempotency warning is exactly the kind of risk detail annotations cannot convey.

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

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

Purpose is front-loaded and every sentence carries payload (validation, value shapes, name/slug exclusion, retry hazard). It is dense and slightly cramped into a single block, but no sentence is 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 5-param mutation tool with no output schema, the definition covers validation behavior, slug derivation (via schema), and duplicate-creation hazard well. The one gap is that it never says what a successful call returns (e.g., the new entry ID), which an agent would need for follow-up calls.

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 would be 3, but the description adds substantial semantics the schema lacks: 'content' is documented only as free-form key-value pairs, and the description specifies value shapes (arrays for list:true, entry ID strings for references, YYYY-MM-DD or offset-timestamp for dates) and that name/slug live at top level. Minor deduction only because the reference/date rules depend on external 'config.time' context.

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

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

States a specific verb and resource ('Create a new entry in a collection') and implicitly separates itself from update_entry and save_entry_content by emphasizing 'new'. An agent can identify the operation and its scope immediately.

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

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

Gives explicit sequencing ('call get_collection first') and an explicit recovery path ('look for the slug with list_entries before trying again'), plus a clear exclusion ('keys for the built-in name and slug fields are refused'). This is when-to-use guidance an agent can act on without 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?

Goes well beyond the annotations: it discloses the non-effect on the live site, the pre-write validation that refuses duplicate field names, orphaned optionScores and bad gateFields, that score ranges produce warnings rather than refusal, and that a retry duplicates the form. This is exactly the side-effect and failure-mode detail an agent needs for a destructiveHint write.

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

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

Purpose is front-loaded and nearly every sentence carries information the agent cannot get elsewhere. The weakness is form: one long run-on paragraph with no bullets, which makes the scoring and calculator rules hard to scan.

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 large, deeply nested creation schema with no output schema, the description covers the critical semantics: validation refusals vs warnings, scoring modes, calculator breakdowns, and the retry hazard. An agent has enough to construct a valid call and anticipate failure.

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 real meaning on top: how optionScores are keyed by option id, how score mode sums points into scoreRange cards, what calculator.display/stats/parts do, and how optionParts must sum to each option's points. It is not a restatement of schema text, though it still leaves many nested objects (gatedAsset, autoresponder, conversational) to 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 ('Create a new form in a project') and immediately clarifies scope: the form is not on a page yet, so the live site does not change. That distinguishes it from update_form_schema, insert_section and create_page without the agent opening any schema.

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

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

Gives clear conditional guidance for the risky case: 'A retry makes a second form: if the answer was lost, look for it with list_forms before trying again', naming the alternative tool and condition. It does not explicitly compare against update_form_schema, so an agent must infer that editing an existing form belongs elsewhere.

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 say readOnlyHint=false and destructiveHint=true; the description adds the real behavioral payload: the page starts empty and unpublished, slug collisions silently get a suffix (so results must be re-read), and idempotency is scoped to the key+project+address tuple. These are side effects an agent could not infer from 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?

Four tight sentences, each carrying distinct information: lifecycle state, collision behavior, retry safety, and the no-key fallback. Creation scope is front-loaded and nothing is repeated from the schema.

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

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

For a mutation tool with no output schema, the description covers lifecycle, slug rewriting, and retry semantics thoroughly. It references 'the slug in the result' without saying what else the result contains, a minor gap given no output schema exists to fill it.

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 still earns credit by adding composite-key semantics for idempotencyKey ('the same key, project and address name one page') that the schema's per-field description does not spell out, plus slug-suffix behavior that changes how the returned slug must be handled.

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 draft page in a project') plus a lifecycle qualifier (draft, not live) that separates it from create_entry/create_collection and from publish_page. An agent can identify the tool without opening the schema.

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

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

Gives concrete conditional guidance: pass idempotencyKey for safe retries, and without one, verify the address with list_pages before retrying. It does not discuss sibling alternatives for page creation itself, but for a sole-purpose create tool the retry routing is the relevant decision.

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

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

Annotations already flag destructive and openWorld behavior, but the description adds substantial context: redirects go live without publishing, usually within minutes, can replace a live page, reject loops, and require confirmation in risky cases. It also covers retry behavior when the answer is lost.

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

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

The description is front-loaded with the core action and then supplies only high-value behavioral constraints. Every sentence earns its place; there is no filler or repetition.

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

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

For a destructive openWorld mutation with no output schema, it covers timing, side effects, uniqueness conflicts, loop refusal, confirmation requirements, and retry advice. Return shape is not described, but invocation requirements are complete.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds useful semantics beyond the schema for source uniqueness and confirm conditions, though it does not explain the permanent or description parameters beyond what the schema already says.

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 URL redirect.' It also names list_redirects for checking existing redirects, making it distinguishable from list/update/delete redirect 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?

Explains key use conditions and refusals: unique active source, no redirect loops, and confirm required for the home page or offsite destinations. It points to list_redirects after a lost answer, but does not explicitly route existing redirects to update_redirect.

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 bar is lower, but the description still adds real context: the deletion is permanent, there is no undo, and a published entry's page goes offline and drops out of live listings immediately. It stops short of describing permission requirements or cascade effects on related content.

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, nothing wasted, and the permanence warning plus immediate side effects are front-loaded right after the action statement.

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 and full schema coverage, the description only needs to convey consequence and irreversibility, which it does well. It could be more complete by noting any required prior state or authorization, but nothing an agent needs to invoke it safely is missing.

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

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

Schema description coverage is 100% and both parameters (entryId, projectId) are documented in the schema, so the baseline of 3 applies. The description adds no syntax, format, or constraint detail beyond what the schema already carries.

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?

'Delete a collection entry permanently' states a specific verb and resource, and 'collection entry' cleanly separates it from the sibling delete_page and delete_redirect tools without needing their schemas.

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

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

Usage is implied by the destructive verb, and the description usefully notes the immediate effect on live listings, but it never names the alternative (e.g., unpublish_entry) for taking a published entry offline without destroying it, which is the one routing decision an agent faces here.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is partly covered. The description adds real value beyond them: permanence ('no undo') and the immediate side effect on a published page. It omits permission requirements and what happens to child sections/entries.

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

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

Two short sentences, zero filler, and the irreversible consequence is front-loaded right after the action. Everything written 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?

No output schema exists, so return values needn't be explained, and the annotations carry the destruction signal. For a 2-param delete the description is nearly sufficient; only the unpublish-vs-delete decision and permission/cascade effects are absent.

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

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

Both parameters are required and have 100% schema description coverage, so the schema already carries the semantics. The description adds no format, scope, or constraint detail for pageId/projectId, 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 page permanently.' An agent can immediately tell it targets a page. It does not, however, differentiate itself from sibling delete_entry/delete_redirect beyond the resource noun, and gives no route to unpublish_page.

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 'A published page goes offline at once; there is no undo' implies the destructive/irreversible branch of usage, but never names unpublish_page as the reversible alternative. When-to-use is inferable but not stated, so this sits at minimum-viable.

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=true, and the description adds genuinely useful behavior beyond them: the live site stops redirecting without a publish, usually within minutes. That timing and no-publish effect is exactly the operational context a destructive tool needs. It stops short of stating whether the deletion is recoverable 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?

Two short sentences with zero waste; the action comes first and the behavioral consequence follows. Every clause earns its place.

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

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

For a two-param destructive call with no output schema and annotations already covering the safety profile, the description supplies the missing piece (immediate unpublish-free effect). Only the reversibility/permission story is absent, a minor gap against the otherwise complete picture.

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

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

Schema description coverage is 100% (both UUID params are documented), so the schema carries the parameter burden. The description adds no syntax, format, or scoping detail beyond it, which is the expected baseline when coverage is complete.

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 a URL redirect') that unambiguously separates it from create_redirect, update_redirect, and list_redirects. An agent knows exactly what object is being acted on 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?

No when-to-use or when-not-to-use guidance is given, and no alternative is named (e.g., update_redirect to disable rather than remove). The single-target delete is implied by the verb, but nothing addresses the delete-vs-modify decision an agent actually faces.

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 readOnlyHint=false, and the description adds the key non-obvious trait: this operation is not idempotent, each retry makes another copy. That is real value beyond the annotations, though it doesn't state what the response contains (e.g., new entry ID) beyond implying the copy is findable via list_entries.

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

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

Two tight sentences; the core action is front-loaded and the retry hazard follows as the secondary but important caution. No wasted words.

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

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

No output schema exists, and the description implies the returned copy is retrievable via list_entries while covering the mutation's non-idempotency risk. Slightly short on what exactly gets copied or the return shape, but adequate for a two-parameter mutation with annotation 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 description coverage is 100% and both parameters are documented in the schema, so the description needn't repeat them. It adds no syntax or scoping detail (e.g., cross-project behavior) beyond the schema 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 ('Duplicate an existing collection entry with all its content'), which immediately separates it from create_entry (new entry) and duplicate_page (pages). An agent can select it without opening the schema.

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

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

Explicitly warns that retries create additional copies and directs the agent to list_entries to recover a lost answer, naming the sibling tool. It does not cover when to duplicate vs. re-create from scratch, so it stops short of a full 5.

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

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

Annotations already declare a destructive write with no open-world reach, so the bar is lower, and the description adds genuinely non-obvious behavior: the copy is deep (sections plus content) and the operation is non-idempotent. It stops short of saying what the response contains (e.g., whether the new page ID is returned) or where the copy is placed.

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, the operation is stated first and the retry caveat second. Every clause earns its place and nothing is repeated from the annotation or schema.

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

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

For a two-param mutation with no output schema, the description covers the risky part (non-idempotency and how to recover) and the copy depth. It leaves open what the caller receives back, which matters for a tool whose whole hazard is a lost response.

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

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

Schema coverage is 100%, with both projectId and pageId documented in the schema itself. The description adds no format, constraint, or scoping detail for either parameter, so the schema carries the whole load and 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?

Uses a specific verb ('Duplicate') with a specific resource ('an existing page') and states the scope of what is copied ('all its sections and content'). The resource noun distinguishes it from duplicate_entry, though it never explicitly contrasts with that sibling or with create_page.

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 concrete retry guidance: a retry makes another copy, so verify with list_pages when the original response was lost. This is real when-to-use guidance aimed at non-idempotency, but it doesn't cover when to duplicate versus build a new page from scratch.

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 reveal readOnly=false, destructive=true, openWorld=true; the description adds the behavior those hints do not: quota consumption, concurrency limits, clear-error behavior when disabled/exhausted, and the exact immediate return shape { status: 'pending', jobId } with no output schema to convey it. This is substantial context beyond structured data.

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

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

Front-loaded with the purpose, then prerequisites, return contract, and routing guidance in a logical order; each clause earns its place. It is dense and parenthetical-heavy, which costs a little readability, but there is no filler.

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

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

For a 5-parameter, async, side-effecting tool with no output schema, the description covers prerequisites, error conditions, the immediate return contract, and the required polling follow-up. Nothing an agent needs to invoke and complete the workflow correctly is missing.

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

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

Schema description coverage is 100%, so every parameter (count, prompt, quality, projectId, aspectRatioOverride) is already documented in the schema; the description adds no per-parameter syntax, format, or constraint detail. Baseline 3 is appropriate when the schema carries the load.

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 ('Generate image(s) with AI') and immediately clarifies the async, start-only nature of the operation. It distinguishes itself from siblings by naming search_stock_images + upload_asset as the alternative for real-world photos, so an agent can route without opening any schema.

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

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

Explicit when-to-use ('custom, branded, or illustrative imagery'), explicit when-not ('real-world photos' → search_stock_images + upload_asset), plus prerequisites to check first (get_project context.imageGeneration.enabled, get_imagegen_quota). The follow-up workflow (poll get_image_job, set url as section media.src) is also spelled out.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds the domain scope of the data (AI platforms such as ChatGPT, Claude, Perplexity) but says nothing about attribution logic, aggregation granularity, or behavior when no AI referrals exist. Adequate but not rich.

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 filler; the resource scope and the concrete platform examples are the only content and both earn their 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 2-parameter read-only tool with full schema coverage the core is covered, but there is no output schema, so the description could usefully say what metrics/shape come back (sessions, referrers, per-platform breakdown). Without that, an agent knows what to call but not what it will receive.

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% — both 'days' (default 30) and 'projectId' (UUID) are documented in the schema. The description adds no meaning beyond the schema, e.g., the timezone or whether 'days' is calendar or rolling; baseline 3 applies since the schema carries the load.

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 ('get analytics for traffic referred from AI platforms') and enumerates the source platforms, so the agent knows exactly what data class this returns. It does not, however, distinguish itself from near-siblings like get_site_analytics or get_search_performance, which cover overlapping analytics territory.

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: an agent can infer this is for AI-referred traffic specifically, but the description gives no when-to-use condition, no prerequisite (e.g., analytics must be connected), and never names get_site_analytics or get_search_performance as the alternative for non-AI traffic.

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

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

Annotations already declare readOnlyHint, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds a genuinely useful trait beyond the schema: the data is 'as last synced from Google', disclosing that results are a cached snapshot rather than a live query — material for an agent deciding whether to re-check. It omits any prerequisite that a GSC connection must exist, which caps it below 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?

One sentence with zero waste, front-loaded with the verb and resource, and the scope qualifier follows immediately. Nothing is padded or repeated from the 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?

An output schema exists, so return values need no explanation, and the single required parameter is fully documented in the schema. For a simple read-only batch-status tool, the only substantive extra an agent needs — that the data is a sync snapshot — is already stated; the missing GSC-connection prerequisite is minor.

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 projectId parameter, so the schema already carries the semantics. The phrase 'in a project' confirms the scoping but adds nothing beyond what the schema states; baseline 3 applies.

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

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

States a specific verb and resource (get Google Search Console indexing status for all pages in a project), and the plural 'all pages' implicitly separates it from the singular get_page_index_status sibling. It does not explicitly name that sibling, so the differentiation is inferable rather than stated.

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 when-to-use or when-not-to-use guidance, and no mention of the sibling get_page_index_status for per-page lookups or inspect_url for live inspection. The usage is implied by the scope phrase 'for all pages in a project', which is enough to act on but leaves the agent to infer alternatives.

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

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

Annotations already declare the read-only, non-destructive, closed-world nature of the tool. The description adds substantial behavioral context beyond that: field type semantics, list/array behavior, reference targets, date config shape, and the special handling of built-in name and slug fields.

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

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

The description is front-loaded with the core action, then spends its length on high-value schema semantics needed because there is no output schema. Every sentence provides actionable interpretation or usage guidance, with no filler.

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

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

Given the lack of an output schema, the description carries the return-value burden well by explaining field types, config formats, built-in fields, and the critical `list` distinction. An agent has enough context to call the tool and correctly interpret the result.

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 projectId and collectionId are already documented in the input schema. The description adds no parameter-specific meaning beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Get a collection's schema and field definitions.' It also distinguishes this tool's role from update_collection_schema and get_entry by explaining how updatedAt and name/slug fields are used elsewhere.

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 explains when the result matters, such as passing updatedAt to update_collection_schema and checking `list` before writing content. It stops short of explicitly naming alternatives like list_collections or spelling out when not to use this tool.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description adds genuinely new semantics: firstPublishedAt is null when the page was never public, page.slug is the live address, draftSlug is a pending address. Good added value without contradicting 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?

The purpose is front-loaded and the remaining sentences are dense with field semantics rather than filler. It is somewhat information-packed, but each clause carries usable meaning, especially given the absence of an output schema.

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

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

There is no output schema, so the description must document return values itself, and it does so thoroughly (content vs metadata, draftSlug vs page.slug, firstPublishedAt, publishedRevisionId, latestRevision.version/id, headAnchor). An agent has everything needed to call it and use the result downstream.

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 both required parameters (projectId, entryId), so the schema already carries the input semantics. The description's field discussion concerns return values, not input parameters, so no extra input meaning is added; 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 states a specific verb+resource (get a collection entry's content and metadata), which clearly separates it from list_entries, get_page, and get_collection. However, it does not explicitly contrast itself against the nearest siblings such as get_page_content or list_entries within the collection domain.

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 routes the agent usefully: it identifies which returned fields feed save_entry_content (latestRevision.version) and publish_entry (latestRevision.id plus headAnchor), and explains that draftSlug is applied by the next publish_entry. It gives clear downstream context but no explicit when-not/alternative clause (e.g. versus list_entries or get_page).

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

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

Annotations already declare the safety profile (readOnlyHint, destructiveHint=false), so the bar is lower, and the description adds substantial value by enumerating the return contents (fields, optionScores, optionParts, showWhen, scoring, calculator/delivery settings, updatedAt). It also discloses the optimistic-concurrency role of updatedAt, though it does not spell out authorization or error behavior.

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

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

The purpose is front-loaded in the first sentence, followed by the return inventory and the workflow instruction. The dense return list is informative rather than padded, though it could be tightened.

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 return-value burden and does so thoroughly, and the two required params are covered by the schema. Combined with annotations covering safety, an agent has enough to call it correctly, with only minor gaps in error/edge-case 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% for both formId and projectId, so the schema already documents the parameters fully. The description adds no syntax or format detail beyond the schema, so the baseline 3 is appropriate.

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

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

States a specific verb and resource ('Get one form') and scopes it precisely ('its complete schema'), which cleanly separates it from list_forms and get_form_submissions. An agent can identify this as the single-form read tool without opening the schema.

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

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

Explicitly tells the agent to 'Read here before update_form_schema' and to pass the returned updatedAt as expectedUpdatedAt, naming the sibling and the sequencing rule. This is actionable when-to-use guidance rather than vague context.

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

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

Goes well beyond the readOnly/destructive annotations: explains spam filtering, that rows carry status and spamReason, that partial submissions are hidden by default while pagination.total still counts them, that counts includes partials, and flags that results contain user-entered PII. This is rich behavioral context an agent cannot infer from annotations alone.

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 formId guidance, and every clause earns its place by explaining filtering/count behavior. It is dense with nested parentheticals, which slightly hurts scanability but not correctness.

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

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

Despite having no output schema, the description fully specifies the return shape (results, pagination, counts) and field meanings. Combined with the PII warning, an agent has everything needed to call and interpret results.

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?

Although schema coverage is 67%, the description clarifies the non-obvious semantics: the status enum's effect on filtering, the interaction between includePartial and pagination.total, the meaning of counts.ok, and the default limit of 20. This adds meaningful interpretation beyond the raw 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 ('Gets submissions for a form'), names the sibling (list_forms) that supplies the formId, and specifies ordering (newest first). An agent can identify and scope this tool without opening the schema.

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

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

Explicitly routes the agent to list_forms to obtain formId, and defines when each status value applies (inbox default excludes spam, ok/suspect/spam list one kind, all lists everything). It also states exactly when to use includePartial to surface unfinished submissions.

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, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context by naming propertyCoversSite and suggestedProperty as result concepts, which helps an agent understand what the check evaluates.

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 wasted preface. The parenthetical efficiently explains the suggestedProperty nuance without derailing the main purpose.

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

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

For a simple read-only status check with one well-documented parameter, the description is nearly complete. It explains the key connection and property-coverage concepts, though without an output schema it could be slightly more explicit about the full response shape or not-connected states.

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 projectId parameter, so the schema already carries the parameter documentation. The description only references 'this project' and does not add format, source, or selection guidance beyond the schema.

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

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

The description states a specific verb and resource: checking whether Google Search Console is connected to a project and whether the connected property covers the site address. It is clearly distinct from sibling analytics and inspection tools such as get_search_performance and inspect_url.

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

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

Usage is implied by the connection-status framing, but the description does not explicitly say when to choose this tool over related siblings or what to do if the result is not connected. It also does not mention prerequisites beyond the project context.

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

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

Annotations already establish this as a safe read-only, non-open-world query, so the bar is lower; the description still adds the return contract ({ used, limit, remaining, plan, unlimited }) and the key edge case that remaining is null when unlimited. It does not cover freshness/latency or whether the monthly window resets on a fixed date.

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

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

Two sentences, zero filler: purpose and the ordering constraint come first, the return shape second. Every clause earns its place.

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

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

With no output schema, the description compensates by enumerating the returned fields and the null-when-unlimited semantics, which is exactly the information an agent needs to interpret the result. Nothing material is missing for a one-parameter read tool.

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

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

Schema coverage is 100% and the single uuid-constrained projectId is fully documented in the schema, so the baseline is 3. The description only implies the quota is project-scoped ('the project's') without adding format or acquisition guidance beyond what the schema provides.

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

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

States a specific verb (check) and resource (project's monthly AI image-generation quota), with clear scope. It is trivially distinguishable from siblings like generate_image and get_image_job without opening any schema.

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

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

Explicitly positions itself as a pre-flight check: 'before calling generate_image', which routes the agent to the correct sequencing relative to a sibling. It stops short of stating exclusions or failure modes (e.g. what to do if remaining is 0).

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds genuine value beyond that by disclosing the status lifecycle (pending|running|completed|failed) and the completed payload shape, which it must since no output schema exists. It omits polling cadence/termination behavior, so not a 5.

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

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

Two sentences, zero filler, with the core purpose front-loaded and the return-value contract following immediately. Every clause earns its place.

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

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

With no output schema and only two fully-documented params, the description correctly assumes the burden of explaining return values and does so completely, including the status enum and completed asset structure. Nothing needed to call or interpret the tool is missing.

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

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

Schema description coverage is 100%, so both jobId and projectId are already documented in the schema. The description only echoes the jobId origin ('started by generate_image') without adding format or constraint detail, so the baseline 3 applies.

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

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

States a specific verb and resource ('Poll an AI image-generation job') and explicitly ties it to the originating sibling 'generate_image'. An agent can immediately distinguish this polling tool from generate_image without opening either schema.

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

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

The phrase 'started by generate_image' establishes the precondition and the correct context for calling it, and 'Poll' implies repeated invocation. It stops short of explicit when-not guidance or telling the agent to keep polling until a terminal status, so it falls 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered by structured data. The description adds nothing beyond that: it doesn't say what fields the 'details' include, whether it errors on missing pages, or how it relates to get_page_content. With annotations carrying the load, the description contributes no incremental behavioral context.

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

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

It is a single front-loaded sentence with no filler, which is structurally fine. But the brevity comes at the cost of substance rather than being earned concision, so it sits at adequate rather than strong.

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

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

For a two-parameter read tool with no output schema, the description should at minimum clarify what 'details' means and how it differs from get_page_content or get_page_revisions. It leaves both questions open, so an agent choosing among the page-reading siblings is under-informed.

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 (pageId, projectId) are documented in the schema with UUID formats, so the baseline of 3 applies. The description does not add format, constraint, or relationship information beyond the schema, but it is not required to.

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 verb ('Get') and a resource ('details of a specific page'), so the basic purpose is legible. However, 'details' is unspecified, and the description does nothing to distinguish this tool from close siblings like get_page_content, get_page_revisions, get_page_index_status, or list_pages. An agent cannot tell from this text which page-inspection tool returns what.

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 exclusions, and no mention of alternatives, despite the sibling list containing at least four other page-reading tools. The only implicit signal is that both IDs are required, which the schema already states.

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?

Despite readOnlyHint already marking this as a safe read, the description adds substantial behavioral detail: default outline behavior, omitted cfg fields, icon svgStr replacement with short references, and how references should be sent back unchanged. It also explains latestRevision.version for saves and headAnchor for publish review, which is valuable operational context beyond annotations.

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

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

The description is front-loaded with the purpose and then proceeds through output shape, icon references, layout settings, and revision semantics. It is dense and somewhat long, but the detail is relevant for a tool with non-obvious return behavior and does not read as wasteful.

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

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

An output schema exists and annotations already cover the safety profile, yet the description still supplies the key content-shape and save/publish semantics an agent needs to call and interpret this tool correctly. Nothing essential appears to be missing for a read tool of this complexity.

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

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

Schema description coverage is 100%, so the schema already documents projectId, pageId, and mode. The description explains the default outline result and what mode "full" includes, but most of that meaning is already present in the schema's mode description, so it does not add much parameter-specific value beyond the baseline.

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

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

The description gives a specific verb and resource: it gets the actual text content of a page's sections, including titles, descriptions, CTAs, images, and items. It also distinguishes the tool from at least one sibling by directing single-section reads to get_section_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?

It explicitly says to use this tool to read what is on the page before editing, and it gives a clear alternative for reading just one section via get_section_content. However, it does not explain when to choose this over other related sibling tools such as get_page or get_partial_content.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description adds genuinely useful behavioral context those annotations lack: results reflect the last Google sync and may therefore be stale relative to a live check. It doesn't say anything about latency, quota, or what happens when GSC isn't connected.

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

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

Two short sentences, zero filler, with the core purpose front-loaded and the disambiguation deferred to the second sentence. Nothing repeats the title or the schema.

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

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

For a two-required-parameter read tool with full schema coverage and no output schema, the description covers what is needed to select and invoke it correctly, including the key staleness caveat. It would be stronger if it sketched what a returned status contains or noted the GSC-connection prerequisite.

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% — both projectId and pageId are documented as UUIDs with patterns. The description adds only the implicit notion that pageId identifies 'a specific page' and doesn't explain the project/page relationship or whether a URL could be substituted. Baseline 3 applies when the schema carries the parameter burden.

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 (get) and a precise resource (Google Search Console indexing status for a specific page), with the data provenance made explicit ('as last synced from Google'). It also names inspect_url as the differing sibling, so an agent can distinguish it from both inspect_url and get_all_page_statuses without opening a schema.

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

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

The clause 'inspect_url checks a URL live' gives a clear routing rule: use this tool for the stored/synced status, inspect_url for a live check. It does not explicitly say when-not to use it, nor does it mention the related bulk sibling get_all_page_statuses, so it stops just short of full alternatives coverage.

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 read-only, non-destructive, closed-world behavior, and the description adds substantial context beyond that: the exact return fields (id, version hash, dates, isDraftHead, isPublished), the draft head's saves and headAnchor, and the five-minute save-grouping rule. This is behavior an agent could not infer from the 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?

The core purpose and ordering come first, then return-field semantics, then the cross-tool relevance, then pagination. Each sentence contributes new information with no repetition of the schema.

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

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

There is no output schema, so the description carries the burden of explaining return values, and it does so thoroughly, including field meanings and the unusual save-number grouping. Nothing essential for correctly interpreting the response is missing.

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

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

Schema description coverage is 100%, including explicit descriptions for limit and offset with defaults and bounds, so the baseline is 3. The description's 'limit and offset page through long histories' confirms intent but adds no syntax, range, or format detail the schema does not already provide.

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

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

States a specific verb and resource ('Get the revision history of a page') plus ordering ('newest first'), and names the sibling it feeds into ('revert_page_revision_to_version'). An agent can distinguish it from revert_page_revision and get_page_content without opening any schema.

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

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

Explains the key workflow condition: the save numbers returned here are what revert_page_revision_to_version takes to undo recent saves, which tells the agent when to use this tool first. It lacks explicit when-not guidance (e.g., versus get_page_content or get_all_page_statuses), but the context is clear.

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

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

Beyond the read-only annotations, the description discloses meaningful behavior: live status via publishedRevisionId, unpublished-change detection via hasUnpublishedChanges, omission of empty values, replacement of icon SVG markup with reusable short references, and the specific latestRevision fields needed by downstream save/publish tools. Nothing contradicts 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?

The purpose is front-loaded in the first sentence, followed by tightly packed but relevant details about status, output compaction, mode selection, and downstream revision fields. There is no filler, and each sentence contributes useful invocation or interpretation context.

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?

Although there is no output schema, the description explains the returned structure in enough detail for an agent to interpret outline versus full responses, including omitted fields, icon references, and revision metadata. For a read-only get tool with complete parameter coverage, it is sufficiently complete.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema by explaining the practical effect of mode: outline omits cfg and empty values and compresses icon markup, while full includes every field. ID parameters remain schema-only, which is appropriate given the existing UUID descriptions.

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

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

The description opens with a specific verb and resource: 'Get the content of a partial (header, footer, or other reusable section).' It also defines what a partial is, which distinguishes it from sibling tools like get_page_content and get_section_content without requiring the schema to be opened.

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 explains the default outline mode versus passing mode "full" for every field, and ties the returned latestRevision fields to save_partial_content and publish_partial. However, it does not explicitly name alternatives such as get_section_content or state when not to use this tool, so it stops short of full routing guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavioral context: the returned id is unique and invariant across token refresh, reconnection, and name/email changes — a non-obvious property an agent would otherwise have to discover empirically. It stops short of mentioning auth requirements or failure modes.

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

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

Two tight sentences with zero filler. The primary statement of what is returned comes first, with the id semantics as supporting detail.

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 parameters, full annotation coverage, and an output schema, nothing structural is missing. The one thing an agent could not infer — that the id is a stable key — is explicitly documented, which is exactly the gap a description needs to close for an identity 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?

The tool takes zero parameters, so the baseline is 4; there is nothing for the description to disambiguate. The description's explanation of what the returned id represents is a bonus but not required for 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 and resource: 'Return the Pixelesq account this connection is signed in as' — an agent knows immediately this is the identity/whoami call, not a data listing. It never names or contrasts a sibling (e.g. get_project, list_projects), so it falls short of full sibling differentiation.

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, when-not, or alternative is given; usage is only implied by the notion of knowing which account is signed in. The second sentence does provide strong guidance on how to use the result (the id is a stable identifier across token refresh, reconnection, and profile edits), but that is consumption guidance, not selection 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 this a safe read (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the description doesn't need to cover safety. It does add context the annotations can't: the exact shape of the returned payload and the nested path context.imageGeneration.enabled, which is a concrete behavioral detail an agent would otherwise have to discover by trial.

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 core payload description and the actionable generate_image prerequisite are front-loaded before the field enumeration. The settings enumeration is dense but each parenthetical carries real information; the only mild bloat is the long nested clause around settings and syncEnabled.

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 explaining return values, and it does so thoroughly, including a nested flag path and a cross-tool dependency. It stops short of mentioning error behavior for an invalid or unknown projectId, which keeps it at 4 rather than 5.

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 parameter and schema description coverage is 100%, so the schema fully documents projectId as a UUID. The description adds no meaning beyond that (no note on obtaining the ID, e.g. from list_projects), so it lands at 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 opens with a specific verb+resource ("Get a project's full details") and then enumerates exactly which fields come back (id, name, slug, plan, siteBaseUrl, moduleAccess, settings, brand/AI context, content counts). This clearly separates it from list_projects (which lists rather than fetches one) and from get_theme (which the description explicitly defers to for theme data).

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

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

It gives one explicit routing rule: "Check that flag before calling generate_image," and points to get_theme for the theme itself. What's missing is a when-not: nothing says to prefer list_projects when the agent lacks a projectId, so the agent must infer that from sibling names.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful behavior beyond that: results include a comparison against the previous period and are sorted most-clicks-first then most-impressions. It stops short of stating what happens when GSC is not connected or when no data exists.

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

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

A single dense sentence with the resource front-loaded and the returned dimensions trailing as a list; no filler. The enumerated output facets make it long, but each element carries information an agent would otherwise have to open the output schema to learn.

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

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

With an output schema present and annotations covering safety, the description need not explain return values, and it is adequate for calling the tool. However, in a 60+ tool surface it omits the GSC-connection precondition and project-sourcing step that would let an agent chain correctly from get_gsc_connection_status / list_projects.

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 parameters are already documented and the baseline is 3. The phrase 'change against the previous period' loosely gestures at the period parameter, but the description never mentions the period options (7/28/90 days) or the default, so it adds no real semantics 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 (Google Search Console search performance data) and enumerates exactly what is returned: totals with period-over-period change plus top queries, pages, devices and countries. This clearly distinguishes it from the broader get_site_analytics and get_ai_referral_analytics siblings without needing to name them.

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

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

Usage is only implied by the resource name — an agent infers this is the read path for GSC search metrics. There is no explicit 'use this instead of get_site_analytics when...' guidance, and no mention of the apparent prerequisite implied by the get_gsc_connection_status sibling or of where projectId comes from.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds genuinely useful behavioral detail beyond them: the return shape (uislices with ctx/cfg, empty values omitted) and the read-only nature of collectionFed paths. It stops short of describing error behavior or size limits, so not a 5.

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

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

Front-loaded with the core purpose and return shape, then the flow, then the collectionFed caveat. Mostly every sentence earns its place, though the collectionFed sentence is slightly tangential for a read tool and could be trimmed.

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

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

With no output schema, the description carries the burden of explaining return values and does so reasonably (ctx/cfg, omissions, collectionFed). A mention of pagination or failure modes is missing, but an agent has enough to call it correctly.

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

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

Schema coverage is 100%, so all three IDs are documented in the schema itself. The description only adds that sectionId may be a section id 'or logicalId' implicitly via the flow of finding it through get_page_content, which is marginal added value over the schema. Baseline 3 applies.

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

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

States a specific verb and resource ('Get a single section's full content and config from a page') and explicitly contrasts with loading the whole page and with sibling tools like get_page_content. An agent can distinguish it from get_partial_content/get_page_content 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?

Gives an explicit when-to-use ('inspect one section in isolation before editing, instead of loading the whole page') plus a concrete multi-step flow: get_page_content/list_pages to find the id, this tool to read, save_section_content to write. Alternatives and sequencing are spelled out.

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

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

Annotations already cover readOnly/safe profile; the description adds valuable behavior detail—the return shape (ctx + cfg), the expected workflow (edit values, keep structure), and how the output feeds save_page_content. It doesn't cover error cases for unknown section types, but the added context is well beyond 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?

Front-loaded with the core action and return value, then usage. Slightly repetitive in the second paragraph about replacing text values, but every sentence carries practical guidance.

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

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

The tool is simple (1 param, read-only, no output schema) and the description fully explains the return structure and how to use it. Minor gap around invalid section type behavior, but otherwise complete for the agent's needs.

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 already documents sectionType with examples, so the description adds no syntax or format detail for the single parameter. 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?

States a specific verb and resource (get default content/config structure for a section type) and clearly distinguishes itself from siblings like list_section_types and save_section_content by naming what it returns (ctx and cfg).

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

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

Explicitly states when to use it ('before creating a section') and ties it to the follow-up action (modify and pass to save_page_content), giving the agent a clear workflow.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety and scope are covered. The description adds the useful behavioral detail that each metric includes a comparison against the previous period, but says nothing about project scoping, empty-data behavior, or cost/latency, which matters for an aggregate-report call.

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

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

A single front-loaded sentence with no filler; the metric inventory is dense but each item is informative. The trailing enumeration is long but earns its place by telling the agent what it will receive.

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?

Return shape is covered by an output schema and parameters are fully documented in the schema, so the description need not repeat them. What remains missing is routing guidance relative to the sibling analytics tools, which is the main gap for an otherwise simple read 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%, including the period enum and its default, so the schema carries parameter meaning. The description never mentions the period parameter or how the comparison window derives from it, adding no meaning beyond the schema.

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

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

Specific verb and resource ('Get site traffic analytics') followed by an enumeration of the exact metrics returned, so an agent knows precisely what data comes back. It does not explicitly contrast with the nearby analytics siblings (get_ai_referral_analytics, get_search_performance), leaving that differentiation to be inferred from the metric names.

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, and no mention of alternatives. With three analytics tools in the sibling list, an agent gets no help deciding between traffic analytics, AI referral analytics, and search performance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavioral context: `variables` reflect the live site while `draftVariables` carry staged editor changes, and `hasUnpublishedDraft` signals divergence — this is not derivable from 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?

Three clauses, zero waste, front-loaded with the tool's purpose followed immediately by the semantics of the returned fields. 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?

An output schema exists, so return values need not be explained, yet the description usefully clarifies the live-vs-staged distinction, which the schema alone would not convey. Given annotations cover safety and the single param is documented, the definition is near-complete; only explicit usage routing is absent.

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

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

Only one parameter (projectId) with 100% schema description coverage, so the schema fully documents it. The description adds no parameter-level detail, which matches the baseline 3 when schema coverage is high.

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 ('Get') and resource ('the project's active theme') and even enumerates the theme's contents (colors, typography, spacing), which is more than the tautological title. It is distinguishable from siblings like update_theme or get_project, though it never explicitly contrasts with update_theme.

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: reading the current/live theme state. There is no explicit 'use this when...' guidance and no mention of update_theme as the mutation alternative or of when to consult the draft fields.

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?

Goes well beyond the annotations: the write lands in the draft, existing sections are untouched, script tags/handlers/links are refused, and the insert is rejected when lastVersion is stale. It also explains the identity model — the supplied UUID becomes logicalId while the response carries the internal id hermes stored.

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-loads the core operation before the setup workflow, which is the right order. Some material restates the schema's own field descriptions (the Uislice vs component-name note appears in both), but nearly every sentence carries non-obvious operational guidance.

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, deeply nested, five-required-parameter mutation with no output schema, the description covers sequencing, identity, refusal conditions, and Partial-vs-Uislice branching. An agent has what it needs to construct a valid call without trial and error.

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 the schema lacks: section.type is 'Uislice' vs 'Partial' while the component name belongs on uislices[0].type, Partial sections may leave uislices empty, and collectionId binds in the same step. The lastVersion parameter is explained only by reference to another tool rather than its format.

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

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

Opens with a specific verb+resource+location: 'Insert a brand-new section at a given position on a page,' and immediately clarifies scope ('added to the page's draft as one section; existing sections are not sent back and are untouched'). It does not explicitly contrast itself with save_section_content, reorder_sections, or remove_section, so an agent must infer the boundary from names 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?

Gives an explicit ordered workflow: call get_section_defaults first, assign one fresh UUID, then call insert_section with position as a zero-based index or -1 to append. It also names prerequisites (get_page_content latestRevision.version) and the conditions under which the call is refused.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds the connectivity prerequisite, which is genuinely useful operational context, but says nothing about quota consumption on the underlying GSC API or what happens when no property is connected.

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 and the returned facets, with the constraint as a follow-up. Nothing is padded, though the parenthetical could be tightened into the main clause.

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

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

For a two-parameter read tool with no output schema, the description covers what is inspected, the returned facets, and the eligibility constraint. The main remaining gap is failure behavior when the property is not connected, which is minor given the annotation 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%, so the baseline is 3, but the description adds a constraint the schema lacks: the URL must fall inside the connected property, which materially narrows what values are valid. It still adds no guidance on the projectId parameter beyond what the schema already says.

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 (inspect) and resource (a URL) and even enumerates the facets returned: indexing, crawl, and robots.txt status. It does not, however, distinguish itself from the closely related sibling get_page_index_status, leaving the agent to infer which one answers a given indexing question.

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 supplies a real precondition — the URL must belong to the project's connected Search Console property — which tells the agent when the tool will succeed. It stops short of naming alternatives (e.g., get_page_index_status vs this tool) or stating when not to reach for it.

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

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

Annotations already cover safety (readOnly, non-destructive, closed-world), and the description adds genuinely useful behavior: newest-first ordering, a hard cap of 10 results in search mode, and that search overrides the other filters. It does not describe pagination totals or result shape, but the key behavioral quirks are disclosed.

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?

Compact and front-loaded, with the core action and ordering stated first and the search caveat second. The dense semicolon-chained phrasing is slightly harder to scan than a short bulleted form, but nothing is wasted.

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

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

For a read-only listing tool with no output schema, the description covers ordering, default type, filter/search interplay and the search result cap. Return-value shape and total-count behavior are left implicit, which is acceptable given the absence of an output schema but leaves 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 67% and the description fills gaps: it clarifies the type values including that a MIME type such as image/webp maps to its kind, and states the precedence relationship between search and the other parameters. limit/offset remain undocumented beyond the schema, so not a full 5.

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

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

States a specific verb and resource ('List the media assets in a project's library') plus an ordering guarantee ('newest first') and default scope (images by default). An agent can distinguish this from search_stock_images and list_entries 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?

Clearly explains the branch between filter-mode and search-mode, including that limit, offset and tags are ignored during a search. It does not name sibling alternatives (e.g. search_stock_images for non-project imagery), so it stops short of full alternative routing.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuine value by disclosing the return payload (id, name, slug, hasPages, updatedAt, entry count, fields) and the non-obvious semantics of the built-in name/slug types.

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 return-shape detail is front-loaded and each sentence is informative: payload fields, then a caveat about built-in types, then the sibling pointer. Slightly dense with enumerated attributes but no wasted sentences.

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, and the description compensates by describing the return fields and their meanings. For a one-parameter read-only list tool, an agent has everything needed to call it and interpret the result.

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 carries its meaning. The description adds nothing about projectId, which is acceptable only because coverage is complete.

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 with scope ('List all content collections in a project') and enumerates the returned attributes, which no sibling list tool duplicates. It is clearly separable from get_collection, which is named as the single-collection variant.

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 closing sentence routes the agent to get_collection when the full field schema (labels, help text, reference targets, type config) is needed, implying this lightweight tool is for overview listing. No explicit exclusions, but the alternative and its selection condition are stated.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description adds value beyond that by disclosing the exact return shape (id, hostname, verified, misconfigured, updatedAt), which is meaningful for a read tool with no output schema; only pagination/ordering behavior is left unstated.

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

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

Three short sentences, front-loaded with what the tool does, followed by the return shape and the motivating use case. No filler, no repetition of the title, and each clause carries information an agent can act on.

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

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

For a single-parameter read tool with no output schema, the essentials are covered: scope, return fields, and purpose. It is nearly complete, with only minor gaps around result ordering and whether the list is ever paginated or truncated for projects with many domains.

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 parameter (projectId) and schema description coverage is 100%, so the schema already documents it completely. The description implies the domains are scoped to the supplied project but adds no format, default, or constraint detail beyond the schema, which is the correct baseline of 3.

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

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

The description gives a specific verb and resource ("Lists a project's custom domains") and even enumerates the returned fields, so an agent knows exactly what it gets. It does not need to distinguish itself from a competing domain sibling because none exists in the tool list, but it also makes no explicit routing statement, which is the only thing separating it from 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?

"Use to check whether a domain is verified or misconfigured" gives a concrete purpose-driven use case rather than leaving intent implied. It stops short of stating when-not-to-use it or naming an alternative (e.g., a hypothetical get_domain or verify_domain tool), so it lands at clear-context-without-exclusions.

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

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

Annotations already declare readOnlyHint, openWorldHint=false, and destructiveHint=false, so the safety profile is fully covered. The description adds only the collection scoping and says nothing about pagination behavior, ordering, or what the listing returns beyond what the schema and annotations already convey.

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

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

The description is a single, front-loaded sentence with no wasted words. Its brevity is appropriate, though the minimal content is under-specification rather than elegant 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 list tool with a fully documented schema and annotations covering the safety profile, the description is minimally adequate. It does not clarify whether results are paginated, how they are ordered, or what an entry listing contains, which would help an agent call it correctly without inspecting the schema.

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

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

Schema description coverage is 100%, so projectId, collectionId, limit, offset, and search are all documented in the schema. The description adds no parameter-level meaning beyond the collection scope, 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 clear verb and resource (list entries) and adds meaningful scope: entries are listed within a specific collection. It is distinguishable from get_entry (singular) and list_collections (different resource), though it does not explicitly name 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?

The description gives no guidance on when to use this tool versus alternatives such as get_entry, search_content, or list_collections. Usage is only implied by the word 'List', and there are no exclusions or prerequisites.

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

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

Annotations already cover read-only/non-destructive, and the description adds real value on top: it discloses that the returned schema is abbreviated (and where to get the full one) and that limit defaults to 20. It does not mention ordering guarantees for the listed forms, a small remaining gap.

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, then return shape, then the get_form caveat and the use case. The response-shape block is long but earns its place because there is no output schema; the rest is tight.

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 correctly supplies the return structure including pagination fields, which is what an agent needs. Missing offset/paging guidance for multi-page iteration is the only notable omission for a 3-param list tool.

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

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

Schema coverage is 33% — only projectId is documented in the schema. The description restates the default limit of 20 (already in the schema default) but says nothing about offset, pagination semantics, or the max of 100, so it only partially compensates for the coverage gap.

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 with scope ("Lists forms in a project") and explicitly contrasts with the sibling get_form for full schemas. An agent can pick between list_forms and get_form without opening either schema.

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

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

"Use to find a formId" gives a concrete selection criterion, and the get_form pointer names the alternative for the deep-schema case. No explicit when-not-to-use statement, but the routing is clear.

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

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

Annotations already indicate a safe, closed-world read operation. The description adds useful behavioral context: it names supported filters, default and maximum limits, and describes the returned result and pagination shape.

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

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

The description is front-loaded with purpose, then filters, then return shape and pagination defaults. It is fairly dense but each part is relevant; the return-shape detail is somewhat redundant given the output schema.

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

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

With annotations covering safety, 100% schema coverage, and an output schema, the description supplies the remaining practical context: filter options, pagination defaults, return shape, and the workflow reason to call it before editing or publishing.

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 all five parameters. The description reinforces status filter values and pagination limits, but adds little syntax or meaning beyond the schema.

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

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

The description states a specific verb and resource: 'Lists pages in a project.' It distinguishes the tool from get_page by describing list filtering behavior and from create/update siblings by being a read/list operation.

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

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

It gives clear usage context: 'Call before editing or publishing to find the page id.' This helps an agent know when to use it. It does not explicitly exclude alternatives like search_content or get_all_page_statuses, so it falls short of a 5.

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

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

Annotations already cover readOnly/destructive/openWorld, so the bar is lower, and the description still adds real value by decoding the status fields an agent will see (publishedRevisionId set = live, hasUnpublishedChanges = draft edits not live). With no output schema, this return-semantics context is the main behavioral contribution.

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

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

Three sentences, front-loaded with the purpose and definition before the field semantics and pagination note. Tight overall, though the pagination clause largely echoes the schema defaults.

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 read-only, three-parameter list tool with full schema coverage and annotations, the description supplies the needed domain framing (what a partial is, what the status fields mean). Only the ordering/filtering behavior and the full shape of returned records are left implicit.

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

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

Schema coverage is 100%, so limit, offset, and projectId are fully documented in the schema itself. The description only restates the limit ceiling and that offset pages, adding no syntax or semantics beyond the structured fields. 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?

"List the partials ... in a project" is a specific verb plus resource, and the parenthetical defines what a partial is (reusable headers/footers), which an agent may not know. It does not contrast itself with get_partial_content or list_pages, so the sibling 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?

Usage is implied: enumerate partials for a given projectId. There is no explicit when-to-use, when-not-to-use, or pointer to get_partial_content for fetching a single partial's body, which is the most likely confusion given the sibling set.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered without the description. The description only adds the account-scoping implied by "your"; it says nothing about pagination, result ordering, or volume limits.

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

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

A single six-word sentence with zero filler, and the resource being listed is front-loaded. Nothing in it could be trimmed without losing meaning.

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 trivial zero-parameter read tool covered by annotations, the description is adequate but thin. With no output schema, it could still say what a project record contains or whether the result set is paginated, leaving a small but real gap.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate. Baseline 4 applies for a parameterless tool with a fully covered (albeit 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?

States a specific verb ("List") and resource ("Pixelesq projects") with the qualifier "your," so the purpose is unambiguous. It does not, however, distinguish itself from the sibling get_project or explain how the list differs from a filtered lookup.

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?

"List all your ... projects" implies retrieval of the full set with no filtering, which implicitly contrasts with get_project, but no explicit when-to-use guidance or alternatives are named. Usage must be inferred from the naming convention shared with list_pages/list_entries.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The word 'all' implies an unfiltered full listing, which is a small useful signal, but the description says nothing about pagination, ordering, or what a redirect record contains.

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 short sentence, front-loaded with verb and resource, with no filler. Nothing to trim and nothing 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 simple single-parameter read tool with annotations covering safety, the description is nearly sufficient. However, with no output schema, the agent learns nothing about the shape of returned redirects or whether results are paginated, leaving a modest gap.

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

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

There is a single parameter (projectId) and schema description coverage is 100%, so the schema already documents it fully. The description adds no extra meaning such as whether an invalid or missing project returns an error versus an empty list, 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 ('List') and resource ('URL redirects in a project'), which clearly separates it from the many other list_* siblings that target pages, entries, assets, and forms. It stops short of distinguishing it from the redirect mutation siblings (create/update/delete_redirect) or noting scope like pagination.

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 call this versus inspecting redirects another way, no mention of pagination behavior, sorting, or limits. The agent gets a clear read verb but nothing about context or alternatives.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the bar is lower; the description still adds value by enumerating exactly what each entry returns (name, description, group, use cases, content fields, preview image URL) and by explaining the split between the text listing and the richer structured result. That textual-vs-structured distinction is behavioral context not present in 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?

Front-loaded with purpose and return contents, which is good, but the group list is repeated verbatim from the schema's parameter description and the return-field enumeration partly duplicates the existing output schema. Two sentences earn their place; the rest is restatement.

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

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

An output schema exists so return values need no deeper explanation, and the one optional parameter is fully covered in both schema and description. For a simple read-only list tool this is essentially complete, with only the missing sibling routing keeping it below 5.

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 documents the single group parameter, so baseline would be 3. The description earns more by adding a non-schema fact — that pricing sections live under the form group — which changes how an agent would set the filter.

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

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

States a specific verb and resource ("List available section types for building pages") and implicitly scopes it to page construction, which separates it from get_section_content or insert_section. It never names a sibling outright, so differentiation is inferential rather than explicit.

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?

"Use the optional group filter to narrow results" gives usage for the parameter and "for building pages" hints at the workflow, but there is no statement of when to pick this over get_section_defaults or get_section_content, nor any when-not guidance. Usage is implied rather than directed.

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

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

Beyond the destructiveHint/openWorldHint annotations, the description discloses the real behavioral traits: optimistic-concurrency refusal if the draft changed, the side effect of moving the page to a pending address in the same step, automatic redirect creation for previously-public pages, and a partial-success warning when the entry-page template has no sections. It does not explain what a failed or partial publish leaves behind for a destructiveHint-true tool, which keeps it from a 5.

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

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

The core action and the review-binding contract come first, followed by the pending-address and redirect cases, then the warning behavior — a sensible front-loaded ordering. It is dense rather than bloated, though the warning sentence is long and could be trimmed without losing meaning.

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 return-value burden and does mention the warning field in the result, which is the one non-obvious output condition. What the result contains otherwise (published revision, final address) is left unstated, a minor gap for a mutation tool whose annotations already flag it as destructive.

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 genuine meaning the schema does not: expectedAddress is tied to draftSlug from get_entry and to a refusal-on-change contract, and expectedHeadAnchor is tied to latestRevision.headAnchor. That connects the parameters into a review-consistency workflow rather than restating field docs.

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

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

Opens with a specific verb and resource ('Publish a collection entry to make it live'), and the 'collection entry' framing cleanly separates it from publish_page and publish_partial in the sibling list. An agent knows what object it acts on and what the end state is 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 spells out preconditions for each optional parameter: pass expectedRevisionId/expectedHeadAnchor from get_entry to bind the publish to what was reviewed, pass draftSlug as expectedAddress when a pending address exists, and note that a first publish never needs a redirect. The refusal conditions act as explicit when/when-not guidance rather than leaving inference to the agent.

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 real context beyond annotations: the publish is conditionally refused when a newer draft exists or the draft was edited, and the rationale (user re-reviews) is given. It does not describe what happens to the previously published version or what auth level is needed, which the destructiveHint annotation leaves implicit.

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

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

Three sentences, front-loaded with the action, then the parameter contract, then the failure behavior. No filler and nothing repeated from the schema.

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

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

For a 5-parameter mutating tool with no output schema, the concurrency contract is fully covered, which is the main correctness risk. Missing only the success-side outcome (page goes live, prior published revision superseded) and any permission notes.

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 actionable semantics the schema does not: pass the same latestRevision.id as both revisionId and expectedRevisionId, and name the tools that supply headAnchor. That cross-parameter relationship is genuinely additive.

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 (publish a page) and immediately defines the outcome (make it live). An agent can distinguish it from publish_entry, publish_partial, and unpublish_page without opening a schema.

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

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

Explains the precondition clearly: revisionId must be the draft the user reviewed, sourced from get_page, get_page_content, or a save result. It does not state when to prefer publish_page over reverting or updating a revision first, but the review-then-publish workflow is explicit enough to guide invocation.

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

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

The annotations already mark this as destructive and open-world, and the description adds meaningful behavioral context beyond them: it refuses non-newest revisions and refuses when the draft changed since it was read, preventing accidental publication of stale content. That is valuable concurrency-safety disclosure.

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

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

The description is front-loaded with the action and effect, followed by the required revision provenance and the refusal behavior. It is dense but every sentence contributes to correct invocation.

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 publish operation with no output schema, the description covers the key preconditions, expected parameter sources, and failure modes. It does not describe the exact post-publish response, but the absence of an output schema makes that less critical.

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, but the description adds useful semantics by mapping revisionId to latestRevision.id, expectedRevisionId to the head revision the user reviewed, and expectedHeadAnchor to a value read from get_partial_content or a save result. This goes beyond the schema’s short field descriptions.

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

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

The description uses the specific verb "publish" with the resource "partial (header, footer, or reusable section)" and states the effect: making it live across all pages. This clearly distinguishes it from sibling tools like publish_page and publish_entry by 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?

It gives concrete usage instructions: revisionId must be the reviewed draft, expectedRevisionId should match latestRevision.id, and expectedHeadAnchor comes from get_partial_content or a save result. It also states the refusal conditions, though it does not explicitly compare against publish_page or other alternatives.

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

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

Adds substantial context beyond the destructiveHint annotation: the DELETE_SECTION operation on the draft under a revision lock, draft forking from the published head, and the fact that a missing section is an error with or without a key. This is exactly the mutation behavior an agent needs to know.

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 preservation guarantee, then layers in locking, id handling, and idempotency. Dense but every sentence carries necessary information; minor overlapping of idempotency/error detail keeps it from a perfect 5.

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, no-output-schema mutation tool, the description covers mutation mechanics, scope of effect, id semantics, idempotent retry, and error behavior. An agent has everything needed to call it correctly.

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

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

Despite 100% schema coverage, the description adds real meaning: sectionId accepts either id or logicalId with the crucial publish-survival distinction, and idempotencyKey semantics (replay on lost answer, use a new key after errors) are spelled out. This goes well beyond the schema text.

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 ('Remove a section from a page by id') and immediately clarifies preserved scope ('All other sections are preserved'). An agent can distinguish this from delete_page or other destructive 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?

Explains that sectionId comes from get_page_content and that logicalId survives publishing while id does not, which guides correct invocation. It doesn't explicitly name an alternative tool or a 'when-not-to-use' case, so it falls just short of the top mark.

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?

Goes beyond the annotations by disclosing that content is preserved and only positions change, and — importantly — that the reorder is refused if the page changed since lastVersion was read, revealing optimistic concurrency behavior not encoded anywhere else. The destructiveHint=true annotation is implicitly contextualized rather than contradicted; only the response/error shape is left unexplained.

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 action, followed by the input contract and the failure condition. No filler and 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?

For a mutating tool with no output schema and annotations that only declare the safety profile, the description supplies the essential behavioral facts: preserved content, all-or-nothing input list, and version-gated rejection. It stops short of describing the success response or what the agent should do on a version conflict (e.g., re-read via get_page), which would complete the picture.

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

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

Schema coverage is 100%, so baseline would be 3, but the description adds real semantics: orderedSectionIds must cover every existing section exactly once (schema says this too, but the description reinforces it prominently), and lastVersion is explained as the freshness guard whose staleness causes rejection. That last point materially extends the schema's terse 'current revision version'.

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

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

States a specific verb and resource ('Reorder the sections on a page') and immediately clarifies that only positions change, which cleanly separates it from insert_section, remove_section, and save_section_content. An agent can distinguish it from siblings without opening a schema.

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

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

Gives the key usage constraint ('Provide the full ordered list of section IDs — every existing section must be included exactly once') and the precondition that lastVersion must be current. It does not explicitly name sibling alternatives for adding/removing sections, but the full-list contract effectively steers an agent away from partial updates.

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?

Goes well beyond the annotations: it discloses that the source revision is not modified, the published revision is unaffected until publish, and every unpublished edit in the current draft is left behind — that last point is the real consequence behind destructiveHint=true and it is stated plainly. It does not mention permission requirements or failure modes, so 4 rather than 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?

Front-loaded with the core action and its non-obvious effect, then prerequisites, then the alternative. Every sentence carries distinct information — the mechanism, the immutability guarantees, the data-loss warning, and the routing hint — 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?

For a two-parameter, no-output-schema mutation guarded by a destructiveHint, the description supplies everything needed: what is created, what is preserved, what is lost, and how to locate the revisionId. No meaningful gap remains for an agent to call it safely.

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 projectId and revisionId are already documented, and the schema even hints at the source ('from get_page_revisions or page.publishedRevisionId'). The description reinforces that provenance but adds no format or constraint detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource ('Revert a page's draft to a previous revision') and immediately clarifies the mechanism — a NEW draft revision is created rather than the old one being restored. It explicitly distinguishes itself from both get_page_revisions and revert_page_revision_to_version, so an agent can route correctly without opening any schema.

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

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

Names the prerequisite lookup tool ('Use get_page_revisions to find the revision to revert to') with a concrete example, and names the alternative ('use revert_page_revision_to_version instead') together with the exact condition that selects it — undoing only the last few saves of the current draft. When/when-not is fully spelled out.

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

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

Goes well beyond the destructiveHint=true annotation by disclosing that deleted saves are unrecoverable, that the operation is refused unless the revision is the current draft and the anchor still matches (optimistic concurrency), and that edits within ~5 minutes collapse into one save number. This is rich behavioral context an agent needs before a destructive call.

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

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

Front-loaded with the core operation, then prerequisites, edge cases, refusal conditions, and the destructive warning. Dense but every sentence carries information; the only cost is that the paragraph runs long enough that the WARNING could be surfaced earlier.

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 no output schema, it covers the workflow prerequisite, anchor-based concurrency check, save-number edge case, and irreversibility. Nothing material is missing for an agent to call it correctly.

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

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

Schema coverage is 100%, but the description still adds meaning: it maps revisionId to the isDraftHead entry, explains that saveNumber=0 keeps none of the draft's saves, and clarifies that expectedHeadAnchor is the stale-read guard. It does not explain the 'version' alias parameter, a minor omission.

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 ('Undo recent saves on a page's current draft') and defines the exact operation: keep saves up to saveNumber, delete all newer ones. The draft-only scope and save-number semantics distinguish it from the sibling revert_page_revision without needing to open either schema.

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

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

Explicitly tells the agent to read get_page_revisions first and pass the head revision id, save number, and headAnchor. It also enumerates the refusal conditions (revision must be the current draft, headAnchor must be unchanged, a newer save must exist), so when-not-to-use is covered as clearly as when-to-use.

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 destructiveHint=true already present, the description adds substantial behavioral context: omitted fields are preserved, null clears a field, arrays are replaced wholesale, reference IDs must exist, list fields must be arrays, and invalid date formats are refused. It also explains optimistic concurrency via lastVersion, which no annotation conveys.

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 merge semantics before the exhaustive field-type rules, and the bullets make the density navigable. The icon mapping block is long and niche, but it is tied to a genuinely complex content type rather than being filler.

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

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

Covers prerequisites, merge behavior, and content value shapes thoroughly for a nested, polymorphic mutation tool with no output schema. It stops short of saying what the call returns and what specifically happens on a lastVersion conflict, which an agent would benefit from knowing.

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 already 100%, but the description goes well beyond it by giving per-field-type value shapes (text, html, number, checkbox/boolean, date and its config.time-dependent format, image/media, icon, reference, related) and list-field semantics. lastVersion also gets runtime meaning ('from get_entry latestRevision.version').

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

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

States a specific verb and resource ('Save/update the content of a collection entry') and immediately distinguishes itself from update_entry by declaring that name/slug keys are refused and must be changed via update_entry. An agent can separate this from save_page_content or save_section_content on resource 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?

Explicitly directs the agent to call get_collection before composing content and get_entry for lastVersion, and routes rename/address changes to update_entry. The merge-only nature of the call is stated up front, so when to use and when not to use it are both inferable without opening a schema.

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?

Goes well beyond the destructiveHint annotation by explaining the replacement semantics, which omissions cause removal, how cfg/ctx merge against server state, which changes are refused rather than silently dropped, and which recovery tool to use after a bad save. This is exactly the behavioral context needed for a destructive save tool.

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

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

The description is front-loaded and logically organized, but it is lengthy and includes a long list of common component types that is helpful yet not strictly essential. For a complex destructive save operation the length is mostly justified, though some sections could be tighter.

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 complex nested schema, destructive behavior, and lack of an output schema, the description is complete: it covers prerequisites, merge semantics, matching rules, refusal cases, alternatives, and post-failure recovery. An agent has enough information to call the tool correctly.

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

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

Although schema coverage is already 100%, the description adds crucial semantic meaning: section/uisclice structure, matching by id or logicalId, RFC 7396 merge behavior, array replacement rules, and the requirement that lastVersion come from get_page_content. These details materially affect correct parameter construction.

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?

Starts with a specific verb and resource ('Save sections to a page') and immediately clarifies the exact operation: replacing the page's section list while merging cfg/ctx within matching sections. It also distinguishes page-level section work from sibling operations like insert_section, remove_section, save_section_content, and save_partial_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?

Explicitly says when section-level add/remove/reorder should happen here and names alternatives for adjacent operations: save_partial_content for embedded header/footer content, remove_section then insert_section for component type changes, update_entry/save_entry_content for collection items, and get_section_defaults for new sections.

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 the description earns that hint by spelling out exactly what is destroyed: omitted sections are removed explicitly on every project, and arrays (ctas, items, media, icons, menu, social, legal) are REPLACED wholesale. It further discloses merge semantics (RFC 7396), explicit refusals (component type changes, stale logicalIds, script tags), and concurrency 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?

Front-loaded with the core operation and replace semantics, then proceeds to merge rules, type guidance, refusal cases, and the version requirement in a logical order. The bullet list for merge semantics is dense but every line carries non-obvious behavioral information; only the prose paragraph on refusals is slightly verbose.

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 destructive, nested mutation with no output schema: it covers prerequisites, replacement scope, per-field merge behavior, refusal conditions, concurrency, and the returned latestRevision.headAnchor needed for publish_partial. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds substantial meaning beyond field types: merge behavior for cfg and ctx, the null-clears rule, array replacement, the distinction between section.type ('Uislice'/'Partial') and the component name on uislices[0].type, and matching by id or logicalId. This is exactly the kind of semantics the schema cannot express.

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 the specific verb and resource ('Save sections to a partial (header, footer, or other reusable section)') and immediately distinguishes it from save_page_content and save_section_content via the 'partial' scoping. An agent can identify the target and operation without reading 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?

Specifies prerequisites very clearly: lastVersion from get_partial_content, defaults from get_section_defaults, types from list_section_types, and the follow-up publish_partial. It also gives a valid alternative flow when a component type change is refused ('save the partial without it, then with the new section'). It doesn't explicitly say when to use save_page_content or save_section_content instead, but the scoping makes the boundary clear.

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