JustBlogged

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

Beyond the annotations, the description discloses two meaningful behavioral details: the subdomain is auto-generated from the name, and specific auth credentials are required. These add practical context that helps an agent anticipate setup and side effects, though it does not describe every possible failure mode.

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

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

The description is two sentences with no filler: it states the action, the key auto-generation behavior, and the auth requirement. Every sentence contributes actionable information, and the most important details are front-loaded.

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 3-parameter creation tool with an output schema and annotations, the description is complete. It covers the core purpose, the auto-generated subdomain behavior, and auth requirements. Nothing essential about how to invoke 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?

The input schema already covers all three parameters with descriptions, so the baseline is 3. The description adds extra meaning to the 'name' parameter by stating that the subdomain is auto-generated from it, which goes beyond the schema's simple 'Blog name' description.

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

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

The description opens with a specific verb and resource, 'Create a new blog,' making the tool's purpose immediately clear. The blog resource is distinct from sibling create_* tools like create_post and create_collection, and there is no ambiguity about what is being created.

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 clearly indicates this tool creates a new blog and provides an important usage prerequisite: it requires account-level OAuth or a user-scoped API key. It does not explicitly name alternatives or state when not to use it, but the context is clear enough for an agent to select it for creating a 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?

The description's 'Create a new collection' is consistent with annotations indicating a non-read-only, non-idempotent, non-destructive write operation. It adds little beyond the annotation profile, such as duplicate behavior, validation failures, or side effects, but it does not contradict the annotations.

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

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

The description is a single sentence with no filler, front-loading the core action and the key fields. Every word earns its place.

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

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

The schema fully documents all parameters, including the required blogId and its discovery path, annotations describe the mutation profile, and an output schema exists. The only minor gap is that blogId is absent from the natural-language description, but the schema compensates completely.

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

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

Schema description coverage is 100%, and the schema already provides good semantic detail, including the blogId hint to use list_blogs. The description merely repeats name, slug, and description names while omitting blogId, so it adds no meaningful semantic value beyond the schema.

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

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

The description states a specific verb and resource ('Create a new collection') and lists the main fields (name, slug, optional description), distinguishing it from update_collection and delete_collection. It is clear but omits blogId from the prose, and it largely restates the title with a bit more detail.

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, no exclusions, and no mention of prerequisites beyond what appears in the schema. There is no explicit routing to sibling tools like update_collection or list_collections.

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 safety profile is known. The description adds no behavioral context beyond restating the operation—no mention of side effects, resulting page state, auto-generation of slug, or interaction with the publishing workflow. It doesn't contradict the annotations, but also adds little beyond 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?

One concise sentence with no filler, front-loading the verb and resource and enumerating the key fields. It is efficient, though it doesn't use the space to add routing or behavior 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 straightforward create operation, the description is minimally adequate given the rich schema and output schema. However, it lacks explicit guidance on when to select this tool over create_post, and it doesn't clarify the meaning of 'static page' or the prerequisite blogId discovery step, leaving some 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 100%, so the baseline is 3. The description simply lists parameter names already documented in the schema and adds no extra meaning, inter-parameter relationships, or format 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?

The description states a specific verb ('Create') and resource ('static page'), and enumerates the key fields (title, HTML body, metadata, slug, image, status). The phrase 'static page' helps distinguish it from sibling tools like create_post and create_collection, though it doesn't name them explicitly.

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

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

The description implies a use case through 'static page' and the HTML body field, but provides no explicit guidance on when to use this tool versus alternatives like create_post or create_redirect. No exclusions or conditions are given, leaving selection to inference.

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

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

Annotations already cover readOnlyHint=false, idempotentHint=false, and destructiveHint=false. The description adds modest context by emphasizing 'new' and mentioning publishing options, which implies side effects and status choices, but it does not disclose specifics such as permissions for author assignment or the default draft behavior beyond 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?

A single efficient sentence front-loads the core action ('Create a new blog post') and then concisely lists the relevant aspects. No filler or repetitive prose.

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

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

With a complete input schema, an output schema, and annotations covering safety/idempotency, the description is mostly sufficient for an agent to invoke this tool correctly. A small gap is the absence of a pointer to alternative creation tools, but that is more of a usage-guidance issue than a completeness issue for this resource.

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 every parameter's meaning and constraints. The description's field list adds no new semantic detail beyond restating the parameter names.

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: 'Create a new blog post', and enumerates the involved fields (title, HTML content, author, collection, tags, metadata, slug, image, publishing options). This clearly distinguishes it from sibling tools like create_page and create_collection.

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 no explicit when-to-use or when-not-to-use guidance and names no alternatives. The agent must infer from the name and schema that this is for posts, not pages, collections, or redirects.

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 write operation (readOnlyHint=false) and non-idempotent (idempotentHint=false). The description adds the auth requirement, which is useful behavioral context, but does not disclose other behaviors such as conflict handling or whether an existing redirect is overwritten. With annotations covering the safety profile, this is adequate but not exceptional.

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 sentences with zero filler. The core action is front-loaded, and the auth note follows without bloating the text. Every word earns its place.

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

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

For a tool with five parameters (three required) and an output schema, the description covers the essential purpose and auth prerequisite. The schema handles parameter documentation and the output schema covers return values, so the description is complete enough without over-explaining.

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

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

Schema description coverage is 100%, so all five parameters are already thoroughly documented in the schema. The description adds no additional parameter-level meaning beyond what the schema provides, so the baseline of 3 applies.

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

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

The description states a specific verb ('Create') and resource ('redirect for a blog'), clearly distinguishing it from siblings like update_redirect, delete_redirect, and list_redirects. The phrase is precise and leaves no ambiguity about the action.

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

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

The description provides clear context that this tool is for creating redirects, and adds a prerequisite (owner/admin access via OAuth or user-scoped API key). However, it does not explicitly state when not to use it or mention alternative tools, so it falls 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 indicate destructiveHint=true and readOnlyHint=false, and the description adds meaningful context by stating that approving a staged update to published content applies that revision. This clarifies the nontrivial consequence of the decision. It does not, however, explain what happens when changes are requested, though that is less impactful.

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

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

Two sentences with no filler; the core decision action is stated first, followed by the most important side effect. Every sentence adds value and the structure is ideal for quick agent scanning.

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 a full schema and output schema available, the description covers the essential decision options and the publish effect. It does not detail the outcome of requesting changes, but the enum values and comment requirement in the schema cover most of what an agent needs. The definition is sufficiently complete for correct invocation.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description's mention of 'request changes' aligns with the comment requirement but adds no semantic detail beyond the schema, which is the baseline expectation.

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

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

The description clearly identifies the action as deciding on a pending content review via 'approve' or 'request changes', and explicitly describes the real-world consequence of approval ('applies that revision'). This distinguishes it from sibling tools like submit_content_review or list_content_reviews, which serve different stages of the review lifecycle.

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

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

The phrase 'pending content review' implies this tool is used when a review is awaiting a decision, but it does not explicitly state when to prefer this over submit_content_review or other review-related tools. No exclusions or alternatives are named, so the guidance is only implied.

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

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

Beyond the annotations, which already declare destructiveHint=true and idempotentHint=false, the description adds meaningful behavioral context: an ownership permission requirement and an important side effect (active subscriptions are cancelled automatically). This helps the agent anticipate consequences beyond a simple delete 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?

Three short sentences deliver the essential information without wasted words. The primary action is stated first, followed by the permission constraint and the most consequential side effect.

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 delete operation with a full output schema and robust annotations, the description covers the key non-obvious details: ownership requirement and automatic subscription cancellation. Nothing critical is missing for an agent to invoke this safely and correctly.

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

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

Schema description coverage is 100% for the single blogId parameter, and the description's 'by ID' matches the schema. The description does not add additional parameter-level detail beyond what the schema already provides, 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 ('Delete a blog by ID') and clearly distinguishes this tool from sibling delete operations for other resource types like delete_collection and delete_page. The action and target are unambiguous.

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

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

Clearly establishes a prerequisite ('Only the blog owner can delete') and identifies the operation's scope. It does not explicitly discuss when not to use the tool or enumerate alternatives, but the blog-specific naming and context make the intended use clear.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the destructive nature is covered. The description adds the reassignment behavior, which is useful. However, it does not disclose what happens to the collection's posts if reassign_to is not provided—whether they are deleted, orphaned, or handled otherwise. This is a significant behavioral gap for a destructive operation.

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, focused sentence that fronts the primary action and includes the optional reassignment. No filler or redundant phrases. It is concise and easily parseable by an agent.

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 description covers the core operation but omits critical details about post handling when reassign_to is absent. An agent may not know the consequences of deleting without reassignment, which is essential for a destructive operation. While an output schema exists, it does not clarify this behavior. The description is adequate for simple cases but falls short on edge-case transparency.

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%, with each parameter (blogId, collectionId, reassign_to) having a brief description. The description repeats the reassignment concept but does not add meaning beyond the schema's parameter descriptions. For example, blogId's guidance to use list_blogs is already in the schema. Baseline 3 is appropriate since the schema handles parameter documentation.

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

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

Description clearly states the action (delete), the resource (collection), and the optional reassignment behavior. It distinguishes from sibling tools like delete_post and delete_page by specifying the collection scope. The verb+resource is specific and unambiguous.

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

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

The description implies usage for deleting collections but does not explicitly state when to use this tool versus alternatives or when to provide the reassign_to parameter. It lacks guidance on when not to use it (e.g., if posts should be kept) and does not mention prerequisites or side effects. Some context is given via the optional reassignment, but no clear decision framework is provided.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the destructive nature is well covered. The description adds no additional behavioral context such as irreversibility or impact on related content, but it does not contradict annotations either. It is consistent but not enriching.

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 concise sentence, front-loading the action and resource without wasted words. It is appropriately sized for a straightforward delete operation.

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 delete tool with two required parameters, full schema documentation, destructive annotations, and an output schema, the description is largely adequate. The only gap is the absence of any usage guidance, but this is minor for such a direct operation.

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

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

Schema description coverage is 100%, with both blogId and pageId fully documented (blogId includes a hint to use list_blogs). The description adds no further parameter semantics, relying entirely on the schema, which is acceptable given full coverage.

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

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

The description states exactly what the tool does: delete a static page, identified by ID. This is a specific verb and resource, and the 'by ID' clarifies the identification mechanism. It clearly distinguishes from sibling delete tools like delete_post and delete_collection.

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, nor any prerequisites. The schema hints at using list_blogs for blogId, but the description itself is silent on when or how to use the tool effectively.

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

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

The description matches the destructiveHint=true annotation and adds no contradictory information. However, it does not add contextual behavioral detail beyond what the annotations already communicate, such as permanence, side effects, 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 description is a single concise sentence that front-loads the core operation. Every word is necessary and no filler or repetition is present.

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

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

For a simple two-parameter delete operation, the description is adequate when combined with the full schema and annotations. The destructive behavior is covered by annotations and an output schema exists, so no critical information is missing, though slightly more context about irreversibility could help.

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

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

The input schema provides 100% parameter coverage, including the helpful note to use list_blogs for blogId discovery. The description adds no additional parameter-level meaning beyond what the schema already states.

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

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

The description uses a specific verb and resource ('Delete a blog post by ID') that clearly identifies the operation. It naturally distinguishes this tool from sibling delete tools like delete_page and delete_collection by naming the target resource explicitly.

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

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

The intended use is implied by the tool name and description, but there is no explicit guidance on when to prefer this tool over sibling delete tools. No alternatives or exclusion conditions are mentioned.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, so the delete behavior is covered. The description adds valuable authorization context by requiring owner or admin access via account-level OAuth or user-scoped API key. No contradiction with annotations 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?

The description is two short sentences with no filler. The core action is front-loaded, followed by the essential authorization requirement. Every sentence earns its place.

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

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

For a simple delete-by-ID operation with two well-documented parameters, an output schema, and annotations covering destructiveness and idempotency, the description is complete. It provides the action, target, required identifiers, and access conditions.

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

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

Schema coverage is 100%, with both blogId and redirectId documented. The tool description itself adds no parameter-level detail, but the schema already provides enough meaning, including a helpful hint to use list_blogs for blogId discovery.

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 action ('Delete') and resource ('a redirect by ID'). This unambiguously distinguishes it from sibling tools like create_redirect, update_redirect, and list_redirects.

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

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

The description implies when to use the tool: when deleting a specific redirect by ID. It also provides access prerequisites, but it does not explicitly contrast with alternatives or mention any conditions that would make another tool more appropriate.

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

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

The description aligns with the destructiveHint annotation and confirms that the action removes a blog tag. It adds no extra behavioral context such as permanence, cascading effects, or permission requirements, but it is consistent and sufficient for a simple delete operation.

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 efficient sentence containing the verb, target resource, and action qualifier. Every word earns its place, and no unnecessary detail is included.

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

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

For a simple two-parameter delete operation, the description, input schema, and annotations together provide everything needed. The schema documents both required parameters, the detection annotation covers safety, and an output schema exists.

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

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

Schema description coverage is 100%, with both tagId and blogId documented. The description's 'by ID' phrasing adds no meaningful semantic information beyond what the schema already provides, 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 uses a specific verb ('Delete') with a clear resource ('blog tag') and the selection mechanism ('by ID'). It is unambiguous and immediately distinguishable from sibling delete_* tools targeting other resources like posts or collections.

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 explicit guidance about when to use this tool versus alternatives such as update_tag or list_tags. Usage is only implied by the verb and resource name, with no exclusions or routing advice.

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 carry destructiveHint=true and readOnlyHint=false, so the destructive nature is known. The description adds genuinely useful context beyond annotations: the Pro subscription requirement and the built-in file limitation. This helps the agent anticipate access and applicability constraints.

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 only three short sentences, with the core action first and supporting constraints following. There is no redundant wording or repetition of schema or annotation details.

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

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

For a low-complexity tool with two well-documented parameters, a destructive annotation, an output schema, and two meaningful usage constraints in the description, nothing essential is missing. An agent has enough information 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?

Schema description coverage is 100%, and both parameters already have clear descriptions: blogId points to list_blogs and file_path is described as relative to theme root. The tool description adds no further parameter-level meaning, so the baseline 3 is appropriate.

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

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

The description uses a specific verb and resource: 'Delete a custom theme file from a blog.' It also distinguishes the tool's scope by noting it cannot delete built-in-only files, which separates it clearly from generic delete operations and from theme-management 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 provides clear applicability context: it applies to custom theme files, requires a Pro subscription, and excludes built-in-only files. It does not explicitly name an alternative tool such as update_theme_file or list_theme_files, so it falls just 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, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds that the response includes settings (subdomain, domain, logo, metadata), but discloses nothing about not-found behavior, authentication, or other operational traits. With annotation coverage, this is 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 sentence that front-loads the operation and resource, then lists notable fields. There is zero redundancy, and every word contributes to the agent's understanding.

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, idempotent single-getter with one self-describing parameter, rich annotations, and an output schema, the description is fully sufficient. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100% and fully documents the only parameter (blogId: string, minLength 1). The description merely restates 'by ID' without adding format, source, or usage details, so the baseline of 3 is appropriate.

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

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

States a specific verb ('Get') and resource ('a single blog by ID'), and enumerates key return fields (settings like subdomain, domain, logo, metadata). This distinguishes it from list_blogs (multiple blogs) and get_blog_metadata (metadata only), which is clear 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?

Makes it clear this tool is for fetching one blog record by ID, implying use when you already have a blogId and need the full record. It does not explicitly name alternatives or exclusion cases, but the 'single blog by ID' framing provides sufficient context versus listing tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds useful scoping context by clarifying what is not returned (themeSettings values), but does not disclose further behavioral details such as error cases or authorization needs. This adds some value but not rich 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?

Two short sentences with no filler. The core purpose is stated first, and the scope exclusion is added immediately after, making it easy for an agent to parse the essential information quickly.

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

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

With a single well-documented parameter, an output schema present, and annotations covering the read-only and idempotent behavior, the description is sufficient. It also adds the key exclusion (themeSettings values) that prevents confusion with sibling tools. Nothing critical is missing for correct invocation.

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

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

Schema description coverage is 100%, and the only parameter (blogId) is fully described in the schema as 'Blog ID.' The description does not add any additional parameter-level meaning beyond what the schema already provides, 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 (Get), resource (custom metadata for a blog), and gives concrete examples (SEO fields, themeId). Explicitly distinguishes itself from theme settings by noting 'Does not include themeSettings values,' which helps an agent separate it from get_theme_settings and get_blog.

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 makes clear it is for blog metadata and excludes themeSettings values, which implicitly routes agents away from get_theme_settings. However, it does not explicitly name an alternative or state a when-not-to-use condition, so some inference is required.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds behavioral value by stating the response is a 'complete content snapshot' of the revision, indicating that the full saved content is returned.

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, well-structured sentence that immediately states the action, target, and key detail. No redundant words or 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?

Given the output schema, 100% parameter coverage, and annotations indicating a safe read-only operation, the description is sufficient for an agent to select and invoke the tool correctly. Nothing essential 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%, with each parameter already documented, including revisionId sourced from list_content_revisions. The description does not add parameter-level details, so the baseline 3 is appropriate.

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

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

The description clearly states a specific verb ('Get'), resource ('one saved post or page revision'), and scope ('including its complete content snapshot'). It distinguishes this from the sibling list_content_revisions by emphasizing 'one saved' revision with full 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?

The description implies the tool is for retrieving a specific saved revision, but it does not explicitly state when to prefer this over get_post/get_page for current content or list_content_revisions for revision lists. Usage context is clear but alternatives are not discussed.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior, so the description only needs to add context beyond that. It adds the selection rule of 'newest saved revision' and 'latest review,' but says nothing about empty results or edge cases. This is acceptable but minimal.

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 wasted words. The action 'Get the latest review' comes first, and the revision qualifier is compact and necessary.

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 lookup, the description, schema, and output schema together give an agent enough to call it correctly. The main gap is lack of explicit guidance distinguishing it from sibling review/revision tools, though the risk is low.

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

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

Input schema coverage is 100%, so the schema already documents all parameters. The description does not add additional parameter-level detail beyond mapping contentType to 'post or page' and contentId to the revision target. 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 precise verb-resource pair: fetches the latest review for the newest saved revision of a post or page. The 'newest saved revision' qualifier distinguishes it from list_content_reviews and get_content_revision 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?

The description implies when to use it (when you want the review on the newest saved revision) but does not explicitly name alternatives or exclusion conditions. For example, it never says to use list_content_reviews for a broader view or get_content_revision for a specific revision.

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, idempotent, non-destructive behavior, so the description does not need to repeat that. It adds the 'static page' and 'single' scope, but offers no additional behavioral context such as error cases or auth requirements; output schema mitigates return-format concerns.

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. Every word earns its place, and it conveys the essential operation immediately.

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

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

For a simple read-only retrieval tool with full schema coverage, helpful annotations, and an output schema, this description is sufficient. An agent has everything needed to invoke it correctly.

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

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

Schema coverage is 100%, with both blogId and pageId documented. The description adds no extra parameter meaning beyond 'by ID,' so the baseline of 3 is appropriate.

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

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

The description 'Get a single static page by ID' names a specific verb, resource, and access pattern. 'Static' usefully distinguishes this from content-review and post retrieval tools, so an agent can identify the correct sibling without inspecting 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?

The usage context is implied: use when you already have a blogId and pageId and need one page. However, it does not explicitly contrast with list-based tools such as list_pages or mention any exclusions/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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds no behavioral details beyond 'Get' and does not describe what happens for a nonexistent post, but this is a standard read operation with output schema available.

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

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

A single, front-loaded sentence with no filler or redundancy. Every word contributes to the tool's 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 simple get-by-ID tool with two documented parameters, an output schema, and read-only/idempotent annotations, the description is functionally complete. It could optionally point to list_posts for discovering post IDs, but that is not essential for correct invocation.

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

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

Schema description coverage is 100%, with blogId and postId already documented, including a pointer to list_blogs for blogId. The description's 'by ID' adds no parameter meaning beyond what the schema provides, 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?

The description states a specific verb ('Get'), a specific resource ('a single blog post'), and the selection mechanism ('by ID'). This clearly distinguishes it from sibling tools like list_posts, create_post, and delete_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?

The phrase 'by ID' implies this tool is for retrieving one known post, but the description does not explicitly say when to prefer it over list_posts or how to discover a postId. Usage context is only implied, not 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 behavior. The description adds valuable context beyond annotations: a read falls back to the active built-in theme when no custom copy exists, which affects what content is returned.

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 tight sentences, front-loads the core read operation and example, and then adds the fallback behavior. Every sentence earns its place with no redundancy.

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

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

For a simple read tool with full schema coverage, an output schema, and safety annotations, the description is complete enough. It covers the primary action and the important fallback behavior, so an agent has what it needs 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 description coverage is 100%, so both parameters are fully documented in the schema. The description only restates the path idea with an example and adds no format or semantic detail beyond what the schema provides, making the baseline 3 appropriate.

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

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

The description states a specific verb (Read), resource (theme file), and path-based lookup with a concrete example (layouts/theme.liquid). It clearly distinguishes this read operation from sibling write/list operations like update_theme_file and list_theme_files.

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 explicit when-to-use guidance, no alternatives such as list_theme_files for discovery, and no prerequisites beyond what the schema already states. The fallback behavior is useful but does not tell an agent when to choose or avoid 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 cover read-only/idempotent/non-destructive behavior. The description adds useful context beyond those flags: the result depends on the blog's active theme, and the call returns both the settings schema and current values. No contradictions.

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

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

One short sentence front-loads the verb, resource, and active-theme scope. Every phrase adds information and 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 simple, one-parameter, read-only tool with an output schema and robust annotations, the description supplies all needed context: what it returns, the active-theme dependency, and how to find blogId. No relevant invocation details are 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?

With only one parameter and 100% schema description coverage, the schema fully documents blogId and even supplies the list_blogs discovery hint. The description adds no parameter-specific semantics beyond tying the value to the blog's active theme, 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 the exact operation ('Get') and object ('theme settings schema and current values') and scopes it to 'a blog's active theme,' distinguishing it from theme-file tools and update_theme_settings.

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

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

The read-only retrieval intent is clear and the schema hints to use list_blogs for blogId, but the description does not explicitly say when to prefer this over update_theme_settings or get_theme_file. Usage context 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 declare readOnlyHint, idempotentHint, and destructiveHint, so safety behavior is covered. The description adds context beyond annotations by scoping to 'built-in themes' and noting that it reports the currently active theme, which is useful behavioral information.

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 names the verb, the resource, the scope, and a key output characteristic in a compact and readable way.

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 low complexity (one required parameter), strong annotations, and the presence of an output schema, the description fully equips an agent to select and invoke the tool correctly. No critical operational gaps remain.

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 has 100% coverage for the single blogId parameter and even includes a helpful cross-reference to list_blogs. 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 uses a specific verb ('List') and a specific resource ('built-in themes available for a blog'), and it adds the active-theme insight, which clarifies the tool's exact responsibility. This distinguishes it from siblings like list_theme_files and switch_theme without requiring schema inspection.

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 makes the read-only use case clear: enumerate available themes or check which theme is active. It does not explicitly name alternatives or say when not to use it, but the 'available for a blog' scope prevents confusion with theme-file or settings tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds functional context that listed members are author-eligible, but it does not disclose additional behavioral details such as pagination, auth requirements, or filter semantics. No contradiction with annotations.

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

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

Two sentences with no wasted words; the core purpose is front-loaded in the first sentence, and the actionable usage follows directly in the second.

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 list tool with an output schema, the description is fully sufficient. It states the scope of results, how the results should be used, and the required input is self-evident from the schema. Nothing an agent needs to call it correctly is missing.

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

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

The only parameter, blogId, is fully described in the schema as 'Blog ID,' giving 100% schema coverage. The description adds no further parameter-level detail, which is acceptable given the high coverage baseline.

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

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

The description states a specific verb and resource ('List blog members') and immediately scopes it to 'who can be assigned as post authors,' which distinguishes it from other list_* tools. It also names the downstream use of the result (member id as authorId), making the tool's purpose unmistakable.

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 second sentence tells the agent exactly when to use this tool: to obtain an authorId for create_post or update_post. This is clear context, though it does not explicitly contrast with sibling list_* tools or state when not to use it.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds meaningful behavioral scope beyond annotations by specifying that only the authenticated user's accessible blogs are returned, which addresses auth needs and result filtering. This goes beyond what the annotations alone 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?

A single, front-loaded sentence that states the action, scope, and purpose without redundancy. Every clause earns its place; there is no filler or repeated information 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?

For a zero-parameter read-only list tool with an output schema available, the description is complete. It explains why the tool exists, what result scope to expect, and how it feeds into subsequent calls. Nothing else is needed to invoke it correctly.

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

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

The tool has zero parameters, so the baseline is 4. The description correctly adds no parameter-specific detail because none is needed; the empty schema already fully defines the invocation surface.

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 ('List'), a specific resource ('the authenticated user's accessible blogs'), and a clear downstream purpose ('so later tool calls can target the right blogId'). It is clearly distinguishable from sibling get_blog (single blog fetch) and other list_* tools by its focus on enumerating blogs for later routing.

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

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

The description gives clear usage context: call this before other blog-scoped tools to discover the correct blogId. It does not explicitly mention exclusions or name alternatives, but for a zero-parameter discovery tool, the context is sufficient to guide an agent on when to invoke it.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the tool's safety profile is established. The description adds that it returns 'all' collections, implying no pagination or filtering, but offers no other behavioral context such as error handling or ordering.

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 no filler; it states the action, scope, and inclusivity ('all') clearly. It is appropriately front-loaded and parsimonious.

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 list operation with one well-documented parameter and an output schema, the description covers essential call semantics. Minor gaps like ordering or empty results are not critical because the output schema documents the result shape.

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

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

The schema provides 100% coverage for the single parameter, including a description directing users to list_blogs to discover blog IDs. The tool description adds no new parameter detail, so the baseline of 3 is appropriate.

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

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

The description uses a specific verb ('List') and resource ('collections') with a scope ('for a blog'), clearly identifying the operation and distinguishing it from create/update/delete_collection siblings. It does not explicitly contrast with sibling list tools, but the entity type removes ambiguity.

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

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

There is no guidance about when to use this tool versus alternatives such as list_posts or list_pages. The only hint is the schema parameter description, which mentions using list_blogs for blog IDs, but that addresses parameter discovery, not tool selection.

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

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

The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds no additional behavioral context such as pagination behavior, ordering, or whether all review history is returned, but for a simple read-only list tool this is a minor gap rather than a contradiction.

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

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

The description is one sentence with no filler. It front-loads the core action and resource, then adds the filtering dimension, making it easy to parse and remember.

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 straightforward read-only list operation, the description plus annotations and output schema are nearly sufficient. The main missing element is explicit differentiation from get_latest_content_review, but the plural 'requests' and the status filter make the tool's basic purpose and invocation requirements 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?

Schema description coverage is 100%: blogId is documented with a pointer to list_blogs, and status has enum values plus a default. The description's phrase 'filtered by status' only restates what the schema already provides, adding no new 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?

The description clearly states a specific action ('List'), a resource ('content review requests'), and a scope ('for a blog, filtered by status'). It is not a tautology and is more specific than the title, but it does not explicitly distinguish itself from the closely related get_latest_content_review or list_content_revisions siblings.

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

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

No explicit guidance is given about when to use this tool versus alternatives such as get_latest_content_review, submit_content_review, or decide_content_review. The intended use is somewhat implied by the word 'List', but there are no exclusions, conditions, or sibling comparisons to help an agent select among related review/revision 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 cover read-only, idempotent, and non-destructive behavior. The description adds a useful note that only revision metadata is returned, not full snapshots, but does not disclose ordering, pagination, or other behavioral details. No contradiction with annotations.

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

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

Two concise sentences with no filler. The core action and scoping are front-loaded, and the metadata-only clarification 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 read-only listing tool with full schema parameter coverage, an output schema, and safety annotations, the description is largely sufficient. It only lacks explicit guidance on when to choose this over get_content_revision, but the overall context is adequate.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description adds little parameter-specific meaning beyond clarifying that the target is 'a post or page,' which maps to the contentType 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?

The description uses a specific verb and resource: 'List the saved revision history for a post or page.' It clearly distinguishes this listing operation from related tools like get_content_revision by stating it returns revision metadata and not full snapshots.

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

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

The description implies use for retrieving revision history rather than a specific revision, and 'without full snapshots' hints that full content should be fetched elsewhere. However, it does not explicitly name alternatives like get_content_revision or state conditions for when this tool should be preferred.

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 operation read-only, idempotent, and non-destructive, so the description need not restate those traits. It adds the resource qualifier 'static pages' but otherwise reveals no hidden behavior beyond what the annotations and schema already convey. There is no contradiction.

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

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

The description is a single, tightly written sentence that front-loads the verb and resource and then lists the main capabilities. Every word contributes to the agent's understanding without 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 straightforward list operation, the one-line description plus a fully documented schema and an output schema cover the invocation needs well. It does not offer explicit tool-selection guidance relative to siblings, but that gap is more a usage-guideline concern. The 'static pages' qualifier provides enough resource context to make the description largely 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 all six parameters, including defaults, enums, and the blogId discovery hint, are fully documented in the schema. The description's phrase 'pagination, filtering, and sorting' aligns broadly with page/limit/order/orderBy/status but adds no meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'List static pages.' It also names the key capabilities (pagination, filtering, sorting), and the plural 'pages' clearly distinguishes it from get_page's singular retrieval. The qualifier 'static' separates it from list_posts among the sibling tools.

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

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

The description gives no when-to-use guidance, exclusions, or alternatives. It does not tell the agent to use list_posts for posts or get_page for a single page, even though many list_* siblings exist. The only usage hint, 'Use list_blogs to discover available blog IDs,' is embedded in the schema rather than the tool description.

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

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

Annotations already establish that the tool is read-only, idempotent, and non-destructive, lowering the burden on the description. The description adds limited behavioral context beyond that, mostly restating filtering and sorting capabilities already present in the schema and output schema.

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

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

The description is a single, information-dense sentence with no filler. Key capabilities are front-loaded, and every phrase contributes 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?

Given the fully documented nine-parameter schema, helpful output schema, and safety-related annotations, the description is sufficient for an agent to correctly select and call this tool. The required blogId and discovery hint are already covered in the schema.

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

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

Schema description coverage is 100%, so the schema fully documents all nine parameters. The description provides a useful high-level summary of filter axes but does not add meaning beyond what the schema already offers.

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

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

The description uses a specific verb and resource ('List blog posts') and names the concrete capabilities: pagination, filtering, and sorting. This clearly distinguishes it from siblings like list_pages, get_post, and list_content_revisions.

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

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

The description gives a clear context: use this tool whenever blog posts need to be listed with filters or sorts. It does not explicitly state when not to use it or name alternatives, but the verb and resource make the primary use case unambiguous.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds value beyond that by specifying authentication scope and access level requirements, as well as the available filter types. No contradiction with annotations 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?

The description is two sentences with no filler. The core purpose is front-loaded, and the access requirement is stated compactly without redundant phrasing.

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

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

Given the output schema exists and annotations fully declare the safety profile, the description covers the remaining contextual essentials: resource scope, filter capabilities, and authorization method. An agent has enough information to 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?

Schema description coverage is 100%, so the schema already documents all six parameters. The description adds a useful summary of the filter groups (search, status, type, pagination), but it does not provide additional semantic details beyond what the schema already states.

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

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

The description uses a specific verb ('List') and resource ('redirects for a blog'), clearly distinguishing it from related redirect mutations like create_redirect, update_redirect, and delete_redirect. It also names the key filter dimensions, making the tool's role immediately identifiable.

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 an access prerequisite (owner/admin via OAuth or user-scoped API key) but does not explicitly explain when to choose this tool over alternatives. The distinction from other list tools is implied by the resource being redirects, but no direct when-to-use or when-not-to-use guidance is provided.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context by stating the search filtering is case-insensitive, which is not encoded in the schema.

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

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

The description is a single, focused sentence that front-loads the primary action and immediately includes the key optional behavior. There is no redundant or filler content.

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

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

For a simple two-parameter list tool with rich annotations, an output schema, and a clear description, the definition is complete. The blogId parameter also references list_blogs for discovery, which covers the main 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 coverage is 100%, so the baseline is 3. The description adds meaning to the 'search' parameter by specifying that filtering is case-insensitive, which is not present in the parameter schema.

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

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

The description uses a specific verb ('List') with a clear resource ('blog tags') and an optional behavior ('case-insensitive search filtering'). It fully conveys what the tool does and is distinguishable from other list_* and tag-related 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 implies the tool is used when you need to list blog tags, and the search filter is optional. However, it does not explicitly state when not to use this tool or mention alternatives such as list_posts or list_collections, so the guidance is adequate but not strong.

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 non-destructive behavior, so the description does not need to restate those. It adds useful context about returning a file tree of layouts, templates, and assets, but gives no additional behavioral details such as depth, format, or limits. No contradiction with annotations.

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

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

The description is a single well-structured sentence with examples in a parenthetical. It is front-loaded, scannable, and contains 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 simple read-only list operation with one well-documented parameter, annotations, and an output schema, the description is nearly complete. The only notable gap is explicit guidance on when to choose this over related sibling tools.

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 blogId parameter already has a clear description including discovery via list_blogs. The tool description adds little beyond restating 'for a blog', so a baseline 3 is appropriate.

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

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

The description uses a specific verb ('list') and a clear resource ('theme file tree for a blog') with concrete examples (layouts, templates, assets). It distinguishes reasonably from siblings like get_theme_file and list_available_themes, though it does not explicitly 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?

There is no guidance on when to use this tool versus alternatives such as get_theme_file or list_available_themes. The schema note about using list_blogs to discover blog IDs is parameter guidance, not tool-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 communicate that this is a mutating (readOnlyHint=false) but non-destructive operation. The description adds useful behavior beyond the schema: it uses 'latest saved revision' to indicate the exact state that gets submitted, and restricts the action to draft content. It does not detail side effects like whether a pending review is replaced, but the annotations lower the burden.

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 16-word sentence with no filler. It front-loads the verb, names the exact resource, and states the key scoping condition ('latest saved revision... draft') without repeating schema or annotation 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 relatively simple 4-parameter tool with fully documented parameters, an output schema, and annotations covering mutation safety, the description supplies the critical behavioral nuance about the revision state. It is complete enough for an agent to invoke correctly, though explicit guidance about the review workflow could push it higher.

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 parameters are already fully documented; the tool description adds no parameter-level meaning. It reinforces the post/page scope and the optionality only implicitly, 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 uses a specific verb and resource: 'Submit the latest saved revision of a draft post or page for review.' It clearly identifies the object (draft post/page), the version (latest saved revision), and the action (submit for review), making it distinguishable from sibling tools like decide_content_review and get_latest_content_review.

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

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

The description implies the usage context: use this when a draft has a saved revision and should be sent for review. However, it names no alternatives and gives no explicit when-not conditions, such as what to do if a review already exists or when to use decide_content_review instead.

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 and destructiveHint=true, so the agent knows this is a write operation with destructive potential. The description adds a key behavioral nuance: switching to 'custom' is only valid if theme files exist, implying an error condition otherwise. However, it does not disclose the full scope of changes (e.g., immediate impact on live blog, irreversibility, or what happens to the previous theme). Given the annotation coverage, the description provides minimal additional context beyond the condition, so a 3 is appropriate.

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

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

The description is a single sentence with no filler. The primary action is front-loaded, and the conditional for custom themes is placed immediately after the main clause. Every word earns its place, making it efficient and easy to parse.

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?

As a destructive mutation tool, the description is thin given the potential impact. It lacks instructions on verifying the availability of custom theme files (e.g., using list_theme_files), what happens if the theme is invalid or unsupported, or the irreversible nature of the change. While the schema and annotations cover some basics, the description does not guide the agent on safe or correct usage, missing critical operational context for a tool that alters a blog's appearance.

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 well described in the schema (blogId references list_blogs, theme_id lists enum values and explains 'custom'). The description enhances this by clarifying that some theme_id values are 'built-in' and that 'custom' requires existing theme files. This adds contextual meaning to the parameter beyond the bare enum, particularly distinguishing 'custom' as special. The description does not elaborate on blogId, but the schema already covers that adequately.

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

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

The description clearly states a specific action ('Switch a blog to a different built-in theme or to custom') and identifies the resource (blog theme). It distinguishes this from sibling tools like list_available_themes or update_theme_settings by focusing on the active theme change, not listing or settings. The scope is unambiguous and the verb+resource pairing is precise.

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

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

The description provides no guidance on when to use this tool versus alternatives. It implies switching themes but does not mention using list_available_themes to discover options, nor list_theme_files to verify if custom theme files exist before choosing 'custom'. The only condition given is 'if theme files exist', but it does not explain how to check that or what to do if they don't. No exclusions or alternatives are mentioned, leaving the agent without direction on when this tool is appropriate.

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

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

Annotations already mark this as readOnly=false and destructiveHint=true, so the mutating nature is known. The description adds owner/admin access requirements and identifies exactly which settings may be overwritten, which is useful operational context beyond the annotation 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?

Two compact sentences carry the entire message with no filler. The main action and field list are front-loaded, followed by the permission requirement.

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

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

With a full input schema, an output schema, and annotations covering mutation, the description is nearly sufficient. It could be improved by explicitly routing metadata or domain changes to sibling tools, but the provided field list and permission note make it complete for the core settings-update case.

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 parameters are already fully documented. The description only restates the field names in prose and adds no format, constraint, or relationship details beyond the schema, matching the baseline for high coverage.

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

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

The description identifies a concrete action and resource: updating blog settings, and enumerates the affected fields (name, subdomain, description, logo). It is not tautological, though it does not explicitly distinguish itself from sibling tools like update_blog_metadata or update_blog_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 field list makes the primary use case clear, and the permission prerequisite 'Requires owner or admin access' gives an explicit condition for invoking it. It does not name alternatives or state when not to use it, but the context is sufficiently clear for a settings-update task.

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=true, and the description adds meaningful behavior context: removal via empty string, DNS verification requirements (CNAME/A vs TXT), and the distinction between custom domain and subdirectory modes. It stops short of describing post-removal effects, but the annotation covers the destructive nature.

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-load the core purpose and then convey usage modes, DNS requirements, and removal behavior. 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?

Given the output schema exists, the description covers all necessary decision points: which mode to use, what DNS prerequisites apply, how to remove a domain, and the role of domain_slug. An agent has the full picture needed for correct invocation.

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

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

Although the schema already documents all three parameters, the description adds the crucial relationship semantics: domain alone for custom domains, domain plus domain_slug for subdirectory, and empty domain for removal. This is exactly the kind of parameter interaction an agent cannot reliably infer from the schema alone.

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

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

The description opens with a specific verb and resource: 'Configure or remove a blog's custom domain.' It clearly distinguishes the tool from generic update_blog/update_blog_metadata siblings by making domain configuration the sole focus.

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 mode-based guidance: use domain alone for custom domains with CNAME/A DNS, use domain plus domain_slug for subdirectory hosting with TXT DNS, and pass an empty string to remove. This tells an agent exactly when and with which parameters to invoke the 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?

The description discloses merge semantics (additive, partial update) and excludes theme-related fields, which goes beyond the annotations. It does not fully address the destructiveHint annotation or openWorldHint implications, but the merge behavior is sufficiently communicated to set expectations for an update operation.

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 sentences, front-loaded with the operation, followed by a usage tip and a routing note. Every sentence serves a purpose with no fluff or repetition of schema details.

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

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

For a two-parameter tool with a rich input schema and an output schema, the description covers the essential usage guidance, merge behavior, and theme-tool routing. It does not explain null-value semantics or potential side effects hinted by openWorldHint, but these are secondary for correct invocation.

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

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

Schema coverage is 100% and both parameters are described. The additional instruction 'Pass only the keys you want to add or update' adds practical meaning to the metadata parameter beyond the schema, clarifying that omitted keys are preserved. This modest extra context justifies moving above the baseline 3.

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

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

Description uses a specific verb ('Merge') and resource ('custom metadata into a blog'), clearly defining the operation. It also distinguishes itself from theme-related tools by explicitly pointing them to dedicated tools, which prevents confusion with siblings like update_theme_settings.

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

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

The description provides clear usage instructions ('Pass only the keys you want to add or update') and explicitly states that theme changes belong to other tools. It does not explicitly mention alternatives like update_blog, but 'custom metadata' makes the boundary reasonably clear without additional explanation.

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

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

Annotations already indicate destructiveHint=true and readOnlyHint=false, but the description adds no behavioral context beyond those hints. It does not mention overwrite semantics, that omitted fields are preserved, or any side effects. There is no contradiction with annotations, but the description relies entirely on 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 a single sentence with no filler. It front-loads the verb and resource and enumerates the relevant fields immediately. Every word contributes 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 simple update tool with an output schema and 100% parameter coverage, the description is mostly adequate. However, it fails to clarify that at least one of name, slug, or description should be provided, despite these fields not being marked required in the schema. An agent could call the tool with only blogId and collectionId and produce a no-op or unexpected 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 the baseline is 3. The description only echoes the field names from the schema and adds no additional meaning about formats, relationships, or constraints. The useful 'Use list_blogs' guidance is already in the schema, not 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?

The description names a specific verb ('Update'), a clear resource ('existing collection'), and the exact mutable attributes ('name, slug, or description'). This is unambiguous and differentiates the tool from sibling tools like create_collection, delete_collection, or update_blog.

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, no prerequisites, and no explicit when-not-to-use conditions. It merely states what the operation does. Unlike the calibration example for get_calls, no sibling tool is mentioned for 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 communicate that this is a destructive, non-read-only operation, and the description adds the partial-update behavior via 'any editable field.' However, it does not mention side effects like status transitions, slug changes, or irreversibility beyond what the annotations imply.

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

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

A single, front-loaded sentence with no filler. It clearly states the action, target, and scope without repeating schema 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?

Given the complete input schema, annotations, and output schema, the description is sufficient for an agent to invoke the tool correctly. It lacks only an explicit pointer to sibling alternatives, but 'static page' already provides enough disambiguation.

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 every parameter thoroughly, including cross-references like 'Use upload_image for local files.' The description adds no parameter-level meaning, so the baseline of 3 is appropriate.

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

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

The description uses a specific verb, 'Update,' and a specific resource, 'existing static page,' which clearly distinguishes it from sibling tools like create_page and update_post. The phrase 'any editable field' conveys that this is a partial-update tool, not a full replacement.

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 'existing static page' gives clear context that this tool is for modifying pages that already exist, not for creation. It does not explicitly name alternatives or state when not to use it, so it stops 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 destructiveHint=true and readOnlyHint=false, so the mutation behavior is covered. The description adds minimal extra behavioral context, such as implying a patch-style update via 'any editable field'. It does not detail side effects beyond modification, but with annotations that is acceptable.

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 concise sentence that front-loads the primary action and resource, then adds a notable detail. There is zero redundancy, and every word contributes to the 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?

Given the 12-parameter schema with full descriptions and an output schema, the brief description is sufficient. It states the purpose and key capability, while the schema handles parameter semantics and the annotations handle safety. More detail would be redundant.

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 parameter descriptions are rich (e.g., image references upload_image, authorId notes owner/admin access). The tool description itself adds no parameter-specific information, 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 clearly states the action ('Update'), the resource ('existing blog post'), and highlights a distinguishing capability ('including its author'). This differentiates it from create_post, delete_post, and get_post without needing to inspect 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?

The description establishes a clear context: it is for modifying existing posts, not creating or deleting. However, it does not explicitly name alternative tools or state when not to use it. The context is strong enough for most agents to select it correctly.

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 destructive and read-write behavior, and the description adds meaningful context by specifying owner or admin access through account-level OAuth or a user-scoped API key. It does not contradict the annotations, though it does not describe potential side effects beyond updating the listed 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 two sentences with no filler. The first sentence anchors the action and fields, and the second provides the essential auth requirement. Information is front-loaded and every word earns its place.

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

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

The schema and output schema cover parameter details and return values, and the description supplies the authorization context. It is slightly incomplete because it does not explicitly note that at least one updatable field should be provided, nor does it point to list_redirects or list_blogs for discovering the required IDs.

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?

All six parameters are fully described in the schema, so the description needs only to summarize the key fields, which it does by naming source, destination, status code, and active state. It adds no new constraints or format details beyond what the schema already 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?

The description clearly specifies a concrete action ('Update') and target resource ('redirect'), and enumerates the four mutable attributes: source, destination, status code, and active state. This differentiates it from create_redirect and delete_redirect purely by the verb and resource scope.

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

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

There is no explicit statement of when to use this tool versus create_redirect or delete_redirect. The update verb only implies the tool applies to existing redirects, and the auth prerequisite is useful but does not provide alternative-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 disclose readOnlyHint=false and destructiveHint=true, so the agent knows this is a mutating operation. The description adds no behavioral context beyond 'rename,' such as consequences or potential failure modes, but it does not contradict the annotations.

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

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

The description is a single front-loaded sentence with no filler or repeated information. Every word earns its place for a simple tool.

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

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

The tool is simple, all required parameters are documented in the schema, an output schema exists, and annotations carry the destructive/write profile. The description is minimally sufficient; a slightly richer note about the rename's effect would make it fully 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%, and each parameter is already documented with requirements and constraints. The description itself adds no parameter-level meaning, so the baseline score 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 uses a specific verb and resource: 'Rename a blog tag.' It clearly distinguishes this operation from sibling tag tools like delete_tag and list_tags, and from other update_* tools that target different resources.

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 states the operation but provides no guidance on when to use this tool versus alternatives, no exclusions, and no prerequisites. An agent must infer that this is the tool for renaming an existing tag.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false, and openWorldHint=true. The description adds two pieces of behavior the annotations don't cover: the Pro-subscription requirement and the side effect of copying the built-in theme when no custom files exist. That copy-on-write side effect is exactly the kind of non-obvious behavior worth disclosing.

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 action, then prerequisite, then the conditional side effect. Every sentence carries information an agent needs and none is redundant.

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

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

With an output schema present, return values needn't be explained, and the annotations cover the safety profile. The description fills the remaining gaps (subscription gate, built-in-theme copy behavior) adequately, though it could say more about how updates affect existing files.

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%, with each of the three parameters documented in the schema (including the allowed file extensions pattern). The description adds no format, syntax, or size guidance beyond that, so the baseline of 3 for fully-covered schemas 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 gives a clear verb+resource ('Create or update a theme file') that an agent can distinguish from siblings like get_theme_file, delete_theme_file, and update_theme_settings. It's slightly inconsistent with the tool name (which says only 'update') and doesn't explicitly route against any sibling, so it stops short of a 5.

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

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

It states a real prerequisite ('Requires a Pro subscription'), which is useful gating context. However it gives no guidance on when to use this versus list_theme_files/get_theme_file to inspect first, nor any exclusion conditions, leaving usage largely implied.

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

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

The key behavioral detail 'Unspecified values are preserved' is disclosed, which is important partial-update semantics not captured by annotations. With destructiveHint already signaling mutability, this adds useful context without over-claiming safety.

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 purposeful sentences with no filler. The primary action is front-loaded and the critical preservation behavior is stated immediately after.

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 update tool with full schema coverage, an output schema, and annotation coverage, the description is sufficient for an agent to call it correctly. It tells the agent what to do, what to check first, and how partial updates behave.

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

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

Schema coverage is 100%, but the description adds meaningful semantic value by noting that updates are partial and unspecified values are preserved. This clarifies how the values parameter behaves beyond the schema's JSON-object 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?

Description states a specific verb and resource: update one or more theme setting values for a blog. It is clearly distinguishable from siblings like get_theme_settings, switch_theme, and update_theme_file.

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

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

The description gives a clear prerequisite: use get_theme_settings first to discover valid keys. It does not explicitly rule out alternatives, but the tool name and resource target make the intended use obvious.

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 mutating, non-read-only operation, so the description does not need to restate that. It adds useful behavior beyond annotations: the upload is a separate step that yields a path to be reused later, clarifying that images are not auto-attached to content. It does not describe storage or overwrite behavior, but this is not essential 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 with no filler. The core action is front-loaded, followed immediately by the most important usage instruction. 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?

With a complete input schema, an output schema, and annotations covering mutation safety, the description provides the right high-level glue. It explains the returned-path workflow and covers the main post/page/blog cases. It does not explicitly mention logo uploads, but the schema does, so the missing detail 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%, with each parameter already documented in the input schema. The description adds no parameter-level detail beyond reinforcing the post/page/blog usage, which corresponds to the uploadType enum. Baseline 3 applies because the schema carries the parameter semantics.

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

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

The description uses a specific verb and resource ('Upload an image to a blog') and clearly explains the downstream purpose: the returned path becomes the image value when creating or updating posts, pages, or blogs. This distinguishes it from sibling create/update tools by positioning it as an image prerequisite rather than a content-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?

The description gives explicit workflow context: call this first, then use the returned path in create/update calls. It does not name excluded cases or alternatives, but since no sibling does image upload, the use case is largely unambiguous. The omission of the 'logo' uploadType is a minor gap.

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