Blogmaker

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

Annotations cover the mutation/safety profile (readOnly=false, destructive=false, idempotent=false), and the description adds genuinely new context: the returned preview_url is anonymously readable by anyone with the link and expires in 30 minutes, plus preview_expires_at. That security-relevant disclosure is exactly what 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?

Four short sentences, front-loaded with the core action, then the authoring choice, then the non-publishing guarantee, then the return values. No redundancy and every sentence carries distinct information.

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

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

With no output schema, the description responsibly documents the return payload (preview_url, preview_expires_at) and its lifetime, and covers the main authoring mode choice. Minor gaps remain around the idempotency_key and publish-consent behavior, but the core call-and-interpret loop is covered.

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

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

Schema coverage is low (33%) over a nested schema, but the schema itself carries strong inline descriptions for html, slug, publish, elements, featured_image_url and idempotency_key. The description only adds the html-vs-elements mutual-exclusion hint; it says nothing about kind, idempotency_key usage, or publish consent, leaving compensation incomplete.

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 precise verb+resource ('Create a post or page draft') and immediately clarifies the draft-vs-publish distinction, which separates it from siblings like publish_content and update_content without requiring the agent 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?

Gives actionable guidance on when to use html versus ordered native elements, and states that creating a draft does not publish it. It stops short of explicitly naming alternatives (publish_content, update_content) or listing exclusions, so it is clear context rather than full when/when-not routing.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false, so the description needn't restate safety. But it adds nothing beyond them: no note on duplicate-slug handling, required permissions, or whether the taxonomy is immediately visible.

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 waste, but it is thin to the point of under-specification rather than efficient. There is room for a short clause on prerequisites or slug behavior.

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 non-idempotent mutation tool with 0% schema coverage and no output schema, the description does far too little. An agent must infer parameter semantics and failure modes from nothing.

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 0% and three of four properties have empty descriptions. The description mentions no parameters at all, leaving name, slug, and description semantics (format, constraints, whether slug is auto-derived) entirely undocumented; only the kind enum self-documents.

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 (create) and resource (category or tag) and disambiguates the two entity kinds, matching the title. It distinguishes itself from list_taxonomy by verb alone, though it doesn't explicitly reference it.

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

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

No guidance on when to use this versus list_taxonomy or how it relates to content creation (e.g., that a taxonomy must exist before assigning it). No prerequisites, no exclusions, no mention of behavior when the slug already exists.

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

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

The annotations already declare this as read-only, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description usefully adds that it operates on published documents and returns a citation URL, but it does not add deeper behavioral context such as error behavior or auth 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?

The description is a single front-loaded sentence with no wasted words. It conveys purpose, required input source, and included output in one pass.

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

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

For a simple one-parameter read-only fetch, the description plus annotations and schema provide enough to call it correctly. It could say more about what the fetched document contains, but the core behavior and citation URL are clear.

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

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

With 100% schema description coverage, the schema already defines the single ID parameter as a posts/slug or pages/slug ID returned by search. The description reinforces that the ID comes from search but adds no syntax or format detail beyond the schema.

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

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

The description states a specific verb (Fetch) and resource (published document), and adds the key scope that the ID comes from search and that a citation URL is included. It does not explicitly name or distinguish itself from nearby siblings like get_published or search, which keeps 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?

The phrase 'by its ID from search' gives clear context for when this tool applies: after a search has returned an ID. It does not state exclusions or point to alternatives, so it falls short of explicit when-not 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?

Adds substantial context beyond the readOnly/idempotent annotations: an account-plan precondition that can cause failure, the implicit default range and timezone, the caveat that filtered reports exclude imported historical aggregates, and the note that visitor identity is privacy-safe and rotates daily. These are non-obvious data-scope and error traits an agent could not infer from structured 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?

Four sentences, all load-bearing, opening with the resource and scope before defaults, preconditions, and data caveats. No restatement of the title or name.

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

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

With no output schema, the description usefully enumerates the report dimensions returned, and it covers default range, plan requirement, and data exclusions. It leaves out return shape/aggregation details (e.g. how trend series are bucketed, whether results are paginated or capped), which matters for a multi-dimension analytics call.

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 compensates by supplying the 30-day default and UTC default that the schema does not state, plus concrete usage for filters.path. It does not explain the semantics of the remaining exact-match filters (e.g. country needing a two-letter code, which the schema does cover) or how multiple filters combine.

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

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

Specific verb + resource ('Read ... analytics for the connected blog') plus an enumeration of exactly what is retrievable: traffic totals, previous-period comparisons, hourly/daily trends, top pages, sources, channels, devices, locations, interactions. This distinguishes it cleanly from the real-time sibling get_current_visitors and from content-listing 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?

Gives concrete selection guidance within the tool ('Use filters.path for a single post or page') and states the default scope (30 days UTC) and the eligibility precondition (requires an eligible API plan). It stops short of naming an alternative tool or an explicit when-not-to-use condition, so it is clear context without full 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 readOnly, idempotent, closed-world, non-destructive, so the safety profile is fully covered without the description. The description adds nothing beyond that — no statement of what 'details' contains, whether it is scoped to the connected blog only, or what happens if no blog 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?

A single short sentence, which is appropriately sized for a zero-parameter tool. However, it largely restates the title ('Read connected blog'), so the sentence does not fully earn its place.

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

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

With no output schema and no description of the returned fields, an agent has no way to know what this 'details' object contains versus get_blog_settings or get_analytics. For a zero-arg read tool the annotation burden is light, but the return-value ambiguity is a 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 no parameters, so there is nothing for the description to explain; baseline 4 applies. The description does not introduce or misdescribe any inputs.

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 verb (read) and resource (connected blog), so the basic action is clear. But 'details' is undefined, and with siblings like get_blog_settings, get_analytics, and get_design the agent cannot tell what this tool returns that those do not.

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, and no mention of the obvious alternatives (get_blog_settings for settings, get_analytics for stats). The agent must infer the routing from sibling names alone.

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

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

Annotations already establish readOnly, idempotent, and closed-world behavior, so the safety profile is covered. The description adds the notable fact that a 'revision' is returned, but does not explain what that revision is for (presumably optimistic concurrency on update_blog_settings) or what the settings contain.

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

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

A single sentence with no filler, and the key information (settings + revision) is front-loaded. Nothing here could be cut without losing signal.

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

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

For a zero-parameter read with no output schema, the description tells the agent what comes back (settings and revision) and why it matters (before mutating). Only the meaning of 'revision' is left implicit.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate beyond confirming it operates on the single connected blog. Baseline 4 applies.

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

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

The description names a specific verb and resource ('Read the connected blog settings') plus an extra returned value ('revision'), so the purpose is unambiguous. It does not distinguish itself from the sibling get_blog, which an agent could reasonably confuse it with.

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

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

'Read ... before changing them' implies a read-before-write workflow, which hints at when to call it. However, it never names update_blog_settings as the follow-up tool, nor states any exclusion versus get_blog.

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

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

Annotations already cover readOnly/idempotent/non-destructive, yet the description adds real value: preview_url is a private sharing link, valid until preview_expires_at, 30 minutes after issue, and re-retrieval is required for a new one. Missing are failure modes (expired link, missing ID, permission requirements on drafts), 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?

Four short sentences, front-loaded with what is returned, then the security/expiry caveat, then the non-publishing scope. No filler and nothing repeated from the schema or annotations.

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

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

With no output schema, the description does the necessary work by naming the returned payload fields and explaining preview link lifecycle. It stops short of stating permission requirements or error behavior, which matter for reading an unpublished draft.

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

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

Schema coverage is only 50% — the 'id' parameter is documented but 'kind' (enum posts/pages) carries no description. The description never mentions either parameter, so nothing compensates for the coverage gap beyond the self-explanatory enum values.

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

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

States a specific verb ('Read') and resource ('a complete editor draft and its revision'), then enumerates exactly what comes back: native elements, taxonomy, authors, preview_url. 'Draft' and the closing 'Does not publish.' separate it from get_published/list_published 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?

Gives clear operating context: retrieve again for a fresh link, and it explicitly excludes publishing ('Does not publish'), which routes the agent to publish_content. It does not explicitly name list_content vs get_content as the selection rule, so it falls short of full when/when-not 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 cover the safety profile (readOnly, idempotent, non-destructive), so the description adds real value beyond them by disclosing the five-minute activity window and the API plan requirement, neither of which is in structured fields. It stops short of describing the response shape or any rate 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?

Three short sentences, front-loaded with the core operation and scope, then filters, then the plan gate. No wasted text.

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

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

For a single-filter read tool with full annotations, the description covers scope, filter behavior, and an access prerequisite. The return value (a visitor count) is implied but not stated, which is a minor gap given there is no output schema.

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

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

The schema describes each nested filter property as an 'exact-match filter,' and the description reinforces this by saying it supports the same exact-match filters as get_analytics. That cross-reference is helpful context but doesn't enumerate or add syntax detail, so it sits at the baseline for schema-documented params.

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 a precise scope: 'Read the number of visitors active on the connected blog within the last five minutes.' This clearly separates it from historical analytics siblings, though it names get_analytics only to borrow its filter semantics rather than to draw a purpose distinction.

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

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

Use is implied by the real-time five-minute window, and the 'Requires an eligible API plan' prerequisite is useful. However, it never states when to choose this over get_analytics or which plan tiers qualify, leaving selection logic to inference.

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

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

Beyond the annotations, it explains paging defaults, omitted settings semantics, custom CSS chunking, revision consistency, theme_has_native_defaults behavior, device override precedence, all_pages scope, page/post independence, and the Advanced plan requirement. These are substantial behavioral details for a read-only 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 core purpose is front-loaded, and the dense details are largely relevant to correct invocation. It is a long paragraph, but most sentences earn their place by preventing pagination, revision, or custom CSS mistakes.

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 six-parameter read tool with no output schema, the description is complete enough: it explains returned settings semantics, pagination, custom CSS handling, revision use, device precedence, all_pages behavior, and plan requirements. An agent should be able to call it correctly without additional context.

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 useful meaning: query helps discover areas/labels/keys, offset must reuse filters and revision, and section=custom_css changes paging behavior and must be read chunk-by-chunk before replacement. It does not fully document every parameter nuance 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: read Design Studio settings, supported rules, draft/published values, and exact revision. It is clearly a read-only paged design-settings tool, distinguishable from mutation siblings like update_design and publish_design.

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

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

It gives clear operational guidance: use query to discover controls, follow next_offset with the same filters and revision for more, and request section=custom_css before replacing CSS. It lacks explicit when-not-to-use guidance or named alternatives such as get_blog_settings.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds two useful behavioral facts: the content is publicly visible only and the response includes rendered HTML. It does not mention not-found or unpublished 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?

A single front-loaded sentence with no filler. It is efficient, though its brevity is part of why parameter and usage details are absent.

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

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

For a tool with an output format not formalized in an output schema, the description mentions rendered HTML but omits how kind/slug resolve, what happens for unpublished or missing content, and when to prefer the sibling fetch tools. Given 0% schema coverage, this leaves real gaps.

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

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

Schema description coverage is 0% and the slug field has an empty description, so the description needs to compensate but does not. It never mentions 'kind' (posts vs pages) or 'slug', leaving both parameters unexplained beyond their names and enum.

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

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

States a specific verb (Read) and resource (a publicly visible published snapshot), which is discernible from siblings like list_published or get_content. It does not explicitly differentiate itself from near-neighbors such as get_content or render_published, so it stays below a 5.

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

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

No guidance on when to use this versus get_content, list_published, or render_published, all of which appear in the sibling list and sound closely related. The agent must infer selection from names alone.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds one genuine behavioral fact — only confirmed and visible authors are returned — but says nothing about pagination, ordering, or result 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?

A single clause with zero filler, and the scope qualifier is front-loaded where it matters most.

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?

A simple, annotation-covered read tool, so not much is demanded, but the description omits that results are paginated via a cursor and says nothing about what an author entry contains, which an agent selecting this tool would want.

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

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

Schema coverage is 50%: 'cursor' is documented in-schema while 'limit' has only an integer range. The description adds no parameter meaning at all — it never hints at pagination or a page size, leaving the undocumented limit to be inferred.

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 authors) plus a meaningful scope qualifier — 'confirmed visible' — which tells the agent these are assignable authors rather than all users. Purpose is clear without needing the schema 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?

The clause 'for assigning content' implies the use case (picking an author when creating or updating content), but there is no explicit when-to-use/when-not statement and no named alternative among the many sibling content tools.

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

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

Annotations already establish that this is a read-only, idempotent, non-destructive, closed-world operation. The description adds concrete behavioral context beyond annotations: preview_url links are anonymous and expire after 30 minutes, and an eligible API plan is 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?

The description is two compact sentences with no filler. The core action is front-loaded, followed by the useful expiration and plan caveats.

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?

This is a read-only list tool, so annotations cover the safety profile, and no output schema exists. Still, with low parameter description coverage, the description should say more about filtering, pagination, and limit behavior to fully equip an agent calling 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 description coverage is only 25%, with just the cursor parameter documented. The description mentions posts/pages and draft/published scope, which loosely maps to kind and status, but it does not explain limit bounds/defaults, cursor pagination behavior, or the required kind parameter's role.

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: listing draft and published editor posts or pages. It distinguishes the scope from published-only siblings implicitly by including drafts, but does not explicitly name alternatives such as list_published or get_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?

Usage is implied by the draft/published list scope, and the description notes an eligible API plan requirement. However, it does not say when to choose this tool over siblings like list_published, search, or get_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, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered externally. The description contributes the content-visibility filter, which is genuinely beyond the annotations, but says nothing about ordering, default page size, or how cursor exhaustion behaves.

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 capability front-loaded and the scope constraint immediately after. Nothing is redundant with the title or annotations.

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

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

No output schema exists, so the description could reasonably describe the shape of returned items or pagination behavior, and it does neither. For a simple read-only list tool this is adequate but leaves the agent guessing about return contents.

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

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

Schema description coverage is only 33%: cursor is documented in-schema and kind is self-describing via its enum, but limit has no stated default or meaning beyond the 1-100 bounds. The description adds nothing about any of the three parameters, so it fails to compensate 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 ("List ... published posts or pages") plus a visibility qualifier ("publicly visible"), which is enough to tell it apart from generic list_content. It stops short of naming the sibling it differs from, so the differentiation relies on inference.

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 exclusion rule ("Private, subscriber-only and scheduled content is excluded") tells an agent when this is the right tool in a scoping sense, but there is no explicit statement of when to prefer it over list_content or get_published, and no prerequisites.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint false and openWorldHint false, so the safety profile is fully covered. The description only adds the scope qualifier 'connected blog'; it says nothing about pagination behavior, ordering, or size of results, which pagination-bearing read tools usually need.

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 the verb, zero filler. Brevity is fine for a simple list tool, though the space saved is not reinvested in any of the missing semantics.

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 carry result-shape expectations, yet it never says whether paginated results return a cursor/next_cursor, what fields a category or tag includes, or how ordering works. For a 3-parameter paginated list tool this leaves meaningful gaps.

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

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

Schema description coverage is 33% — only 'cursor' is documented in the schema. The description does not explain that 'kind' selects between two distinct resource types, nor that 'limit' is a page size bounded at 100; with low coverage it should have compensated and does not.

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 (blog categories or tags), and the 'kind' enum makes the two modes explicit. It is clear it differs from write-side siblings like create_taxonomy, but it never names or differentiates itself from list_authors, list_content, or list_published beyond the resource noun.

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 choose this over create_taxonomy or other list_* tools, and no prerequisites noted (e.g. that a blog must be connected). Usage is only implied by the phrase 'connected blog categories or tags'.

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, readOnlyHint=false and idempotentHint=false, so safety is largely covered. The description's confirmation requirement adds genuine context consistent with that profile. It still omits what publishing actually causes (content goes live publicly, visible to visitors) and what happens on a revision conflict, which is the most consequential behavior here.

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 constraint front-loaded next to the purpose. Slightly under-specified rather than padded, but the sizing is appropriate for a simple mutation.

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 should describe the return or the resulting state, and it does neither. For a destructive, non-idempotent publish operation with an undocumented idempotency_key and kind parameter, an agent can call it but not predict the outcome or recovery path.

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

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

Schema description coverage is only 50%: id and revision are well documented in the schema, but kind has no description and idempotency_key has an empty description despite idempotentHint=false — a notable gap for a retryable-write scenario. The description adds nothing about any parameter, and "current draft" gives no hint that kind distinguishes posts from pages.

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 (publish) and resource (the draft to the public blog), which cleanly separates it from siblings like update_content, publish_design and unpublish_content. Minor imprecision: it says "the current draft" while the tool actually takes an explicit id/kind/revision, so an agent could misread the targeting.

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 gating condition: call only when the user explicitly asks to publish. That is real when-to-use guidance and doubles as a when-not-to-use signal. It does not reference the obvious counterpart unpublish_content, so the agent must infer the reverse operation.

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

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

Annotations already declare destructiveHint=true and non-idempotent, but the description adds genuinely new behavioral context: it clarifies what is and is not affected ('Preserves other pending Studio changes') and the blocking state for theme switches. It does not address reversibility/undo or what the response contains, which keeps it below 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?

Five short sentences, front-loaded with the action and gating requirement, then prerequisites, then scope caveats. No filler and no repetition of the title or annotations.

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

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

For a destructive one-parameter mutation with no output schema, the description covers intent gating, prerequisite reads, exact-revision sourcing, and scope of effects — everything needed to call it safely. Only a note on what the publish returns or confirms would close the gap.

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

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

Schema coverage is 100% with a single 'revision' parameter, so the baseline would be 3. The description earns above baseline by specifying provenance and strictness: the revision must come from get_design and be used exactly, which is meaning the schema's 'Exact quoted design revision' does not convey on its own.

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 ('Make ... live') and precise resource scope: supported native settings plus custom CSS from the current Design Studio draft, including native edits saved in the UI. An agent can tell this apart from update_design (draft edits) and publish_content (content publishing) 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 an explicit gating condition ('Requires explicit user intent to publish'), an ordered prerequisite workflow ('Read get_design and review the draft first; use its exact revision'), and an exclusion path: a pending theme switch must be published in Design Studio first. This is when/when-not/alternatives coverage in compressed form.

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, idempotent and non-destructive behavior, so the bar is lower; the description still adds real value by disclosing what is NOT returned (no theme, header, footer, styles, scripts) and that private, scheduled and subscriber-only content is excluded. It does not mention auth requirements 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?

Four tight sentences, each carrying distinct information: purpose, return contents, omissions, and exclusions. Front-loaded with the core action and 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?

With no output schema, the description usefully enumerates the response (snippets, footnotes, summary, TOC, featured image, SEO metadata) and exclusions, which is most of what an agent needs. The remaining gap is the unexplained slug parameter.

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 0% and the slug description is empty, so the description is the only source of param meaning. 'Post or page' loosely maps to the kind enum, but neither the enum values nor what slug identifies (and its format/source) is explained.

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 (render) and resource (public post or page content) and specifies the output form (an HTML fragment for a customer-owned layout). It does not explicitly differentiate itself from the close sibling get_published, so the agent must infer the boundary.

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

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

'For a customer-owned layout' implies the decoupled/headless use case, but no explicit when-to-use, when-not, or named alternative (e.g. get_published vs render_published) is given. Usage is implied rather than 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 cover read-only, idempotent, non-destructive, and closed-world. The description adds scope facts the annotations don't carry: only publicly visible content is searched, only titles and descriptions are matched (not body text), and the return is citable references. What is missing is result limits, ranking, or matching semantics.

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

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

A single sentence that front-loads the action and scope with no filler. Every clause (public visibility, titles and descriptions, citable references) carries information.

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

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

For a one-parameter read-only tool with full safety annotations and no output schema, the description covers what is searched, what is visible, and what comes back. Only result-set behavior (limits, ordering) is left unstated, which is minor here.

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 0%, so the description must compensate. It does so partially by indicating the query is matched against post and page titles and descriptions, which is real semantics absent from the schema, but it says nothing about length limits, exact-phrase vs token matching, or expected query form.

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 searches 'publicly visible post and page titles and descriptions in the connected blog.' That distinguishes it from the name alone and from write siblings, but it never explicitly contrasts with the browse-style siblings (list_published, get_published, fetch), which an agent might otherwise pick.

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 — keyword lookup across published content — but no sentence says when to use this instead of list_published or get_content, and no prerequisites are stated. The selection signal must be inferred from the verb 'search'.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is known; the description adds two things annotations cannot convey — that the editor draft survives (bounding the destruction) and that user confirmation is required. It omits what happens to the public URL after removal and how a revision mismatch fails, 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 tight sentences with zero filler; the behavioral consequence (draft retained) and the safety precondition both appear up front.

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, 3-required-param tool with no output schema, the description covers effect, retained state, and confirmation requirement, and annotations cover reversibility/idempotency. Missing detail is mainly post-conditions for the public URL and revision-mismatch 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 coverage is 67%: id and revision are documented in the schema (with the concurrency rationale for revision), but the 'kind' enum has no description in either place, and the description adds no parameter meaning. Baseline 3 is appropriate given the schema carries most of 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 ('Remove a published post or page from the public blog') plus the differentiating outcome ('retaining its editor draft'), which separates it from update_content and publish_content. It does not name a sibling explicitly, so it falls just short of the 5 bar.

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?

'Requires explicit user intent' gives a clear gating condition for when this tool is appropriate, which is meaningful for a destructive operation. It stops short of naming alternatives (e.g., use update_content to edit instead of unpublishing) or stating when not to call 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?

Goes well beyond the annotations (destructiveHint=true, idempotentHint=false) by disclosing optimistic-concurrency behavior via the revision, permission requirements, and partial-update semantics ('Omitted fields are preserved; supplied menus replace that menu'). It also flags that header/footer HTML is executed as custom code, a non-obvious risk. It does not state reversibility/undo, which is the only 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?

Five short sentences, front-loaded with the action and the user-consent constraint, then the precondition, then the field semantics. No filler and nothing buried at the end.

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, non-idempotent mutation with a deep nested settings object and no output schema, the description covers the essentials: consent, permissions, revision, merge-vs-replace, and image sourcing. It leaves the response behavior and recovery from a stale revision unspecified.

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

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

Schema description coverage is only 50%, and the description compensates partly: it explains that revision must come from get_blog_settings, that omitted fields persist, and that menus are wholesale replacements. Those replacement rules are also repeated in the schema for the menu fields, and the many scalar settings (timezone, copyright, banner fields, toggles) get no added meaning from the description.

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

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

Specific verb+resource ('Change blog settings ... on the live blog') with scope made explicit ('immediately', 'live'). It is clearly distinguishable from the read-only sibling get_blog_settings, which it names as a prerequisite.

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

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

States the gating condition ('only when requested by the user'), the required permission set, the mandatory workflow ('Read get_blog_settings first and supply its revision'), and routes image sourcing to upload_asset. When-to-use and prerequisites are both covered 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?

Adds real context beyond annotations: the draft-isolation rule for published posts, a preview_url valid 30 minutes, preview_expires_at, and the security warning that anyone with the link can read the draft until expiry. It does not restate the destructiveHint=true implication (that omitted elements are removed), which is left to the schema.

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

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

Three tight sentences; the mutation effect is front-loaded, and the preview token warning follows. 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?

With no output schema, the description usefully explains the return values (preview_url, preview_expires_at) and their lifetime. Minor gaps: it doesn't warn that the update replaces content (omitted elements removed) or mention permission requirements, but the core call path is covered.

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

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

Schema description coverage is 50%; the description only reinforces the 'revision' parameter's purpose, while the content fields (html vs elements, slug rules, featured_image_url) are documented in the schema, not the description. Adequate, but no extra semantics added.

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 ('Update editor content') plus the optimistic-concurrency requirement ('with its current revision'), which separates it from create_content and publish_content. It does not explicitly name those siblings, so differentiation is implied 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?

'Changes to a published post remain drafts until explicitly published' implicitly routes the agent to publish_content afterwards, but there is no explicit when-to-use/when-not statement or mention of create_content vs update_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?

The annotations already mark the tool as destructive and non-idempotent, but the description adds substantial context: omitted controls are preserved, custom_css replaces the entire draft, reset_only settings are retired, device reset affects inheritance, and the operation does not publish. This is rich guidance beyond the annotations and is consistent with them.

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 dense but appropriately front-loaded: purpose first, then prerequisite, then behavioral rules. Most sentences earn their place, though the long paragraph could be more scannable if broken into bullets.

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

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

For a complex, destructive draft-editing tool with no output schema, the description covers the key behavioral constraints an agent needs: prerequisites, draft-only scope, non-publishing behavior, device inheritance, reset semantics, and replacement behavior for custom_css. It is complete enough to select and invoke 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?

With only 50% schema description coverage, the description meaningfully compensates: it explains that values are strings including numbers, how device targeting works, the two reset forms and inheritance behavior, and that custom_css is a full replacement. It does not cover every schema detail such as the 250-item limit, but it adds strong semantic value where it matters.

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: saving native Design Studio changes as a draft. It immediately distinguishes the tool from publishing with 'Does not publish,' so an agent can separate it from publish_design 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 gives explicit usage guidance: use only when requested, read get_design first for supported keys/ranges/choices/revision, and use existing editors for theme switching, legacy palettes, branding, and page-specific overrides. These are clear when-to-use, prerequisites, and exclusions.

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

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

Adds real constraints beyond annotations: accepted formats, 10 MB, 32 megapixels, 8000 px per dimension, and the important clarification that uploading does not mutate a post. Annotations already cover safety (readOnly=false, destructive=false, idempotent=false, openWorld=true), so the description's job is narrower and largely done; it stops short of stating failure/duplicate-name behavior or permission requirements.

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

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

Three dense sentences: capability and constraints first, parameter selection second, return value and scope limitation last. No filler or redundancy.

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

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

No output schema exists yet the description explains the return value (url) and its intended consumers. Combined with the format and size limits and the explicit scope statement, an agent has everything needed to call this correctly on the first try.

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 requires nothing (required: []) and only half the properties carry descriptions, so the description carries the load: it declares that exactly one of file/source_url must be supplied, and the size/format limits apply to both paths. This is information the schema alone would not convey.

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 ('Upload one JPEG, PNG, GIF or WebP image') and immediately scopes the destination ('to the connected blog'). Explicitly distinguishes its scope from sibling mutation tools by noting 'Uploading alone does not edit or publish a post.'

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 exact selection rule between the two parameters ('exactly one is required') and downstream usage ('Returns url for content.featured_image_url, gallery images or HTML'). Also names the exclusion that prevents confusion with create_content/publish_content.

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