WebCake Storefront MCP

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v1.31.8
Disambiguation3/5
With 135 tools, several pairs appear to overlap (e.g., create_page vs build_page vs new_page_skeleton, add_section vs add_draft_section, get_intake_guide vs get_build_guide). However, most descriptions are detailed and clearly differentiate the context (page vs global source vs global section, draft vs persisted), so an agent can learn the boundaries with careful reading.
Naming Consistency4/5
The dominant pattern is verb_noun with get/list/create/update/delete/search, but there are notable deviations: 'new_' (new_element, new_section) coexists with 'create_' (create_page, create_site), and 'build_page' vs 'create_page' for similar actions. Most names remain predictable and readable.
Tool Count1/5
135 tools is far beyond the typical well-scoped set and falls into the 'extreme mismatch' category (50+). Even for a broad storefront platform, the sheer number makes it difficult for an agent to select the right tool and increases cognitive load significantly.
Completeness4/5
The surface is remarkably broad, covering pages, global sources/sections, products, orders, customers, blog, promotions, apps, CMS, collections, themes, images, and a full BuilderX authoring system. A few operations are missing (e.g., updating global section elements, updating site info, customer CRUD), but most workflows have a viable path and gaps are workaround-able.
Average 4.1/5 across 135 of 135 tools scored. Lowest: 2.8/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 133 commits in the last 12 weeks
- Last stable release on June 29, 2026
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI status not available
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description bears the full burden of behavioral disclosure, but it only restates the basic purpose. It does not mention whether this is a safe read-only operation, how results are paginated, what data is returned, or behavior when page_id is omitted.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence with no wasted words, but it is under-specified. While concise, it fails to include important details that could fit in the same space, making it more sparse than appropriately concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has one optional parameter, no output schema, and no annotations. The description does not explain what the returned contents look like, how multi-language is represented, or what happens when page_id is not supplied. It leaves key functional aspects unspecified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% because page_id is documented as 'Filter by Page ID'. The description adds no additional meaning beyond the schema, which handles parameter semantics adequately. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the action ('List') and the resource ('multi-language contents of a page'). It is specific enough to distinguish from siblings like get_page_source or list_elements, though the exact nature of 'contents' remains somewhat vague.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description offers no guidance on when to use this tool vs alternatives, no context about filtering, and no mention of prerequisites or limitations. It only states what the tool does without any situational advice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions filters but omits important behavioral details such as whether it is read-only, what the return format is, and whether pagination is supported. Additionally, the description references a 'date range' filter that is not present in the input schema, which could mislead users.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, but it includes an inaccurate reference to a date range filter. While concise, the misleading content reduces its effectiveness, earning it a middle score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 6 parameters and no output schema, so the description should clarify what the tool returns and any pagination behavior. It does not. It also fails to mention the is_activated filter and includes a non-existent date range filter, making the context incomplete and somewhat confusing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 100% of parameters with descriptions, so the baseline is 3, but the description adds little value beyond repeating schema info. It introduces a 'date range' filter that does not exist in the schema, which is misleading. It also omits the is_activated, page, and limit parameters from its summary.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Search/filter promotions with advanced filters'. It specifies the resource (promotions) and the action (search/filter). However, it does not explicitly differentiate from sibling tools like list_promotions, but the mention of 'advanced filters' implies a more specific capability.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
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 filtering promotions by various criteria) but does not provide explicit guidance on when to use it instead of alternatives like list_promotions or get_active_promotions. No exclusions or alternatives are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full responsibility for disclosing behavioral traits. It only states 'Update a blog article', which implies mutation but does not explain whether it is a partial or full update, what happens if the article does not exist, or whether it is destructive. No additional behavioral context is provided.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no filler words. It effectively communicates the core purpose. However, it is extremely brief and lacks structural details that could be included without bloating, such as mention of updatable fields or side effects, so it is not a perfect 5.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 8 parameters, no output schema, and no annotations, the description is inadequate. It does not explain return values, error behavior, or update semantics. A one-sentence description is insufficient for a tool with this complexity and missing structured metadata.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% parameter description coverage, so the schema already explains each parameter. The description adds no extra semantic information about parameters, such as relationships, defaults, or effect of partial updates. Baseline of 3 is appropriate because the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the verb 'Update' and the resource 'blog article', making the tool's function unambiguous. However, it does not mention the specific fields or scope of the update, and it does not explicitly differentiate from sibling tools like create_article or delete_article, though the resource is specific enough to avoid confusion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 does not mention prerequisites, situations where update_article is preferred over create_article or delete_article, or any exclusions. There is no contextual advice at all.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure, but it only states that it updates existing content. It does not disclose whether the update overwrites the entire file, whether the rename parameter is supported, whether any data is destroyed, or what the return value looks like. This is a significant gap for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that directly states the tool's primary action. There is no redundancy or unnecessary detail; every word contributes to the core message.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no annotations, no output schema, and moderate parameter complexity, the one-sentence description is insufficient. It does not explain whether the operation is reversible, whether it overwrites the full content, what the response contains, or that the 'name' parameter renames the file. An agent would need to infer much of this from the schema and context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides descriptions for all three parameters with 100% coverage. The description adds no extra meaning beyond what the schema already states; 'update code content' mirrors the 'content' parameter description. Since the schema is complete, a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool updates the code content of an existing CMS file, using a specific verb and resource. It distinguishes itself from create_cms_file and other update tools. However, it omits the rename functionality exposed by the 'name' parameter, so the full scope is not captured.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 does not mention that create_cms_file should be used for creating new files, nor does it describe any prerequisites or exclusions. An agent is left to infer usage solely from the tool name and basic action.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of disclosing behavior. It only says 'update' and lists properties, without clarifying whether settings are merged or replaced, whether changes are immediately published, or any permission requirements. The mention of 'custom code' is not backed by a schema parameter, further muddying expectations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, front-loaded with the action 'Update'. It effectively lists key property categories without unnecessary filler. The slight inaccuracy regarding 'custom code' prevents a perfect score, but the structure is efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 5 parameters including a nested object (settings) and no output schema or annotations. A one-line description is insufficient to guide correct invocation. It omits the is_homepage property, does not explain the settings object structure, and lacks information about return values or side effects, making it incomplete for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already has 100% description coverage for all parameters, so the baseline is 3. The description does not add any extra semantic value beyond listing some property names; it actually introduces 'custom code' which is not a direct parameter, potentially confusing the agent.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool updates page properties and lists specific fields (name, slug, settings, custom code). This distinguishes it from sibling tools like create_page (creation) and update_page_content (content-specific updates). However, 'custom code' is not a parameter in the schema, introducing minor ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance is provided on when to use this tool versus alternatives. The phrase 'Update page properties' implies top-level metadata updates, but it does not mention exclusions (e.g., use update_page_content for content changes) or name preferred alternatives. Similar to the update_drive calibration, this lacks contextual direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure, but it only states the action 'Delete' without indicating permanence, side effects, required permissions, or any other consequences. For a destructive operation, this is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence that is extremely concise and front-loaded. It contains no fluff or unnecessary words, making it efficiently scannable for an agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with one parameter and no output schema, but it is a destructive operation. The description omits any mention of permanence, whether it can be undone, effects on related data, or success/failure outcomes, leaving the context incomplete for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema fully describes the only parameter 'id' with 'Article ID' (100% coverage). The description adds no additional parameter semantics, so the baseline of 3 is appropriate given the schema's completeness.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Delete' and resource 'blog article', clearly distinguishing it from sibling tools like delete_page and delete_product. It adds the modifier 'blog' which provides refinement beyond the tool name alone.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus alternatives, nor any conditions, prerequisites, or warnings. The description is purely a statement of function with no usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It fails to mention whether deletion is permanent, if it cascades to dependent resources, or if any confirmation is needed. For a destructive operation, this lack of side-effect disclosure is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no unnecessary words. It is front-loaded and immediately communicates the action, making it appropriately sized for a straightforward tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Although the tool is simple with one parameter, it is destructive and the description lacks essential warnings about permanence or side effects. Without annotations or an output schema, the description should compensate but fails to provide a complete picture for safe invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for the single parameter page_id, whose description 'Page ID to delete' is present. The tool description adds no additional meaning beyond what the schema already provides, so it meets the baseline for high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Delete a page' uses a specific verb (Delete) and a specific resource (a page), clearly distinguishing it from sibling tools like create_page, update_page, and list_pages. It communicates the exact action without ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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, nor does it mention any prerequisites, consequences, or conditions. It is simply a bare statement of the action, leaving the agent without context for appropriate usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description needs to disclose behavioral traits such as whether deletion is permanent, whether it cascades to related products or subcategories, or any required permissions. The description only states the core action without any such context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that conveys the action immediately, with no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Although the tool is simple, it is destructive and no annotations or output schema exist. The description lacks any mention of irreversibility, side effects, or what happens to associated products, leaving the agent with insufficient context for safe invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents the 'ids' parameter with its type and description, covering 100% of parameters. The description adds only a slight clarification that deletion is 'by id' and supports 'one or more', which is already implied by the array type, so it adds marginal value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool deletes one or more product categories identified by id, using the specific verb 'Delete' and the resource 'product categories'. This distinguishes it from sibling tools like delete_product, delete_page, or update_product_category.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to choose this tool over alternatives, such as when it is appropriate to delete a category versus archival, or any prerequisites. There are no exclusions or alternative recommendations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It says 'toggle' but does not explain what debug render mode is, side effects, reversibility, or return behavior. This leaves the agent guessing about the operational impact.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. It conveys the essential action and object efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no annotations or output schema, the description is too minimal. It lacks context about what debug render mode entails, when to invoke it, and what the expected outcome is, making it incomplete for a new agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter cms_file_id has a schema description 'CMS file ID' covering 100% of its meaning. The tool description does not add additional parameter context, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Toggle' and a specific resource 'debug render mode for a CMS file', clearly distinguishing it from sibling tools like toggle_confirm_mode. It is unambiguous about the action and target.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, nor are any prerequisites or conditions mentioned. The description only states the action without context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses only the creation action and does not mention side effects, permissions, return values, or any behavioral constraints, leaving the agent without critical context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, direct sentence that immediately states the tool's purpose and includes useful component type examples. It is concise, front-loaded, and contains no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple create tool, the description covers the core purpose and parameter types, but without an output schema it does not explain the return value or any side effects. It is minimally adequate but lacks behavioral and outcome details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 100% of parameters with descriptions, so the description does not need to add much. The description restates the component type examples already in the schema, adding minimal value beyond the structured definition.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (create) and the resource (new global source component), and it distinguishes this from update/delete siblings by saying 'Create a new'. It also enumerates valid component types, adding specificity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like create_global_section or update_global_source. There is no mention of prerequisites, exclusions, or preferred contexts.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must carry the full burden of behavioral disclosure. It describes a read operation semantically, but it does not state return format, error behavior (e.g., 404 for unknown IDs), authorization requirements, or whether the retrieved article is a draft or published version.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single focused sentence, front-loads the action, and contains no unnecessary words or repetition of schema details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter read tool, the description is minimally viable: it states the operation and the key. However, with no output schema and no annotations, it leaves a gap by not specifying the shape or scope of 'article details', making the returned data unclear to the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents the single 'id' parameter with type string and description 'Article ID', covering 100% of parameters. The description adds little beyond the schema, just restating that lookup is by ID, which matches the baseline 3 for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get article details by ID' uses a specific verb ('get') and resource ('article'), and specifies the lookup key ('ID'), clearly distinguishing it from sibling tools like list_articles. It unambiguously identifies a single-resource retrieval operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to prefer this tool over siblings such as list_articles, update_article, or delete_article. The phrase 'by ID' implies usage with a known identifier, but there is no explicit context, prerequisites, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It implies a read operation via 'Get', but does not disclose behavior such as whether all languages are returned, whether the component parameter is required, or any limits. Lacks detail beyond the obvious read nature.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loaded with the verb, and contains no waste. Every word contributes to the meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with one parameter and no output schema, so the description is relatively adequate. However, it leaves ambiguity about whether it returns contents for all global sources or a specific one, and does not describe the multilingual content structure. Given the low complexity, a 3 is appropriate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with an example for the 'component' parameter. The tool description adds no further parameter-specific semantics, but the schema already handles it, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Get' and identifies a clear resource ('multilingual contents for global sources') with a scope ('by component type'). This clearly distinguishes it from sibling tools like update_global_source_contents or get_global_source_element, which have different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus alternatives such as search_global_source_elements or get_global_source_detail. The description only states what it does, not the intended context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden of disclosing behavior. It states that it 'Returns matching products with basic info,' which gives some insight into the response scope. However, it does not mention read-only status, potential side effects, auth requirements, or pagination behavior, leaving significant transparency gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise and front-loaded: 'Search products by keyword. Returns matching products with basic info.' Every sentence contributes to understanding the tool's purpose and output, with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple search tool with 3 parameters and full schema coverage, the description gives an adequate but minimal overview. It mentions the return type ('basic info') but lacks any explanation of pagination, result ordering, or how it differs from list_products and get_product. Given the low complexity, this is barely sufficient, but not enriched.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with all three parameters (term, page, limit) described. The description adds only the word 'keyword' to reference the term parameter, providing no additional meaning beyond the schema. Baseline 3 applies since the schema fully documents the parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Search products by keyword.' This is a specific verb+resource (search products) with the mechanism (by keyword). It also notes it returns matching products, which helps distinguish it from list_products and get_product, though it does not explicitly differentiate from them by name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 like list_products or get_product. The description only states what it does, not when it should be preferred over sibling tools. It lacks any explicit usage context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It only says 'delete' which implies mutation, but does not mention potential consequences like permanence, required permissions, or whether the operation is a hard or soft delete. This is a notable 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that directly communicates the tool's purpose. It contains no filler or redundant content, making it highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one required parameter with full schema coverage, no output schema needed), the description is adequate. It explains the core function and the parameter. However, a brief note on irreversible effects or authorization requirements would make it more complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers 100% of parameters with a clear description for product_ids, so the baseline is 3. The description's 'by id' adds no new information beyond the schema, making it redundant but not harmful.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Delete one or more products by id' with a specific verb (delete), resource (products), and method (by id). It clearly distinguishes from sibling delete tools like delete_product_category and delete_article by explicitly targeting products.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to use this tool versus alternatives such as set_product_published (which could be used to unpublish instead of delete) or other delete tools. It only states the action itself without contextual cues or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. While 'View' implies a non-destructive operation, the description does not mention any additional behavioral traits such as output format, pagination, or permission requirements. It adds no context beyond the tool name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that clearly communicates the tool's purpose with no wasted words. It is appropriately sized for a simple one-parameter tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one required parameter, no output schema, no nested structures), the description is largely sufficient. However, it does not explicitly describe the return value, which might be expected for a 'view' operation, especially without an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 100% description coverage for the single parameter (page_id), so the baseline is 3. The description does not add any semantic meaning beyond the schema, but the schema is clear and self-sufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function with a specific verb ('View') and resource ('version history of a page'). It also distinguishes from sibling tools like get_file_versions and restore_file_version by specifying 'of a page' as the scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as get_file_versions or restore_file_version. It does not mention any conditions, prerequisites, or scenarios where this tool is preferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states that the tool 'builds a section node' and that children are stacked, which suggests a non-mutating build operation. However, it does not disclose the return value, whether the section is automatically inserted into a page, or any side effects. The word 'build' implies creation of an object, but not fully transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is succinct, with a clear opening sentence and a useful example. The example is illustrative and earns its place, but the overall length is appropriate. There is no redundant information or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has moderate complexity with nested child objects, and the schema documents inputs well. However, with no output schema and no mention of the return value or how the built section is used in page workflows, the description leaves some context gaps. A note on the resulting node and its integration would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides comprehensive descriptions for all parameters (100% coverage). The description adds a concrete example of children and reiterates vertical stacking, which slightly reinforces the schema's 'stacked vertically' note. It does not significantly augment the schema's semantics, 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.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool builds a complete section node with a vertical grid layout for children, distinguishing it from sibling tools that build individual elements or add sections elsewhere. The action verb 'Build' is specific and the resource 'section node' is well-defined. It doesn't explicitly name sibling alternatives, but the scope is clear enough.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains how to use the tool (pass an array of element specs, nest children) but does not explicitly state when to use this tool over alternatives like add_section or new_element. It implies usage through the example and the phrase 'in the builder's vertical grid', but lacks direct guidance on when to choose this tool versus others.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, but it only states the basic operation (fetch and return bytes) without disclosing error handling, failure modes, authentication needs, or rate limits. The extensive post-fetch instructions about describing the image are about downstream analysis, not the tool's own behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is bloated with a long block of instructions on how to describe the image after retrieval, which is tangential to the tool's core purpose. While the first two sentences are concise, the additional field list makes the description unnecessarily long and less scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple fetch operation, the description adequately explains the main function and the schema covers parameters. However, it lacks details about return format (beyond 'bytes'), possible errors, and does not clarify whether the post-fetch image description guidance is required or optional. It is moderately complete but not thorough for a tool with no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides complete descriptions for both parameters (url and max_size_mb), so baseline 3 applies. The description adds minimal extra meaning by reiterating 'image URL' but doesn't explain URL format or size-limit behavior beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb and resource: 'Fetch an image URL and return its bytes for vision analysis.' It also references a specific sibling tool ('scan_unique_images') to contextualize its use, which helps distinguish it from alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit context by saying 'Pair with scan_unique_images to inspect images already on the site,' which implies a workflow. However, it does not offer exclusions or compare against other sibling tools like read_images, so it's not fully explicit about when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It only states 'Create a new CMS file' and lists types; it does not disclose failure modes, permissions, whether existing names are overwritten, or what the response looks like. Minimal for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, direct, no filler. The type list earns its place by clarifying valid values without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Low complexity, schema fully covers parameters and default value. However, with no annotations or output schema, the description omits return/error behavior and usage context; it is acceptable but not complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema already documents all three params with descriptions (100% coverage), and the description's type list repeats the enum. No additional meaning is added beyond the schema, 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Create a new CMS file' with a specific verb and resource. Listing types ('http_function', 'jobs_config', 'default') distinguishes this from update_cms_file and other sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implied usage: use to create new CMS files; the types hint at specialized file kinds. However, no explicit guidance on when to use this over update_cms_file or http_function-specific tools, nor 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.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It only states the core action without disclosing return behavior, error handling, or whether the operation is strictly read-only. The term 'find' suggests non-mutating, but this is not explicit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no filler, front-loading the action and resource. Every word contributes meaning, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple lookup tool with two parameters and no output schema, the description covers the resource and search fields but omits explicit return value details, behavior when no match is found, or potential multiple matches. It is adequate but has gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% coverage with clear descriptions for both parameters, including the enum for 'by'. The description adds little beyond restating the search fields, so it does not significantly enhance understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (find), the resource (customer), and the three supported search fields (ID, phone, email). This is specific and distinguishes it from list_customers and other customer-related tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for looking up a single customer by one of the specified identifiers, but it does not explicitly mention when to prefer it over alternatives or when not to use it. No comparison with list_customers or other search tools is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of disclosing behavior. The word 'Get' implies a read operation, but it does not clarify which site is referenced (e.g., current active site), whether any settings are returned in a specific format, or if there are any limitations. This lack of detail is a significant gap given the presence of site-switching tools.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that immediately states the action and resource. The parenthetical list of settings is concise and avoids unnecessary filler. It earns its place by providing examples of what constitutes 'full site information.'
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description lists several included categories (name, domain, settings with examples), which gives a reasonable overview. However, it ends with 'etc.', introducing ambiguity about the exact scope of the return value. Since no output schema is provided, the description should more precisely define what 'full site information' includes.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the input schema is empty and schema coverage is 100%. Per the rubric, a baseline of 4 applies when there are no parameters. The description does not need to add parameter details since there are none, and it correctly focuses on the return value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Get full site information' followed by a list of included fields (name, domain, settings). This distinguishes it from sibling tools that are more specialized, such as get_site_custom_code, by emphasizing a comprehensive scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus alternatives. It neither mentions situations that warrant this tool nor contrasts it with related getters like get_site_custom_code or list_my_sites. Usage has to be inferred from the tool name and description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the transparency burden. It discloses key behavior: values are saved to local database and auto-restored next session. However, it does not mention potential side effects (e.g., overwriting existing credentials), validation, or whether changes take immediate effect for API calls.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences. The main purpose is front-loaded, and every sentence adds valuable context: what it does, persistence behavior, and how to get parameter values. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple 3-parameter update tool without annotations or output schema, the description is fairly complete. It explains persistence and data source, but omits return value or success/failure behavior, which could be important for the agent's next steps. Still, the core functionality is well covered.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with each parameter described. The description adds extra context by explaining where to find token and session_id (browser DevTools → Network tab), which is useful beyond the schema. api_url receives no additional description but is already clear in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Update authentication credentials' — a specific verb and resource. It distinguishes itself from siblings by focusing on auth, though it doesn't explicitly compare to alternatives, so it lacks some differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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. It only explains how to obtain token and session_id values, but no usage scenarios or exclusions are provided. The intended context is implied but not explicitly stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states 'Get full product details' without detailing return format, error behavior, permissions, or whether it reads published or draft data. This is a minimal statement that does not reveal behavior beyond the basic operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded, starting with the action and resource. The list of returned fields is informative, though the trailing 'etc.' is slightly vague and adds little value, preventing a perfect score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (single required parameter, no output schema), the description is adequate but not comprehensive. It lists major return content, but without an output schema or annotations, it does not fully specify the response structure or edge cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already fully documents the single required parameter 'id' with the description 'Product ID', achieving 100% coverage. The tool description does not add additional parameter-level meaning, but none is needed because the parameter is self-explanatory.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: retrieving full product details by ID, and explicitly lists the included fields (name, description, price, variations, images, attributes, SEO). This distinguishes it from sibling tools like list_products or search_products, which have different scopes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'by ID' gives clear context for when to use this tool: when you have a specific product ID and need full details. It does not explicitly mention alternative tools or exclusion scenarios, but the implied usage is unambiguous for typical retrieval tasks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It explains what the tool does but does not mention side effects (e.g., persistence, reversibility), required permissions, idempotency (handling of already-installed apps), or what happens to the site state. The example and app-type list do not address these behavioral aspects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: it starts with the purpose, provides a practical example, and then lists the valid app types. The list of app types makes the description longer but is necessary for a parameter with an enum. No redundant fluff is present.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a mutation tool with no annotations or output schema. The description explains what and when, but does not cover return values, error cases, prerequisites (beyond 'current site'), or edge cases like duplicate installation. Given the tool's simplicity, it is adequate but not complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds the numeric-to-name mapping for app types and a usage example, which provides some extra context beyond the schema. However, the enum values are already self-explanatory, and the added mapping is not essential for using the parameter correctly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Install (register) an application on the current site so its features become usable.' It uses a specific verb ('Install'), names the resource ('application'), and describes the outcome. It also distinguishes itself from sibling tools like uninstall_app, update_app, and list_apps.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a concrete use case: 'For example, automations need the "automation" app installed first.' This implies when to use the tool (when an app's features are required) and provides clear context. It does not explicitly mention exclusions or alternatives, but the sibling context makes 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.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits itself. It reveals that the tool lists cached results and specifies the returned fields, but it does not explicitly state that the operation is read-only or non-mutating, nor does it mention permissions, rate limits, or side effects. The verb 'List' implies safety, but this is not an explicit disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of 13 words, beginning with the verb 'List'. It includes the resource and the output fields without any filler or redundancy, earning top marks for conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (no parameters, no output schema). The description states the purpose and the fields returned, which is sufficient for an agent to invoke it correctly. It could be enhanced by clarifying what qualifies as 'large' or detailing cache behavior, but these are not essential for basic usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
This tool has zero parameters, so the description has no parameter burden to carry. According to the rubric, 0 params earns a baseline 4. The description's mention of output fields provides context about what the tool returns, which is useful but not directly about parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'List' and identifies the resource as 'large results currently held in the session cache'. It also enumerates the output fields (id, label, size, age), making its function clear and distinct from the sibling tool `read_cached_result`, which retrieves an individual cached result.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus alternatives. It does not mention `read_cached_result` or any other related tool, nor does it specify when not to use it. The intended usage is only implied by the name and verb.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden for behavioral disclosure. It explains the return contents (image bytes, element_id, source_type, source_id) and the pre-built items template, but it does not explicitly state whether the operation has side effects, requires authentication, or has payload/rate constraints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a summary and numbered workflow, making it easy to follow. However, the final sentence redundantly restates the step 3 instruction about filling placeholders, so it is not maximally concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The workflow and return format are clearly explained, which is good for a single-purpose helper. But missing parameter semantics, no output schema, and no mention of edge cases or failure behavior leave notable gaps for an agent to safely invoke this tool in all situations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 40%, with page_id, max_size_mb, and scope lacking descriptions in the schema. The description only mentions using 'scope/limit' and never explains the meaning of the enum values or the other parameters, so it fails to compensate for the low schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as a one-shot helper for filling image_alt, returning image bytes and element metadata, and distinguishes it from siblings like read_images and set_image_alts by prescribing a specific workflow. The verb 'fetch' plus 'images_for_alt_fill' makes the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit workflow context: call with scope/limit, receive images and metadata, draft alts, then call set_image_alts once. This effectively tells when to use the tool, though it does not explicitly mention alternatives or 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of behavioral disclosure. It transparently explains the exact activity filter (is_activated=true and time range), but it does not mention other behaviors such as pagination, sorting, or absence of side effects. As a simple read operation, 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that defines both the action and the exact criteria for 'active'. It is front-loaded with the main purpose and contains no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple zero-parameter read operation with no output schema. The description provides the necessary filter context to understand what the tool returns. However, it could slightly benefit from mentioning its read-only nature or how it differs from list_promotions, though such omissions are not severe given the simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema is empty (0 parameters), and the description correctly focuses on the tool's behavior rather than parameter details. Since there are no parameters, the baseline is 4; the description adds value by explaining the implicit filtering semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Get all currently active promotions' with explicit filtering criteria (is_activated=true and within start_time/end_time range). This is a specific verb+resource combination, but it does not explicitly distinguish itself from sibling tools like list_promotions or search_promotions, which may also return promotions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool: when you need only currently active promotions. However, it does not explicitly state when not to use it or mention alternative tools for broader queries or more complex filtering, leaving some ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the burden. It discloses that client-rendered (React/Vue) pages may return little content, which is useful. However, it does not mention other behavioral aspects such as handling of invalid URLs, redirects, rate limits, or what the 'structural blueprint' contains.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no filler. It front-loads the main operation and adds a valuable caveat in the second sentence.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With one required parameter and no output schema, the description provides a basic understanding but leaves the return format vague ('structural blueprint'). The pointer to ingest_html helps, but a self-contained description would be more complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema documents the single 'url' parameter with the description 'Public page URL to analyse', providing 100% coverage. The tool description adds no further semantic detail, so the baseline 3 applies for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool fetches a public URL and parses it into a structural blueprint. It uses a specific verb ('Fetch') and resource ('public URL'), and references ingest_html for the parsing details, which helps distinguish it from sibling tools like ingest_html and general fetch functions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies a use case (fetching URLs for parsing) but does not explicitly state when to choose this over ingest_html. The note about client-rendered pages provides a caution but not a clear alternative selection rule. The reference to ingest_html suggests it is the canonical tool, but the guidance is implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose side effects. 'Save a version snapshot' conveys a non-destructive write and the rollback purpose adds context, but it does not mention that the provided content is stored as the snapshot, whether the live file is untouched, or what response is returned. It 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence with no filler; the main verb, object, and purpose are front-loaded. Every word adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 3-parameter write tool with no annotations and no output schema, the description is minimally viable: it names the action and purpose, but leaves ambiguity about the role of the content parameter and return behavior. Sibling tools exist for listing and restoring versions, but the description doesn't connect to them.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All three parameters have schema descriptions, and the description adds no additional parameter-level details. It only reinforces that content is saved as a snapshot, so the schema carries the burden and 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Save'), a concrete object ('a version snapshot of a CMS file'), and the purpose ('for rollback'), which clearly distinguishes it from sibling tools like restore_file_version, get_file_versions, and update_cms_file.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'for rollback' implies the tool should be used to create a recovery point before changes, but it does not explicitly state when to prefer this over update_cms_file or when to use get_file_versions/restore_file_version with it. No explicit alternatives or exclusions are named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the transparency burden. It states that execution happens in debug mode without deploying and that results and console logs are returned, but it does not disclose potential side effects, permissions, resource limits, or safety considerations beyond the 'without deploying' qualifier.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no filler. It front-loads the action and includes key modifiers ('debug mode', 'without deploying', 'returns execution result and console logs') without unnecessary elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity and lack of output schema, the description provides a good overview of purpose, behavior, and expected return. It could mention prerequisites or edge cases, but for a debug execution tool, the essentials are covered.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with all three parameters (content, function_name, params) adequately described in the schema. The description adds no additional param-level detail, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Run') and resource ('JS code') with a clear scope ('in debug mode (without deploying)'). It also distinguishes from sibling tools like run_function by highlighting the debug-only nature and return of console logs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for testing code without deployment but does not explicitly mention alternatives or explain when to use this tool over run_function or other code execution tools. Context is present but no direct comparison or exclusions are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden for behavioral disclosure. It does reveal a key trait—that it also deletes the published version—which goes beyond the bare action. However, it omits other destructive-operation traits like irreversibility, permission requirements, or cascading effects, leaving significant gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loaded with the action verb, and contains zero filler. Every word adds value: the resource, the action, and the notable detail about the published version.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter delete tool with no output schema, the description is largely complete: it states the action, the target, and an important scope detail. It does not explain error conditions or post-deletion behavior, but given the tool's simplicity, those omissions are not critical.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already fully describes the single parameter (global_source_id) with a description ('Global source ID to delete'), and the tool description adds no additional semantic meaning beyond repeating the schema. With 100% schema coverage, the baseline is 3, and no enhancement is provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Delete') and resource ('global source') and adds a key differentiator ('and its published version'), clearly distinguishing it from sibling tools like update_global_source, get_global_source_detail, or delete_global_section.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage (when you need to delete a global source) but provides no explicit guidance on when to use this tool versus alternatives, nor any exclusions. The mention of deleting the published version hints at scope but does not cover prerequisites or alternative actions like unpublishing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It adds context by listing the return content, which indicates read-only behavior via the verb 'Get', but it does not disclose error behavior, prerequisites, or any hidden side effects. The listing of returned fields is helpful but not comprehensive for behavioral transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that front-loads the purpose and lists specific details in parentheses. Every word contributes value, with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple 2-parameter read tool, the description covers the purpose and return scope well, and the sibling context helps differentiate. However, without an output schema, the description could be more precise about the structure of the returned detail, and it omits potential caveats like failure modes. Still, it is largely complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for both parameters (element_id and global_section_id). The description does not add additional parameter semantics beyond the schema, 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb ('Get') and resource ('full detail of a single element inside a global section'), enumerating the included details (style, config, specials, events, bindings, responsive bp1..bp4, children IDs). This distinguishes it from siblings like get_global_section (section-level details) and search_global_section_elements (searching).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The scope ('inside a global section') and detail level ('full detail') imply when to use this tool, but there is no explicit guidance on when not to use it or alternatives. The description lacks direct sibling differentiation or exclusions, so it's merely implied usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must convey behavioral traits. It discloses what the response contains, but it does not explicitly confirm the operation is read-only, mention error conditions, or note any side effects. The verb 'Get' implies read-only, and the list of returned attributes adds value, but the absence of explicit safety statements leaves a gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that front-loads the core purpose and lists key content categories without extraneous words. It is concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description effectively summarizes the return content by listing the element's attributes. It is sufficient for a simple get tool with three parameters, though it could be more explicit about return structure or error behavior. Overall, it covers the essential context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema describes all three parameters with meaningful descriptions (e.g., 'Element ID (e.g. TEXT-3)', 'Global source ID'). The description adds no additional parameter semantics beyond the schema, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves full detail of a single element and enumerates the included attributes (style, config, specials, events, bindings, responsive, children). This distinguishes it from sibling tools like search_global_source_elements (search vs. full detail) and get_global_source_detail (source-level detail).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when full element details are needed, but it does not explicitly state when to use this tool versus alternatives like search_global_source_elements or get_global_section_element. No exclusions or alternative guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full transparency burden. It clearly indicates a read operation and enumerates the returned data fields (style, config, specials, events, bindings, responsive, children IDs). This provides useful behavioral context, though it does not explicitly address authentication prerequisites 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that leads with the action and scope, follows with an illustrative example, and concludes with the return payload. No unnecessary words or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple getter with two parameters and no output schema, the description provides sufficient detail about what the tool returns and how to specify the target element. It does not need to explain return values in deeper detail since the listed categories are informative enough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Both parameters are already described in the schema with 100% coverage. The description adds a small example for element_id, but this duplicates the schema's description. There is no additional semantic meaning for page_id. Baseline of 3 is appropriate because the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: retrieving full details of a single element by ID. It provides concrete examples of element IDs and lists the returned data categories. However, it does not explicitly distinguish itself from the sibling tool 'get_element', which may perform a similar function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
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 full detail of a single element is needed) but does not explicitly mention alternatives, exclusions, or when to prefer it over similar tools like 'get_element' or 'search_page_elements'. Usage context is implied rather than clearly stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden for behavioral disclosure. It only says 'List' which implies read-only, but provides no details on output structure, pagination, ordering, or any side effects. This is minimal and does not compensate for the lack of annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, concise sentence that delivers the essential information with no filler. It is appropriately sized and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple zero-parameter list tool, the description covers the action and scope, but because there is no output schema or annotations, it leaves the return format unspecified. This is a clear gap, though not severe given the simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the schema has no properties to describe. The baseline for 0 params is 4, and the description adds no parameter-related information (none needed). It does not detract from the score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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 ('product categories'), clearly stating the scope ('all' and 'of the site'). It distinguishes from sibling tools like list_products (products vs categories) and category mutation tools (create/update/delete), making its purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'of the site' clarifies scope without exclusions, and the context of sibling tools implies this is the read-only counterpart to category management tools. However, it does not explicitly state when not to use it or mention alternatives, so it falls shy of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the burden. It clearly indicates a read-only action ('List all'), but does not disclose potential pagination, rate limits, or what exact file types are included beyond the vague '...'. It could be more explicit about the safety profile and return behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loaded with the key verb and resource, and uses parenthetical examples to add value without extra words. It is concise and to the point.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters and no output schema, the description provides basic clarity about what is listed (CMS files) but does not describe the response format, pagination, or the full set of file types. For a simple listing tool this is adequate, but it leaves some gaps in expectations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool accepts zero parameters, so the description has no requirement to explain parameter syntax. The baseline of 4 is appropriate; no additional parameter information is needed, and the description correctly avoids inventing parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'List' and identifies the resource as 'all CMS files', scoped to 'the site'. It provides examples ('HTTP functions, cron jobs, ...') that clarify scope and distinguish it from sibling tools like get_http_function (a specific function) or create_cms_file/update_cms_file (write operations).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage as a general listing tool for CMS files, but it does not explicitly state when to use it versus alternatives or provide exclusions. With many sibling tools, some guidance on preferring this over get_http_function or list_pages would be helpful, but it is adequate for a simple list operation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the transparency burden. It discloses the metadata-only behavior, which is valuable, but it does not mention pagination (despite page/limit parameters) or any other behavioral traits such as rate limits or sorting. The disclosure is partial.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero fluff. The first sentence states purpose and scope, the second gives a direct pointer to the alternative. 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.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the essential list-vs-detail distinction but leaves gaps with respect to other siblings like get_active_promotions and search_promotions. It also does not compensate for the lack of an output schema by describing the return structure or pagination behavior, leaving some ambiguity for an agent deciding between tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (all 3 parameters have descriptions), so the baseline is 3. The description adds no additional parameter-specific semantics, such as how page/limit relate to the 'all' claim or the purpose of include_guide. The schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' with a specific resource ('all promotions/discounts of the site') and adds the scope 'metadata only', which differentiates it from the sibling get_promotion for full details. This is a precise and non-tautological statement.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly provides an alternative: 'Use get_promotion for full details'. This gives clear when-to-use guidance for the primary distinction. However, it does not mention other relevant siblings like search_promotions or get_active_promotions, so exclusion guidance is incomplete.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It explains an important naming convention (function_name excludes method prefix) and provides an example, which is valuable. However, it does not disclose potential side effects of running a function, authentication requirements, response format, or error behavior. This is partial transparency, sufficient for basic usage but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loads the core purpose, and includes a succinct example. Every word earns its place, with no filler or redundancy. It is efficiently structured for quick comprehension.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has three parameters, one of which is a free-form object, and no output schema. The description explains the naming convention but does not address what 'params' should contain or what the function returns. It also lacks context on side effects or error scenarios. While the tool seems relatively simple, the description leaves some gaps for an agent to fully predict behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers all parameters with descriptions, so the baseline is 3. The description adds the method-prefix clarification and example, which helps interpret function_name and method. However, it does not elaborate on the 'params' object structure or how parameters map to the function call, leaving some ambiguity for nested arguments. Given high schema coverage, this is adequate but not exceptional.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Run a deployed HTTP function.' It uses a specific verb ('run') and resource ('deployed HTTP function'), and distinguishes itself from sibling tools like get_http_function or edit_http_function by focusing on execution rather than inspection or modification. The example further clarifies the intended use.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool (to execute a deployed function) and includes a concrete example showing how to construct the function_name and method. However, it does not explicitly mention alternatives or exclusion criteria, relying on sibling tool names to imply when not to use it. This is a minor gap but not misleading.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses a key behavioral trait (returns the new category id) and a constraint (image must be a hosted URL), but does not mention potential side effects, required permissions, or error cases. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two well-structured sentences. The first states the purpose and the second provides the return value and a key constraint. Every word earns its place, with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given there is no output schema, the description appropriately discloses the return value (category id) and its intended use. It also explains the purpose and the image constraint, covering the essential information for a simple create tool. A minor gap is not explaining potential validation errors or parent_id prerequisites, but overall it is fairly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds no new parameter information beyond the schema; the 'Image must be a hosted URL' note duplicates the schema's 'Hosted image URL' description. No additional semantics are provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create a product category') and the specific resource, distinguishing it from sibling tools like create_blog_category and update_product_category. It also explains the purpose ('so grid-category / a category page has something to show, and products can be filed under it'), adding specificity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context on when to use the tool, such as needing categories for category pages or to file products, and explicitly instructs to pass the returned id to create_product's category_ids. However, it does not explicitly mention when not to use it (e.g., for blog categories) or name alternatives, but the context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of disclosing behavior. It clearly indicates the destructive nature ('Delete', 'remove... from every page source') and adds safety context (two-step dry_run, atomic save). It does not mention irreversibility or auth requirements, but the dry_run safety mechanism is a significant transparency win.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences: the first states the core action and scope, the second explains the safety workflow. No filler or redundant phrasing. All information is necessary and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a destructive mutation with no annotations or output schema. The description covers what it does, the affected scope, and the safety flag. It does not describe the return value or error behavior, but for a delete tool with a dry run, this is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 both parameters well. The description names the parameters (dry_run, section_id) and explains the dry_run flow, but this adds little beyond what the schema provides. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Delete' and specific resource 'global section (Header/Footer/block)', further specifying that it removes the node from every page source. This distinguishes it from sibling tools like delete_global_source and delete_page, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on how to use the dry_run parameter (preview vs. perform), but it does not explicitly state when to use this tool versus alternatives like delete_page or delete_global_source. No exclusions or alternative recommendations are given, so it's adequate but not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It adds useful behavioral context: returns null if not installed and accepts number or name. But it doesn't describe the return object structure, error behavior for invalid codes, or any read-only confirmation. This is a partial disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: the first states the core function and null behavior, the second lists codes compactly. Every element earns its place, and the information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple getter with one parameter and no annotations, the description is nearly complete. It covers the return-null case and parameter format, but could mention what the returned app object contains. Since there is no output schema, a brief note about the return shape would make it fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description covers 100% of the parameter semantics, and the description duplicates the same information. No additional meaning is added beyond what the schema already provides, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Get one installed app') with a clear parameter (type code). It distinguishes itself from siblings like list_apps (which lists all) and install/uninstall/update_app by focusing on retrieval of a single app.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly indicates when to use the tool: to fetch one app by type code, with a useful null return semantics for not-installed. However, it doesn't explicitly name alternatives or state when not to use it, though the context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It discloses the return contents (schema and records) but does not explicitly state that the operation is read-only or mention any side effects, permissions, or error conditions. The verb 'Get' implies read-only, which provides some transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. Every word adds value, clearly stating the action, target, and notable output details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has only one parameter and no output schema. The description adequately explains the tool's purpose and key return data (schema and records). It does not mention pagination or potential errors, but these are not critical for a simple get operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides 100% coverage for the single 'id' parameter ('Collection ID'). The description adds no additional parameter semantics beyond reinforcing that the id identifies a specific collection.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Get') and resource ('specific collection's details'), and adds detail about what's included (full schema and records), distinguishing it from siblings like list_collections and query_collection_records.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly conveys the use case of retrieving a single collection's details with schema and records, implying when to use it. However, it does not explicitly name alternatives or exclusions, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It goes beyond a simple statement of purpose by explaining the structure of the return (combo_items as required items with count, bonus_items as free gifts), which gives the agent a clear expectation of the output. It does not discuss side effects, but the 'Get' verb implies a read-only operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence. It front-loads the action and resource, then concisely explains the return format. All information is relevant and there is no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with only two parameters and no output schema, the description appropriately covers the return structure and distinguishes the two item types. It does not address error scenarios or the effect of optional parameters, but these are less critical for a simple read operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (both parameters have descriptions), so the baseline is 3. The description adds minimal context about the parameters (e.g., linking bonus_items to free gifts), but it does not significantly elaborate on parameter semantics beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies the action ('Get') and the resource ('items (products/variations) and bonus products that compose a combo'), distinguishing it from sibling tools like list_combos which focus on the combo list rather than its components. It also previews the return fields.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
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 the component items of a specific combo, but it does not explicitly state when to use it over alternatives or provide exclusions. Given sibling tools like get_promotion_items, explicit comparative guidance would strengthen this aspect.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It usefully reveals that each version includes its saved content and that restoring requires passing that content back or using restore_file_version. However, it omits details like ordering, pagination, or exact response structure. For a simple view-history tool, 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, front-loaded with the core purpose, and every sentence adds value. The first sentence states what the tool does, and the second explains version content and restore options. No redundant or filler language is present.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter read-only tool with no output schema, the description covers the essential context: purpose, version content, and restore paths. It could mention ordering or whether all versions are returned, but these are minor gaps for a straightforward history-list operation. The description is complete enough for a user to confidently invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides 100% coverage for the single parameter, describing cms_file_id as 'CMS file ID'. The description adds no additional parameter-level meaning, so the baseline score of 3 applies. It does tie the parameter to the concept of a CMS file but doesn't clarify format or constraints beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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 ('View version history of a CMS file'), clearly identifying the tool's purpose. It also distinguishes itself from sibling tools by explicitly mentioning restore alternatives (restore_file_version, update_cms_file), making its read-only history role unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides concrete guidance on when to use this tool vs. alternatives: it tells you to pass saved content back to update_http_function/update_cms_file or to use restore_file_version for restoration. It doesn't explicitly state 'do not use this for restoring,' but the contrast is clear enough. No exclusion criteria are given, but the usage context is well implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the compact tree format, token savings, and the raw option's large-result cache behavior via the schema. However, it fails to explain the meaning of Nbind and Nev, and does not explicitly state that the compact tree is a lossy summary compared to raw JSON, leaving behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, each contributing essential information: the action and format, the line-by-line output structure, and the intended use case. There is no verbose or redundant phrasing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool with well-described parameters, the description covers purpose, output format, and usage guidance. The lack of an output schema is compensated by the line-format explanation. Minor gaps around abbreviations and potential lossy nature prevent a perfect score.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Both parameters are fully described in the schema (100% coverage), so the description adds little per-parameter semantics. The line-format explanation provides context about the default output of the raw parameter, but this is a minor enhancement over the schema's descriptions. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Get one global section as a COMPACT tree', specifying both the resource and output format. It distinguishes from siblings by emphasizing the compact tree vs. raw JSON and the learning purpose, which is unique among related tools like get_global_section_element or list_global_sections.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides an explicit usage context: 'Use this to learn how a real Header/Footer/block is composed before building your own.' This tells the agent when to choose this tool, though it does not explicitly mention alternatives or exclusion cases, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses the read-only nature via 'Read' and adds the performance trait of token-efficiency. However, it does not mention return format, error handling, or behavior for non-existent function names.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, front-loaded with the action and resource. The token-efficiency rationale is valuable and there is no wasted wording.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool with one parameter and no output schema, the description effectively communicates the core action and a key benefit. It could add the return type or explicitly note non-mutation, but the current level is sufficient for selection and basic invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage for the single parameter function_names, including an example. The description adds little beyond the schema, only reinforcing the 'by name' aspect, which does not meaningfully improve parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Read' and the resource 'specific function(s)' with the scope 'by name'. It also distinguishes itself from sibling tools like get_http_function by emphasizing token-efficiency compared to reading the full file.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives a clear usage context: use this when you need specific functions by name and want to avoid the token cost of reading the entire file. It implies the alternative (reading the full file) but does not explicitly name the sibling tool 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of explaining behavior. It discloses the return content (customer info, items, etc.) and the verb 'Get' suggests a read-only operation, but it does not explicitly state side effects, permissions, or error behavior. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that specifies the action, target, and key content areas. There is no superfluous text; every word adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a get-by-id tool with one parameter and no output schema, the description adequately outlines what the return contains (customer info, items, payment, shipping, discounts). It could be more precise about the response shape, but the 'full details' phrasing plus the enumerated list covers the main expectations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the single 'id' parameter is already documented in the schema as 'Order ID'. The description adds 'full details' context but no new parameter syntax or format details, aligning with the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get') and resource ('full order details by ID'), and enumerates the included information (customer info, items, payment, shipping, discounts). This clearly distinguishes it from list_orders and count_orders_by_status, which are about order listings and counts rather than single-order detail retrieval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for fetching a single order's full details when an ID is known, which is clear context. It does not explicitly state when not to use it or name alternative tools, but the scope is evident from the 'by ID' qualifier and the detail focus.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It clearly signals a read-only inspection (via 'Inspect'), discloses the conditional output ('if a commit is in progress'), and notes the draft is local. It does not cover error behavior or details of 'meta', but the core behavioral traits are transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single compact sentence, front-loaded with the action and resource. Every phrase adds value—naming the object, listing return fields, and noting the conditional behavior—without any redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and no output schema, the description adequately covers the return values, including the conditional behavior. It could optionally mention what happens if the draft doesn't exist, but this is not essential given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter draft_id is fully described in the schema ('Draft id'), yielding 100% schema coverage. The description adds no additional meaning about the parameter itself, but the parameter is simple and self-explanatory, 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Inspect' and clearly identifies the resource 'a local page draft'. It enumerates the exact contents returned (meta, section ids, total section count, and conditional page_id + committed_count), distinguishing it from sibling tools like start_page_draft, commit_page_draft, or list_page_drafts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you have a draft_id and want to inspect its state, but does not explicitly state when to use this tool versus alternatives. It doesn't mention exclusions or contrast with sibling tools like list_page_drafts, making the usage guidance implicit rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of disclosure. It states the return content (items with discount details), which adds useful behavioral context. However, it does not explicitly confirm that the operation is read-only or free of side effects, though the 'get_' prefix implies this. The description adds some transparency but not comprehensive details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that immediately states the action and the key return information. There is no redundant filler, and every word contributes to understanding the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a straightforward retrieval tool with three well-documented parameters and no output schema, the description provides sufficient context about the resource scope and return details. It could explicitly mention pagination behavior, but the page and limit parameters already imply this. Overall, it is complete enough for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All parameters (id, page, limit) already have descriptive schema entries, so the description does not need to add much. It does not provide any additional parameter-specific meaning beyond what the schema offers, 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves products/variations/categories attached to a promotion, with a specific verb ('Get') and resource scope. It distinguishes itself from sibling tools like get_promotion or list_promotions by focusing on the items attached to a promotion and their discount details.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description conveys a clear use case: fetching items attached to a promotion. It does not explicitly mention when to use it over alternatives like get_combo_items or get_promotion, but the context is clear enough. No exclusions or alternative tool names are provided, so it earns a 4 rather than 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It states the scope ('accessible by the current account') and implies a read-only list operation, but it does not describe pagination behavior, response format, or any potential side effects. This is adequate for a simple list tool but not richly transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences, front-loading the verb and resource, and every phrase adds value. It is concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a simple list operation with three optional parameters and no output schema. The description covers its purpose and a key use case (finding site_id for switching), which is sufficient for the tool's complexity. It does not explain the return structure, but that is not critical for a list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each parameter (page, term, limit) having its own description. The tool description adds no additional semantic detail about parameters, 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists all sites accessible by the current account, using a specific verb ('list') and resource ('sites'). It also explicitly ties its purpose to finding a site_id for switching, which distinguishes it from related tools like switch_site or create_site.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear use case: 'Use this to find a site_id before switching.' This implies when to use it, but it does not explicitly mention when not to use it or name alternatives. However, the context is strong enough for most agents to understand.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description must carry the safety/behavior burden. It discloses the non-dumping behavior ('without dumping the whole tree') but does not explicitly state that the operation is read-only, describe return format, or mention rate limits. The verb 'Search/filter' implies non-mutating, but richer disclosure would be needed for full transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences front-load the purpose and then list filter options. Every word is useful; no redundant content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description defines the tool's purpose, filtering capabilities, and efficiency trait, which is sufficient for a basic filtered-list tool. However, there is no output schema and no mention of result structure or pagination behavior, leaving some ambiguity as to the exact response shape.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers all 9 parameters with descriptions, so the baseline is 3. The description lists the filter types but largely restates parameter names from the schema without adding new syntax or format details beyond what is already structured.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Search/filter' and names the resource 'elements within a global section (Header/Footer/block)', immediately distinguishing it from a full tree dump. It also enumerates filter dimensions, making the scope clear relative to sibling tools like search_page_elements or search_global_source_elements.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It states the benefit 'without dumping the whole tree', implying this tool is for targeted queries when a filtered subset is needed. It does not explicitly name alternatives or exclusions, but the context makes 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of disclosing behavior. It mentions returning 'full detail' and gives filter examples, but does not explain edge cases like substring matching behavior, default limit enforcement, or what happens when no elements match. The schema covers defaults, but the description adds moderate context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: one opening sentence plus six short example lines. Every line adds practical value, and the formatting makes filter options easy to scan. No redundant content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a search/filter tool with 9 parameters and no output schema, the description covers the key usage patterns and return intent. It lacks explicit mention of pagination/limit behavior or relationship to page source lifecycle, but the examples and clear scope are sufficient for typical use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although schema coverage is 100%, the description adds valuable usage semantics by showing concrete example values for multiple parameters (`type="button"`, `text="subscribe"`, `has_bind=true`, etc.). This goes beyond the schema's raw field descriptions and helps the agent form valid queries.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Search/filter elements within a page source' with a specific verb and resource, and lists concrete example filters. It distinguishes from sibling `search_global_source_elements` by explicitly scoping to 'page source', making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides useful examples of filters, which implies usage patterns, but does not explicitly state when to use this tool versus alternatives like `list_elements` or `search_global_source_elements`. No exclusions or alternative comparisons are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavior. It discloses the scope (full catalog) and return value structure (name, group, description, JSON input schema), which is useful. However, it does not mention potential performance implications, rate limits, or whether the search is fuzzy/partial, leaving some behavioral ambiguity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the primary action and scope, and includes an illustrative list of capability categories. The follow-up instruction is useful and wastes no words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a straightforward search utility with full schema parameter descriptions. The description explains the return format and next action, making it largely complete. Minor gaps: does not explain what 'group' refers to or any result limits beyond the schema, but these are peripheral.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides complete descriptions for all three parameters (query, group, limit), so the description does not need to add parameter details. The description adds no additional parameter semantics, but schema coverage fully compensates, earning a baseline score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Find') and clearly identifies the resource ('WebCake tools') with a key differentiator ('FULL catalog — including capabilities NOT loaded natively'). It lists example categories and states the return payload, distinguishing it from sibling search tools like search_products or search_global_source_elements.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear context for when to use the tool: to discover tools across the full catalog, especially non-native capabilities. It also states the follow-up action ('Then run one with invoke_tool'), but does not explicitly compare to or exclude alternative search tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of behavioral disclosure. It adds useful context that the operation is quick and batch-capable ('one or more products') and is not a full update. However, it does not mention side effects, permissions, reversibility, or response behavior, which would be valuable for a mutating tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that conveys the action, scope, and key differentiator without any wasted words. Every element earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given this is a simple two-parameter tool with full schema coverage, the description is largely complete for the core task. It provides purpose, scope, and the key 'quick toggle' context. However, because there is no output schema and no annotation, it could have briefly mentioned expected return values or error behavior to be fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% coverage of both parameters, with descriptions for product_ids and is_published. The description reinforces that product_ids can be 'one or more' and that the action is 'publish or unpublish', but it does not significantly add beyond the schema's existing parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb+resource: 'Publish or unpublish one or more products quickly (without a full update).' It distinguishes itself from sibling tools like update_product by explicitly calling out that this is a quick, targeted operation rather than a full product update.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'without a full update' provides clear context that this tool is intended for quickly toggling publish state rather than performing a full product update. However, 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must fully convey behavioral traits. It clearly states that the tool removes/ uninstalls an app, which communicates destructiveness. However, it does not disclose side effects, whether the action is reversible, or if any confirmation/permission is required. The core behavior is transparent, but some safety details are missing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences. The first sentence front-loads the primary purpose, and the second provides essential usage guidance. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple 1-parameter tool with no output schema, the description adequately covers the action, scope, and how to obtain the required id. It could mention the return value or effects after uninstall, but that is not essential for this straightforward operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the parameter description already states 'App subscription id (from list_apps / get_app)'. The description adds the minor detail that the 'id' field from list_apps should be used, but this is largely redundant with the schema. The added value is small, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Uninstall (remove)' and clearly identifies the resource as 'an installed application from the current site.' It is immediately distinguishable from sibling tools like install_app, update_app, and get_app.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool (to remove an installed app) and gives a prerequisite: obtain the subscription id from list_apps or get_app. It does not explicitly mention when not to use it or alternative tools, but the context is sufficient for this straightforward destructive operation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses the need for the full settings object (implying replacement) and the subscription id prerequisite. But it does not explicitly state whether the update replaces or merges settings, nor any side effects or error conditions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: first declares purpose, second gives required inputs. No filler, front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 2-param tool with no output schema, the description covers purpose and key input requirements. It tells the user how to get the id and what to pass. However, it leaves some ambiguity about the update semantics (replace vs merge) and response details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents both parameters. The description adds the 'full settings object' guidance and examples, but this is marginal beyond the schema's own examples.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool updates the product-review app's settings, with specific examples (shop_info, auto-approve, display options). It differentiates from the sibling 'update_app' by specifying 'product-review app'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear context: use to update settings for the product-review app, and instructs to pass the subscription id from get_app and the full settings object. However, it does not explicitly mention alternatives or exclusions, leaving some room for ambiguity with update_app.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses the critical behavioral constraint of requiring prior reads and user confirmation, but it does not describe whether the operation merges or replaces content, nor any other side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, with the purpose front-loaded and the warning following. Every word earns its place; it is concise without being under-specified.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is sufficiently complete for a mutating tool given the schema details and the strong safety warning. It does not explain return values (no output schema), but that is not required. Some details about content structure could be added, but the essential context is present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers all four parameters with descriptions ('Page content', 'Page ID', 'SEO meta tags', 'Language code'), so the description adds little. Baseline 3 applies due to high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Create/update page content for a specific language,' clearly identifying the verb, resource (page content), and scope (language). This distinguishes it from sibling tools like update_page, update_page_element, and update_page_source.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mandates a pre-call workflow: read existing content with list_page_contents and obtain explicit user confirmation. It explicitly forbids updating without approval, providing strong usage guidance, though it does not name alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It explicitly discloses that the action is irreversible and removes all records in the collection, which are critical behavioral traits. It does not mention permissions or return values, but the key destructive behavior is well covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: two short sentences that immediately state the action and its irreversible nature. There is no filler or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete operation with one parameter and no output schema, the description covers all essential aspects: what is deleted, the scope (all records), and irreversibility. The low complexity means nothing important is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema describes the only parameter (collection_id) with 'Collection id.', and the tool description reinforces 'by id.' Since schema coverage is 100%, the description adds little 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states clearly that the tool deletes a collection (table) and all its records by id. This is a specific verb+resource+scope, and it distinguishes the tool from siblings like get_collection, update_collection_columns, and query_collection_records.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage—when you need to permanently delete a collection—but does not explicitly state when to use it versus alternatives, nor does it mention exclusions or prerequisites. The irreversibility warning is more of a caution than usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden. It does describe behavioral output (live skeleton node, ATTRIBUTES reference) but does not explicitly state whether the operation is read-only or any other side effects, auth needs, or rate limits. The 'get' verb implies safety, but the description leaves those aspects implicit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with dense, structured information. It front-loads the main action and follows with a clear usage tip. Every clause adds value, and there is no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has only one parameter and no output schema, the description thoroughly explains what the response will contain (category, container flag, summary, ATTRIBUTES reference, skeleton node) and provides usage context. This is sufficient for an agent to understand the tool's role and invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already fully describes the only parameter 'type' with examples. The tool description simply repeats 'element type' without adding any additional semantic context (e.g., valid values, case sensitivity, or relationship to other tools), so it adds no value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool gets the full detail of an element type, enumerating the specific contents (category, container flag, summary, ATTRIBUTES reference, live skeleton node). This clearly distinguishes it from sibling tools like get_page_element or get_global_source_element by focusing on 'element type' as a resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides a clear usage directive: 'Read this before authoring/editing an element so you set the right keys.' However, it does not explicitly mention when not to use it or name alternative tools, such as list_elements for a catalog overview or get_page_element for page-instance details.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It adds context that the tool is site-scoped and specifies the output fields (type, status, settings) plus the app type codes, which help the agent understand the response. It does not explicitly state side-effect safety, but 'List' implies a non-mutating operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: the first sentence states the purpose and scope, and the second provides a valuable mapping of app type codes. Both sentences earn their place without redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with no parameters, annotations, or output schema, the description is remarkably complete. It covers what is listed, the fields returned, and even decodes type codes. This is sufficient for an agent to understand and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters, so the schema provides no information. Per the rubric, 0 params yields a baseline of 4. The description adds nothing further about parameters, but none are needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists 'the site's installed applications' with specific detail on output fields (type, status, settings). This verb-resource combination distinguishes it from siblings like install_app, uninstall_app, and get_app.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. It does not mention that get_app should be used for a single app or that this tool is for all installed apps. The description only explains what the tool does, not when to prefer it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the burden. It explains the event structure, auto-minting of IDs, and provides an example. However, it does not explicitly state that the tool is read-only, nor describe the output format or any limits, leaving some ambiguity about behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, information-dense sentence. It is front-loaded with the core purpose and then elaborates with examples and usage. While not elegantly structured, it contains no filler and each clause adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no parameters or output schema, the description covers the essential context: what events are, how they are used, and a concrete example. Missing pieces like explicit read-only status or response format are minor given the simple nature of a list/reference tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema provides no parameter details. The description compensates by explaining the content and format of the returned event catalog, effectively covering what the tool offers even without parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists interaction events attachable to nodes, with a specific verb ('List') and resource ('interaction EVENT'). It distinguishes itself from sibling list tools by specifying the domain (events for node attachment) and enumerating example triggers and actions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit context on when the result is used: when attaching events via new_element/new_section opts.events. It doesn't mention exclusions or alternatives, but the context is clear and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses a crucial behavioral trait: the operation is scoped to the local draft and does not affect the backend page. This addresses the most important side-effect concern. It does not mention irreversibility or confirmation, but for a simple delete operation, this is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence. It front-loads the action and the critical caveat, with no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter delete tool with no output schema, the description is nearly complete. It covers the core action and the important exception. Minor gaps exist regarding irreversibility and return values, but these are not critical for this tool's scope.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the parameter 'draft_id' is already described as 'Draft id'. The description adds no additional meaning beyond the schema, so it meets the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Delete a local page draft'. It uses a specific verb ('Delete') and resource ('local page draft'), and explicitly distinguishes it from deleting a backend page, which differentiates it from sibling tools like delete_page.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context by clarifying that this tool does NOT delete the backend page, which implies when not to use it. However, it does not explicitly name an alternative tool (like delete_page), so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full burden. It states the aggregation behavior ('grouped by status') but doesn't add details like whether all orders are included, if zero-count statuses appear, or the exact return shape. For a simple read-only count, the lack of side effects is implied by 'get,' but additional context would be helpful.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences with no filler. It front-loads the core action and adds a brief use case, making it highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple aggregation tool with no parameters and no output schema, the description gives the essential behavior and intended use. It could be improved by specifying the output structure (e.g., key-value pairs or list of status/count), but overall it is sufficient for an agent 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.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the schema coverage is trivially 100%. Per the baseline for 0 params, a score of 4 is appropriate, as there is no parameter information needed and the description does not need to compensate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get order count grouped by status' clearly specifies the verb (get), resource (order count), and grouping (by status). It distinguishes itself from sibling tools like list_orders or get_order, which return order details rather than aggregated counts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'Useful for dashboard overview' provides a clear context for when to use this tool, implying it is for aggregate reporting rather than detailed order inspection. However, it does not explicitly name alternatives or exclusions, 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the transparency burden. The verb 'Get' implies a read-only operation, and the content list clarifies what the guide covers, but it doesn't explicitly state that it has no side effects or describe the output format. This leaves some behavior unspecified.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences: the first delivers the core purpose and content, the second gives usage guidance. There is no wasted wording, and it is well-structured with front-loaded information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple guide-retrieval tool with no parameters and no output schema, the description covers the essential context: what the guide contains and when to read it. It might have explicitly mentioned that it does not modify pages, but that is reasonably implied by 'Get'.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, so schema coverage is 100%. According to the baseline for 0 params, a score of 4 is appropriate. The description adds no parameter info because none are needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a specific verb 'Get' and names the resource 'BuilderX page authoring guide', then lists the covered topics. This clearly distinguishes it from other tools like get_intake_guide and action-oriented siblings (build_page, update_page).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states when to use the tool: 'Read this before building or heavily editing a page.' This is strong usage guidance. However, it does not mention any when-not cases or alternatives, so it misses the full 'vs alternatives' component.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It indicates a read operation ('Get') and discloses the return content in detail. No hidden side effects are apparent, though error handling or prerequisites are not addressed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence, front-loaded with the primary purpose, and enumerates expected fields without unnecessary words. Every part is informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool without an output schema, the description lists the main return fields, giving a clear expectation. The trailing 'etc.' introduces some ambiguity, but it's acceptable for a comprehensive detail object.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with one parameter 'id' described as 'Promotion ID'. The description adds context by saying 'by ID' and listing what details are returned, but it doesn't add new parameter-level meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get'), the resource ('promotion details by ID'), and enumerates the covered fields (name, type, schedule, discount rules, etc.). This distinguishes it from sibling tools like list_promotions (listing all) and get_promotion_items (maybe only items).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use: when you have a promotion ID and need full details. It doesn't explicitly mention alternatives or exclusions, but the sibling tool names provide context. Clear usage intent without explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the transparency burden. It does add behavioral context by mentioning the output is a 'compact tree view' and shows the 'full element hierarchy', which goes beyond a simple 'get' statement. However, it does not disclose any limitations, error conditions, or side effects, though the getter nature implicitly suggests non-destructiveness. The disclosure 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the primary action ('Get all cart global sources with compact tree view') followed by a valuable clarification ('Shows full element hierarchy — no need to call get_global_source_detail separately'). Every sentence earns its place with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, no-output-schema tool, the description covers what the tool returns (compact tree view with full hierarchy) and its benefit over a sibling. It does not dive into the exact structure of the tree, but given the simplicity of the tool and strong sibling context, the completeness is sufficient for an agent to select and invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and the schema is empty, so schema coverage is trivially 100%. With 0 parameters, the baseline is 4; the description correctly adds nothing about parameters because there are none to explain.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get') and identifies the resource ('cart global sources') plus the output format ('compact tree view'). It also distinguishes itself from the sibling tool get_global_source_detail by explicitly stating that calling the latter separately is unnecessary, making the tool's scope clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides an explicit usage hint by stating 'no need to call get_global_source_detail separately', which tells the agent when this tool can replace an alternative. It does not explicitly enumerate when not to use it, but the guidance is clear enough for a simple retrieval tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden. It discloses the return fields (collection names, table names, field counts) and implies a read-only listing operation by using 'List'. It also notes that this is not the full-schema view, pointing to get_collection. However, it does not disclose pagination behavior, which may conflict with 'List all' when page/limit parameters exist.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the primary purpose. The first sentence states the action and resource, and the second sentence adds output details and an alternative. There is no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose, output fields, and an alternative for deeper detail, which is sufficient for a simple list tool. However, it omits pagination specifics and does not clarify that the 'all' might be limited by page/limit parameters. Given the absence of annotations and output schema, this is nearly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All three parameters (page, term, limit) have descriptions in the schema, so the description adds minimal semantic value beyond the schema. It does not explain how to use these parameters together or what 'all' means in the context of pagination.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List all database collections') and the resource ('for the site'), and distinguishes itself from the sibling tool get_collection by noting that get_collection provides full schema details. This is a specific verb+resource combination with a clear scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly points to get_collection as the alternative for full schema details, which tells the agent when not to use this tool. However, it does not mention other related tools like query_collection_records or clarify conditions such as pagination usage, so it is clear but not exhaustive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the behavioral transparency burden. It implies a read-only list operation but does not mention pagination behavior (despite page/limit parameters), the meaning of 'all' given those parameters, or any other behavioral details. Basic transparency is present but lacks depth.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the primary purpose, and contains no extraneous information. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is relatively simple with full schema coverage and no output schema. The description is sufficient to distinguish it from siblings and convey its core function, but the ambiguity between 'all' and the presence of page/limit parameters leaves a minor gap in completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 does not add any additional meaning to the parameters; it leaves all parameter semantics to the schema, which is acceptable but provides no extra value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists all combo/bundle products of the site, using a specific verb ('List') and resource ('combo/bundle products'). It also distinguishes itself from the sibling tool get_combo_items by explicitly redirecting users there for composition details.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear alternative: 'Use get_combo_items for combo composition details.' This tells the agent when to use this tool (listing combos) versus when to use a sibling tool (getting composition details), satisfying the explicit alternative requirement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of behavioral disclosure. It reveals that the tool returns a 'compact summary per source' and warns that the API may not return all types without a filter, which is non-obvious and valuable context. It does not explicitly state side effects or read-only status, but for a list operation this is largely self-evident.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, with the purpose front-loaded and the caveat appended. Every sentence adds value: the first defines the tool's output, the second provides an essential usage warning. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (1 optional parameter, no output schema), the description covers the essential aspects: what it lists, the return format ('compact summary'), and a critical caveat about filtering. It is reasonably complete for an agent to invoke correctly, though it could potentially mention pagination or related sibling tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 the 'component' parameter. The description reinforces the importance of the parameter ('Always provide component') and gives examples in the schema, but adds no new syntax or format details beyond what the schema already states. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List global sources') and the resource ('global sources (cart, popup, etc.)'), distinguishing it from siblings like get_global_source_detail and search_global_source_elements. The verb 'List' is specific, and the resource scope is defined.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides an explicit usage instruction: 'Always provide component to filter by type — the API may not return all types without a filter.' This tells the agent when and how to use the tool effectively. It does not explicitly mention alternatives or when not to use it, but the guidance is clear and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of disclosing behavioral traits. It explicitly states the return is metadata-only with a specific field list, which prevents the user from expecting full product details. It also signals a read-oriented operation via the verb 'list'. It lacks mention of pagination or response envelope, but the core behavioral limitation is clearly conveyed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the verb and resource, and directly states the output scope and the alternative tool. Every sentence earns its place; no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description does well to enumerate the returned fields (id, name, slug, price, image, status) and direct users to get_product for more detail. It does not address pagination despite page/limit parameters, which is a minor gap for effective invocation. Overall, it provides sufficient context to select and use the tool for common purposes.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema descriptions already cover 100% of the parameters (page, term, limit), each with a brief meaning. The tool description adds no additional parameter-level context, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb+resource ('List products of the site') and defines the exact scope with metadata fields. It also points to 'get_product' for full details, distinguishing itself from that sibling tool. This makes the purpose immediately clear and differentiates it.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context: use this tool for a metadata-only list of products, and use 'get_product' when full details are needed. It does not, however, explicitly address when to use this vs. 'search_products' or other listing tools, so it falls short of a full 5 but still provides useful decision guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full responsibility. It discloses that the tool hits a public API (api.storecake.io), is search/list-oriented (read-only by implication), and returns the fields id, name, preview_url, thumbnail, categories. This goes beyond a minimal description, though it doesn't mention pagination or default language.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two compact sentences: first states what and where, second states usage and return fields. No fluff, front-loaded, every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple search/list tool with all-optional params and no output schema, the description covers the purpose, usage, and return shape sufficiently. It could mention pagination behavior, but the schema already documents page/limit, so this is adequately complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with descriptions for all parameters. The description adds no new information beyond the schema; 'by keyword' merely reinforces the 'q' parameter. Baseline 3 is appropriate since the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb + resource ('Search/list the public Webcake template marketplace') and explicitly states the keyword matching purpose. It distinguishes from sibling tools like list_themes (likely site themes) and semantic_search_themes by specifying the marketplace and keyword-based search.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a clear usage scenario: 'match customer brief against existing templates by keyword.' This tells the agent when to use it. It doesn't explicitly name alternatives or exclusions, so it falls short of a 5, but the context is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It reveals the output fields (group name, tool count, loading type) and adds useful context about the tool ecosystem, but it does not explicitly state that the operation is read-only, has no side effects, or mention any rate limits or permissions. The verb 'list' implies safety, but given the absence of annotations, a bit more transparency would be expected.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is front-loaded with the primary action, then lists the specific output attributes. Every phrase earns its place, including the clarification of 'on-demand' via search_tools + invoke_tool, which is necessary to understand the tool's scope. There is no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given there is no output schema and no annotations, the description must carry the burden of explaining what the tool returns. It does so by listing the three key pieces of information. It also adds valuable ecosystem context (native vs on-demand), which helps the agent understand tool relationships. The only minor gap is that it does not specify the exact response format (e.g., array of objects) or any ordering, but for a simple list tool this is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the schema coverage is 100% (vacuously). Per the rubric, this sets a baseline of 4. The description adds no parameter information because there are none to explain, which is appropriate. It correctly focuses on the output rather than input.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists every WebCake tool group with two specific details: number of tools and loading mode (native vs on-demand). It uses the specific verb 'list' and resource 'tool group', and distinguishes itself from sibling tools by focusing on groups and their categories, as opposed to individual tools or content operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool: to get an overview of all tool groups and their accessibility. It implicitly differentiates from search_tools and invoke_tool by mentioning them as part of the on-demand path, but it does not explicitly state alternatives or exclusions. This is slightly below the 'explicit when-to-use' standard, but the context is still clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It adds useful context that the node is returned, editable, and must be placed manually, and that it is structurally-valid. However, it doesn't disclose side effects, authentication needs, 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence that is front-loaded and efficient. Every clause adds meaning: what is built, where it comes from, what to do with it. No filler or redundant statements.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a factory tool, it covers creation, editing, and placement. It correctly defers valid types to list_elements. It could mention return type details or validation behavior, but the schema fills in parameter specifics, making it complete enough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with rich descriptions, especially for 'opts' which enumerates all fields and explains 'align' behavior. The description reinforces the role of specials/style. This goes beyond a plain schema listing.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Build' with the resource 'element node' and clarifies that it comes from the builder factory. It clearly distinguishes from sibling tools like new_section and update_page_element by describing the creation of a node that must be placed afterward.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states the workflow: build the node, edit it, then place it in a section's children. This provides clear context for when to use it (creating new elements), though it doesn't explicitly name alternative tools or exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses a key behavioral trait: the CMS api-key auth requirement. The term 'query' implies a read-only operation, and the mention of paging/filter/sort provides insight into behavior. It doesn't mention side effects (likely none) or errors, but for a read query this is reasonably transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: the first states the core action, the second lists features and auth. Front-loaded with purpose, no redundant text, every sentence carries meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the moderate complexity (5 params, no output schema), the description covers the essentials: what it does, auth, and key capabilities. It doesn't describe the return format explicitly, but 'query records' implies a record list, and the schema covers parameters. This is sufficient for a read tool, though a note on response shape would be helpful.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds only a summary of capabilities ('paging + an optional where filter and order_by sort') without new details beyond the schema. The schema already provides thorough explanations and examples for each parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function with a specific verb ('Query'), a resource ('records from a collection'), and a key qualifier ('by table name'). It distinguishes this from sibling tools like list_collections and get_collection, which operate on collections rather than records.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description establishes clear context: it is for querying records with optional filters and sorting. It doesn't explicitly name alternative tools or exclusions, but the sibling context makes it obvious. The auth note adds a practical usage consideration. A 4 reflects the clear context without explicit when-not or alternative guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that the tool reads version content and writes it back, and the tip about saving the current content first implies the destructive overwrite of current state. It does not mention permissions or error handling, but the provided behavior context is meaningful for a mutating tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exactly two sentences, front-loaded with the core action, and includes a useful tip without any fluff. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 2-parameter tool with no output schema and no annotations, the description covers the main behavior, default parameter behavior, and provides an undo tip. It lacks details on return values or error conditions, but the description is sufficiently complete for an agent to use the tool safely and effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 repeats the 'omit version_id' behavior that is already in the schema and adds no new parameter details. It does not enhance the understanding of cms_file_id beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Roll a CMS file back to a saved version'), identifies the resource ('CMS file'), and explains the one-step mechanism ('reads the version's content and writes it back'). It clearly distinguishes itself from siblings like save_file_version and get_file_versions by describing the combined read-write behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: it explains how to use the tool (with or without version_id) and gives a practical tip about creating an undo point before restoring. However, it does not explicitly name alternatives or when-not-to-use scenarios, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It adds the key behavioral note 'No component param needed' and gives filter examples, but lacks disclosure of return format, pagination, limit behavior, or error handling. It is not misleading, but it does not provide rich behavioral context 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is succinct and front-loaded with the core purpose. Examples are presented as a bulleted list, making it scannable. Every sentence contributes to understanding the tool's usage, with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the 10 parameters and no output schema, the description handles complexity well by providing illustrative examples for common use cases. It does not explicitly explain the return value or default limit, but the tool's purpose is clear and the schema covers the limit. Minor gaps prevent a 5.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 value by showing concrete usage examples for multiple parameters (type, custom_class, text, has_bind, has_events, has_custom_class), clarifying how to combine filters effectively. This goes beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Search/filter elements within a global source.' It further differentiates from siblings like search_page_elements by noting 'No component param needed,' making the scope explicit. Examples reinforce the specific resource and operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool and includes practical examples for filtering by type, class, text, and flags. It hints at an alternative (component-based search) with 'No component param needed' but does not explicitly name alternatives or exclusion conditions, which keeps it slightly below a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses the underlying mechanism (bge-m3 embeddings, cosine similarity) and specifies the return fields, which gives the agent a clear expectation of behavior. It does not mention rate limits, errors, or non-determinism, but for a search operation the provided information is solid.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, each earning its place: one states what it does, one gives when to use it, and one lists the returned fields. It is front-loaded with the verb and resource, and contains no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only search tool with no output schema and no annotations, the description covers the essential context: purpose, usage criteria, and return content. It misses edge cases like no results, but the provided information is sufficient for an agent to select and invoke the tool correctly in most scenarios.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and both parameters already have meaningful descriptions. The tool description reinforces the 'natural-language' intent for the query parameter but does not add new syntax, formatting, or behavioral details beyond the schema, so it stays at the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Semantic search across the theme marketplace', which clearly states the action (semantic search) and resource (theme marketplace). The specificity is further reinforced by a concrete example and the list of returned fields, distinguishing it from simple listing tools like list_themes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Use when the brief is a natural-language description... not just keywords', providing a clear when-to-use condition and an implicit when-not-to-use (keyword queries). However, it does not name an alternative tool or exclude other search tools explicitly, so it lacks full alternative guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the mutating nature with 'upsert' and imposes a strict confirmation requirement. It doesn't describe return values or detailed side effects, but the core behavioral constraints are clear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences: statement of purpose, entry field listing, and critical usage instruction. No redundancy, information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is adequate for a mutation tool with one clearly-specified array parameter and a referencing prerequisite tool. It lacks return value details, but that's less critical; the strong process requirement is commendable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for each property, so the description doesn't need to compensate. It adds a compact overview of the required entry structure but offers little 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'update' with resource 'multilingual contents', and clarifies it is an 'upsert'. It distinguishes from sibling tools like update_global_source_element by focusing on multilingual content entries rather than the global source record or individual elements.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit and mandatory usage context: must read existing contents via get_global_source_contents first, show the user what will change, and obtain explicit confirmation. However, it doesn't explicitly state when not to use this tool or contrast with alternatives like update_global_source(es).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden. It discloses partial-update semantics and prerequisites, but does not explicitly warn that passing variations replaces the entire variation set or that images are replaced, though the schema does. This is useful but incomplete.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with the core action, followed by the two most important usage nuances. No filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 7-parameter update tool with nested variations and no output schema, the description covers the tricky aspects (variations workflow, image sourcing). It leaves simple params to the schema and does not explain return values, but enough is provided to select and invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although schema coverage is 100% (baseline 3), the description adds usage-level meaning: product_id plus only changed fields, variations for price/stock changes, and hosted-URL constraints. This goes beyond the schema's per-field descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it updates an existing product and emphasizes partial updates ('Pass product_id + only the fields to change'), distinguishing it from create/delete sibling tools. The verb-resource pairing 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.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides concrete when/how guidance: partial updates, the need to call get_product before editing variations, and the CDN URL requirement for images with pointers to search_images/upload_images. It lacks explicit mention of alternatives like set_product_published for publish-only changes.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of behavioral disclosure. It does convey that this is a partial update ('fields to change'), which is useful. However, it does not mention permissions, potential side effects, reversibility, or the response format, leaving notable gaps for a mutating operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence containing exactly the necessary information: what the tool does and how to use it. There is no redundant phrasing or wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple update tool with five well-documented parameters, the description covers purpose, mutable fields, and partial-update behavior, which is sufficient for selecting and invoking the tool. No output schema exists, but the return value is not essential to know beforehand. Missing error-handling details are a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 100% coverage for all five parameters. The description adds the partial-update semantics: only fields passed are changed, and it maps the 'visibility' concept to the hidden boolean parameter. This is meaningful context beyond the schema's individual field descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with a specific verb and resource—'Update a product category'—and enumerates the mutable fields: name, image, description, or visibility. This clearly distinguishes it from sibling tools like create_product_category, delete_product_category, and list_categories.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The instruction 'Pass id + fields to change' gives clear guidance on how to invoke the tool and implies it is for modifying an existing category. It does not explicitly name alternatives for create/delete operations, but the context is sufficient for an agent to know when it applies.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden and adds useful behavior: articles are auto-filed under the default category, IDs and slugs are backend-generated, and image URLs must be hosted. It does not mention response format or publish/draft status, but it is fairly transparent for a create operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but not overly long, front-loading the core purpose and then giving pipeline details. The phrase 'Built via dashboard command pipeline' is somewhat vague, but the overall structure is efficient and each sentence adds relevant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description covers the tool's purpose, key parameters, and prerequisite relationships with sibling tools. It lacks explicit return-value details or whether the article is immediately published, but it is reasonably complete for a create operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already covers all parameters at 100% with descriptions, so the baseline is 3. The description adds value by explaining where category_ids come from, emphasizing that image URLs must be hosted, and clarifying that summary is optional—all beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Create a blog article') with the exact resource and purpose ('so blog/post pages have content'), naming concrete page types. This clearly distinguishes it from sibling tools like update_article, delete_article, and list_articles.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context and directs the agent to source category_ids from create_blog_category and use hosted images from search_images/upload_images. However, it does not explicitly mention when not to use this tool (e.g., for editing an existing article, use update_article), so it stops short of full when/when-not coverage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that the tool creates a category, returns the new ID, and requires the image to be a hosted URL. It also notes that post-list/blog pages bind to the category, providing useful integration behavior. It lacks detail on permissions or error handling but adds meaningful 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the main action. It efficiently communicates the purpose, return value, downstream usage, and an image constraint without redundancy or unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple 3-parameter create tool with no output schema, the description is complete. It explains the return value, how to use it with create_article, and a parameter constraint. The integration with post-list/blog pages gives sufficient context for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so each parameter already has a description. The tool description only reiterates the image URL requirement, which is nearly identical to the schema's 'Hosted image URL'. No additional syntax or format details are provided beyond the schema, so it meets the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a blog/article category', using a specific verb and resource. It distinguishes this from sibling create_product_category by specifying 'blog/article', and explains the returned category id's role with create_article, which further clarifies its purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context by explaining to pass the returned ID to create_article's category_id, showing when to use this tool for grouping posts. It does not explicitly mention alternatives like create_product_category, but the 'blog/article' qualifier makes the intended domain clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral burden. It discloses the two modes, the token-saving rationale, and the include_guide behavior. It does not detail response format or error handling, but for a straightforward read-only tool this is adequate and adds context beyond a simple 'get' statement.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded: a one-sentence purpose followed by bullet-pointed mode details. Every sentence earns its place, and the structure makes the two modes and include_guide flag easy to parse. No fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool with two optional parameters and no output schema, the description fully covers the tool's behavior: default return all fields, filtered return specific fields, and include_guide behavior. It explains what the tool returns and how to invoke it, making it self-contained and complete for the given complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for both parameters, with detailed schema descriptions already explaining fields (enum values, omit for all) and include_guide (first-call guide). The description adds minimal extra semantics, such as 'saves tokens', but does not materially enhance parameter understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get custom code of the site (CSS/JS)' with a specific verb and resource. It also explains two modes (default all fields vs. field filter), distinguishing it from sibling tools like update_site_custom_code, and making its purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use each mode: default returns all 4 fields, field filter saves tokens when only CSS or JS is needed, and include_guide=true is recommended on the first call. However, it does not explicitly mention alternatives or when not to use this tool relative to other getters like get_global_source_element or get_page_source.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that the tool returns 'metadata only', which is a key behavioral trait. However, it doesn't mention pagination behavior, sorting, or any side effects, leaving transparency basic but not absent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, front-loaded with the action and resource, no redundancy. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple list operation with three optional, well-documented parameters and no output schema, the description plus schema is sufficient. It covers the scope and points to the right sibling for richer data.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%: all three parameters (page, limit, status) have descriptions, including status enum values. The description adds no extra parameter meaning, but the baseline of 3 is appropriate since the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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 and scope ('orders of the site'), adds the qualifier 'metadata only', and explicitly distinguishes it from the sibling tool get_order by noting that full details including items are covered there.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly tells when to use this tool (for metadata-only listing) and when to use an alternative ('Use get_order for full details including items'). This directly answers when-to-use vs. alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses that fetches are parallel, capped at 5, and that it synthesizes common themes. It also details the output fields (subject, style, palette, etc.). It lacks disclosure of failure handling or auth requirements, but the provided behavioral details are substantial and accurate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is moderately long but well-structured: it starts with the core purpose, then usage, then the output field list. The field list is detailed and necessary for guiding the image analysis. Each sentence contributes useful information, though the bullet list is extensive.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Since there is no output schema, the description appropriately explains the output format (fields like subject, style, palette, etc.) and the synthesis step. It covers the tool's complexity and provides enough context for an agent to invoke it correctly. Minor gaps like error handling are not critical for initial use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 value by explaining the cap of 5 aligns with the schema's maxItems, and it contextualizes 'max_size_mb' indirectly with 'keep context manageable.' It also enriches the 'urls' parameter by describing the per-image output derived from them, which goes beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Batch fetch multiple image URLs in parallel', clearly stating the action (fetch), resource (image URLs), and mode (batch/parallel). It distinguishes itself from the sibling 'read_image' by focusing on multiple images and synthesis of themes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit guidance: 'Use when comparing several references or extracting motifs across a set.' This conveys the intended context. It also notes the 5-image cap, which is a practical usage constraint. However, it does not mention when not to use it or explicitly contrast with alternatives like read_image.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full disclosure burden. It reveals that the scan covers every string field in the source tree (config.src, style.background-image, etc.) and CSS url(...) references, including a 'wide net catches all variants' caveat—genuine behavioral insight beyond the schema. It does not explicitly state side-effect freedom (e.g., read-only), but the scanning nature and return description make the read-only behavior implicit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences: first states the action and output, second gives use cases, third explains the technical scanning behavior. No filler or redundant wording.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of an output schema, the description still explains the return value as a unique list of image URLs with element usage. It also clarifies the broad scanning behavior and lists practical use cases, making the tool's behavior easily predictable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All four parameters are fully described in the schema (100% coverage), giving a baseline of 3. The description adds no extra parameter-specific guidance beyond noting the output shape, which does not go beyond the schema's parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb 'Scan' and names the exact resources (page sources, global sources, global sections) and the return behavior (a unique list of image URLs with element usage). This clearly distinguishes it from sibling tools like search_images or list_image_elements, which focus on search or element listing rather than cross-source auditing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly lists four concrete use cases (image audit, finding broken/duplicated CDN URLs, bulk replace planning, theme migration), giving clear context for when to invoke it. It does not name alternatives or exclusions, so it stops at 4 rather than 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses the critical behavioral trait: the PATCH replaces the whole schema, so omitting a column drops it. It also notes that system columns are automatically included, which is essential for predicting side effects. This exceeds the burden without annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences: the first states the purpose, the second explains the key behavior. It is front-loaded, concise, and every sentence carries essential information with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is complete for a two-parameter tool with no output schema. It explains the full behavioral contract—how the tool works, what gets replaced, and the consequence of omission. It also implicitly covers prerequisites by stating it reads the current schema internally. No missing critical information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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, including the 'columns' field as 'The FULL set of custom columns.' The description reinforces this by saying omitting a column drops it, but this adds minimal semantic value beyond the schema's explicit wording.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb and resource: 'Add or change a collection's custom columns.' It distinguishes itself from sibling tools like create_collection, delete_collection, and update_page by targeting the specific sub-resource of custom columns.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for adding/changing custom columns and explains the mechanism (reads schema, PATCHes with replacements), but it does not explicitly state when to use this vs. alternatives or mention exclusions. It lacks direct guidance like 'To create a new collection, use create_collection.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It mentions the critical side effect of auto-deploying to the bundle service after update. However, it does not explicitly warn that the entire file is overwritten or address risk/reversibility, leaving some gaps for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise, front-loaded sentences. The main purpose is first, followed by usage guidance and a side-effect note. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool with no output schema and no annotations, the description covers purpose, when to use, alternative, and a key side effect. It is sufficiently complete for an agent 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.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with parameter 'content' already described as 'Full JS code content'. The description reinforces 'FULL' but adds little semantic value 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool writes the FULL HTTP function file content, distinguishing it from edit_http_function which is for targeted edits. The verb 'Write' and resource 'HTTP function file' are 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.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use this tool (new features, major refactors, changes touching multiple functions) and when to use the alternative (edit_http_function for small targeted edits). This provides clear decision guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It does an excellent job: it reveals the two-step dry-run/apply mechanism, mandates explicit user approval, cautions that skipping confirmation risks data loss, and specifies merge rules (shallow merge for style/config/specials, replace for events/bindings). This goes far beyond a generic update description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately structured with clear steps and front-loaded purpose. It is dense but not bloated. The main redundancy is that the 'IMPORTANT' section restates the confirmation requirement from STEP 2, but given the data-loss risk, this repetition is acceptable and reinforces the critical safety message.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the operational lifecycle (dry-run, diff, confirmation, apply), merge rules, and safety warning. The schema fully documents parameters, so no gaps there. It does not describe the return value beyond 'per-element diff,' but with no output schema this is acceptable. It is missing some details like error handling, but overall it is complete enough for a complex batch operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 100% of parameters, so the baseline is 3. The description adds valuable merge-rule context for the updates field and explains dry_run's role. However, it states 'dry_run=true (default)' while the schema says 'Defaults to confirm_mode setting,' a direct contradiction that undermines the parameter's default semantics. This mixed contribution keeps the score at 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Batch update multiple elements in one page,' which is a specific verb (batch update), resource (elements), and scope (one page). This clearly distinguishes it from siblings like update_page_element (singular) and update_page (page-level). The two-step process further clarifies the tool's unique behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit step-by-step usage instructions, including the requirement to show diffs and get user confirmation before applying. While it does not explicitly name alternatives like update_page_element or update_page, the 'Batch update multiple elements' phrasing implies when to use this tool. It also warns about data loss when skipping confirmation, which is a strong usage guideline.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full responsibility for behavior disclosure. It thoroughly explains that this is destructive ('replaces the ENTIRE page source'), requires user approval, and has a safeguard ('blocks if new source is <50% of existing size'). This is exemplary transparency for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose, then uses a numbered 'IMPORTANT' list to convey preconditions and safety. It is longer than strictly necessary, but each sentence serves a functional role, and the structure makes the critical caveats scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 3-parameter tool with no output schema and no annotations, the description provides strong context: purpose, mandatory preconditions, destruction scope, and a safety rule. It lacks only an explicit mention of when to use this instead of related update tools, but overall it is adequate for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds limited extra parameter meaning—notably that 'source' refers to the full page source JSON and that the safeguard applies to size—but does not clarify 'page_id' or 'custom_code' beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb-resource pair: 'Directly update the full page source JSON.' It clearly distinguishes this from sibling tools by emphasizing 'full page source' and 'replaces the ENTIRE page source,' contrasting with partial update tools like update_page_element.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit preconditions and a mandatory sequence: read existing source with get_page_source first, show the user what will change, and obtain explicit confirmation. It warns against use without approval and explains the tool's scope, but does not explicitly name alternatives such as update_page_element for partial edits.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and reveals key behaviors: 'NO network,' 'can't time out,' re-id'ing to avoid collisions, quick validation, and non-blocking warnings. It does not mention side effects or return values, but the most critical operational traits are transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise, front-loaded sentences with no filler. Each sentence provides distinct, essential information: what it does, its key constraints, and how to construct the input.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple 2-parameter tool with no output schema, the description covers the critical operational context (no network, durability, validation behavior) and workflow linkage (new_section). It could mention the follow-up commit step (commit_page_draft), but the core usage is clear enough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 value by instructing to build the section with 'new_section' and noting that sections are re-id'd, which clarifies parameter usage beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Append') and resource ('local page draft') with a clear scope ('ONE section'), and it distinguishes itself from the sibling tool 'add_section' by emphasizing the local, no-network nature.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies when to use this tool: as a durable per-section cache step that avoids network timeouts. It also directs the agent to build sections with 'new_section,' providing a concrete prerequisite. However, it doesn't explicitly state when not to use it (e.g., when network access is acceptable).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden for behavioral disclosure. It reveals a critical behavior: 'WITHOUT reading the existing content first,' which alerts the agent that this is a blind append/prepend operation. It also clarifies the additive nature, though it does not mention auth requirements, rate limits, or exact return values.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, front-loaded with the core action, followed by usage context and an alternative. Every sentence earns its place, with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and no output schema, the description provides essential decision-making information: operation type, usage scenario, and an explicit alternative. It is sufficient for an agent to select and invoke the tool correctly, though it omits potential error cases and return format.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 some context by referencing CSS/JS/script tags as examples of 'code' and implies the 'position' parameter via 'append or prepend.' However, it doesn't add deeper semantics about the field enum or edge cases beyond what the schema already defines.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verbs ('Append or prepend') and names the resource ('custom code field'), clearly distinguishing it from sibling tools. It explicitly states 'For full rewrites, use update_site_custom_code instead,' which differentiates it from the update tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states when to use: 'Use this when you need to ADD new CSS rules, JS code, or script tags — no need to read first.' It also provides a clear alternative ('For full rewrites, use update_site_custom_code instead'), giving both positive and negative guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the disclosure burden. It transparently explains the two-step dry_run safety mechanism, that validation errors block the save, and the required source format. It does not mention auto-enabling data sources for special page types (covered in schema), but provides strong behavioral guidance.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loaded with the core purpose, followed by critical safety workflow and source requirement. Every sentence earns its place, with no redundant fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given a complex 7-parameter tool with a rich schema but no output schema, the description covers the essential workflow and validation behavior. It does not describe return values, but the stepwise safety info and source requirements make it largely complete for an AI agent to operate effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds meaning beyond the schema: it explains the dry_run validation/save sequence and directs users to build sections with new_section, clarifying the source parameter's structure and workflow. This adds practical parameter usage context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a brand-new page AND set its full content source in one step,' combining a specific verb and resource. It differentiates from sibling tools like create_page by emphasizing the one-step source setting and 'brand-new' versus update semantics.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool: when creating a page with full content source in one step, with a two-step dry-run workflow. It mentions new_section as a companion tool but does not explicitly state exclusions or alternatives (e.g., use update_page for existing pages).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of behavioral disclosure. It reveals that collections start with system columns and highlights the platform limitation about no direct record insertion. However, it does not mention permission requirements, potential errors, or reversibility, so it stops short of full transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences with no wasted words. The core action is front-loaded, followed by a useful note and a cross-reference. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the essential creation workflow and importantly warns about the record-write limitation, which is critical for the overall data management context. It does not describe the return value or error scenarios, but given the schema's completeness, this is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with descriptions for all three parameters (name, columns, table_name). The description's mention of 'pass columns to add custom fields' largely repeats what the schema already says, adding no new parameter-level details or constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Create a new collection (custom data TABLE)', using a specific verb and resource. It distinguishes from sibling tools by clarifying that a collection is a custom data table, and the parenthetical about system columns helps define its behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use this tool (to create a collection) and when not to: 'to WRITE records into it, use an HTTP function... the dashboard has no direct record-insert API'. It even points to get_http_function as the alternative, giving clear usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses meaningful behavioral details: 'type is a KIND ... mapped to the numeric backend type' and warns about empty-title publishing without seo. However, it does not mention possible side effects, permissions, return values, or error conditions, leaving gaps for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core action, and every sentence earns its place. The alternative tool and key caveat are packed efficiently without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description plus the rich schema (100% coverage, detailed slug/type notes) covers the main invocation concerns. It lacks an explicit return value statement (no output schema), but for a create tool with an empty page and alternative guidance, the provided context is largely complete. Could be improved by noting what is returned.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds beyond schema by explaining that 'type is a KIND' underlying numeric mapping and why 'seo' matters (avoids empty-title publishing), which gives agents extra semantic context not present in the structured fields.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a new (empty) page' – a specific verb and resource. It also distinguishes the tool from sibling 'build_page' by noting the empty-page scope, so the purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance is provided: 'For a page with content use build_page instead' names the alternative and gives the condition for using this tool. Additionally, the warning to 'pass seo so it doesn't publish with an empty title' instructs on a prerequisite for safe use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses key behaviors: backend generates id/slug, publishes the product, auto-creates a default variation, and requires hosted URLs. It does not cover auth/error cases but sufficiently reveals side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact, with three sentences covering purpose, usage modes, and key constraints. Every sentence adds value, and the line breaks for simple/advanced usage improve readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 11 parameters and no output schema, the description provides high-level workflow context and prerequisites (hosted images, category IDs). It does not detail return values, but the schema already covers parameter specifics, making this adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed descriptions, so baseline is 3. The description adds conceptual meaning by grouping parameters into simple vs. advanced usage and explaining relationships (e.g., name+price for simple, attributes+variations for multi-SKU), which goes beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a product for storefront merchandise, with a specific verb and resource. It distinguishes from siblings like update_product/delete_product by emphasizing creation and the resulting published product.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit usage guidance: 'Simple use' and 'Advanced use' with parameter combinations, and instructs to obtain hosted URLs from search_images/upload_images. It implies but does not explicitly name alternatives like update_product for modifications, so a 4 is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full burden. It discloses a non-obvious behavioral trait: the output is a structural blueprint, not an exact reproduction ('Not a 1:1 clone'), and it lists exactly which elements are captured. This provides solid, actionable expectations for the agent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no superfluous text. The action and resource are front-loaded, and the key caveat ('Not a 1:1 clone') is placed at the end, ensuring each sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers input, processing, output scope, and a downstream step (new_section). With no output schema, it could detail the blueprint's exact structure more, but for a one-parameter tool with clear intent, it is nearly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents the single parameter with 100% coverage ('Raw HTML to analyse'). The description adds value by qualifying the input as 'reference HTML', implying it's a sample for design extraction, and by linking the output to rebuilding sections, which enriches the parameter's purpose.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description identifies a specific verb ('Parse'), a clear resource ('reference HTML'), and a distinct outcome ('structural blueprint' with explicit list of elements). It also differentiates from a simple clone by stating 'Not a 1:1 clone', which clarifies what the tool does not do.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by stating 'Parse reference HTML' and suggests a concrete workflow: 'you can rebuild as BuilderX sections with new_section'. It does not explicitly mention when to avoid this tool or compare with ingest_url, but the context makes the intended scenario clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that 'Arguments are validated before running', a key behavioral trait. It also reveals its fallback role ('not loaded natively') and discovery method, but does not describe side effects or error handling, which are delegated to the invoked tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the primary action, then a usage hint. Every clause earns its place: the action, the discovery pointer, a validation guarantee, and the when-to-use. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a generic dispatcher with no output schema, the description is fairly complete: it explains what, when, and a key behavior. It does not explain return format or error propagation, but since the tool can invoke any tool with varied outputs, that is understandably absent. The coverage is adequate for an agent to select and use it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds value by specifying that the name must be 'exact' and pointing to `search_tools` for valid names/schemas, enriching the meaning of the `name` parameter beyond the schema. The `arguments` parameter is well-covered by the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Run any WebCake tool by exact name with its arguments', giving a clear verb ('Run'), resource ('any WebCake tool'), and scope. This distinguishes it from sibling tools, which target specific functions, by establishing itself as a generic invocation tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit usage context with 'Use this for tools that are not loaded natively', telling the agent when to invoke this meta-tool. It also directs discovery via 'discover names + schemas via search_tools', but does not explicitly name alternatives or exclusions, though the 'natively' phrasing implies avoiding it for native tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the return fields (name, phone, email, order_count, etc.) and the search behavior for `term`. However, it does not mention pagination edge cases or sorting, leaving some behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose, and no unnecessary wording. Every sentence contributes meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema or annotations, the description covers purpose, return fields, and the alternative lookup tool. It is mostly complete for a simple list/search tool, though the phrase 'segment' is somewhat vague.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with page, term, and limit all described. The description reinforces the term parameter's search scope but adds no new parameter semantics beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb+resource ('List/search the site's customers') and clearly differentiates from sibling find_customer by specifying exact lookup use cases. The scope is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly tells when to use this tool (browse or segment) and when to use the alternative find_customer for exact id/phone/email lookup, providing a clear when-not and alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the transparency burden. It discloses the output structure (grouped by category, one-line summary, container flag) and the scope (only element types placeable on a page), which helps set expectations. It does not explicitly state that the operation is read-only, but the verb 'List' implies a non-mutating action, and no side effects are suggested.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that front-loads the core function (list element types) and adds useful output details without fluff. Every phrase contributes to understanding the tool's purpose and result.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple zero-parameter listing tool without an output schema, the description adequately covers the return format (categories with one-line summaries and container flags). It does not mention ordering or pagination, but such details are unlikely to be critical for this operation. The description is complete enough for an agent to know what to expect.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema provides complete coverage by definition. The description does not need to add parameter semantics, and it does not attempt to introduce any. The baseline score of 4 applies for zero-parameter tools.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists all BuilderX element/component types placeable on a page, grouped by category with summary and container flag. This distinguishes it from sibling listing tools like list_pages or list_global_sources. It uses a specific verb and resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
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 discover element types available for page composition. It provides clear context about the scope (element types placeable on a page) but does not explicitly mention alternatives or exclusions. Sibling tools like list_global_sources or search_page_elements are not referenced.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of explaining behavior. It discloses return fields, scope, and an important exclusion (global_sections). It does not explicitly say 'this is a read-only operation,' but the verb 'Find' and the context make that clear. It adds useful behavioral context beyond the schema, though it stops short of noting pagination or rate-limit behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no filler. The first sentence states the main purpose and output fields; the second gives a workflow recommendation and a caveat. It is concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description compensates by listing return fields (element_id, alt, src, field path). It also ties the tool to a broader workflow and notes the global_sections limitation. It omits pagination/limit behavior, but that is captured in the schema. Given the simplicity of a list operation, this is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema coverage is 100% with detailed parameter descriptions. The tool description does not add new parameter-level semantics, but it does align with the 'scope' parameter by mentioning 'pages + global sources.' Since the schema already explains limit, scope, page_id, and only_missing_alt, the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Find') and resource ('image elements across pages + global sources'), lists key output fields, and explicitly notes that global_sections are excluded. This differentiates it from sibling tools like search_page_elements or read_image by framing it as a listing/scan operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives an explicit workflow directive: 'Use as the first step before generating alt text via vision (read_image) and writing back with set_image_alts.' It also mentions the global_sections read-only limitation, which tells the agent when results will be incomplete and why.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses that publishing snapshots all current page sources, affects every saved page, and that dry_run controls whether it actually publishes. It doesn't mention potential side effects like downtime, but the safety mechanism is well explained.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loaded with the main action, then a key scoping note, then the safety mechanism. Every sentence adds value with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool with no output schema, the description covers purpose, scope, and safety. It doesn't explain return values, but that's not necessary for a publish action. The description is sufficient for an agent to decide when and how to use it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already describes the single parameter dry_run with 100% coverage, but the description adds meaningful context by explaining the default value (true) and what each value does. This goes beyond the schema's brief 'Preview (true) or publish for real (false)'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function with a specific verb and resource: 'Publish the whole site live.' It also distinguishes itself by explicitly noting that this is a site-level operation, not per-page, which differentiates it from any potential publishing-related siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context on when to use: when you want all saved pages to go live, and clarifies it is not per-page. It also recommends the two-step safety flow with dry_run. However, it doesn't explicitly name alternative tools or situations where this tool should be avoided, though no direct siblings exist.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals important non-obvious behavior: 'Groups updates by source so each source is fetched + saved exactly once' and the auto-detection of alt_path. These add significant context beyond what a bare write tool would imply. It does not mention whether it overwrites existing alt text or handle partial failures, but the given details are substantive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only two sentences plus a workflow and one clarification. It is front-loaded with the primary purpose, followed by an efficiency note, a concrete workflow, and a key parameter behavior. Every sentence serves a distinct purpose and there is no fluff or repetition of schema content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (nested items array, multiple sources, grouping behavior), the description covers the essential context: the overall workflow, batching behavior, and alt_path auto-detection. It does not describe return values or error handling, but since there is no output schema, that is partially excused. The description is thorough enough for an agent to use the tool correctly in a typical alt-fill pipeline.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already covers all parameters with descriptions, giving a baseline of 3. The description adds meaningful semantics beyond the schema, particularly for alt_path: 'If alt_path is omitted, it is auto-detected via the same probe used by list_image_elements.' It also clarifies the grouping of items by source, which is not explicit in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Batch-write alt text for image elements across pages + global sources.' It uses a specific verb (write), identifies the resource (alt text for image elements), and explicitly distinguishes its batch scope from single-entity tools like update_page_element. It also implies its position in the workflow, making it unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear workflow: list_image_elements → read_image → describe → set_image_alts(items), which tells the agent when to invoke this tool (after descriptions are ready) and how it fits with sibling tools. It also notes that updates are grouped by source, implying the benefit over per-source updates. However, it does not explicitly state when NOT to use it or name alternative tools for single updates.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of behavioral disclosure. 'Show' clearly implies a read-only operation, and the listing of what information is included gives the agent a good sense of the tool's return content. It does not explicitly state 'no side effects', but the non-mutating nature is strongly evident from the verb.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences, front-loaded with the primary purpose and immediately followed by actionable guidance. Every word contributes value; there is no fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter context getter with no output schema, the description explains what will be shown and why it matters, making it fully self-sufficient for an agent to select and invoke correctly. The context about confirming the correct site is particularly useful given the large roster of sibling tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, and the baseline for zero-parameter tools is 4. The description adds no parameter-specific details because none exist, which is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Show') tied to a clear resource ('current connection context') and enumerates its contents (site_id, API URL, session, account info). This makes the tool's purpose unmistakable and distinguishes it from all sibling tools, none of which claim to expose current connection state.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'Call this first to confirm you're working on the right site' provides explicit when-to-use guidance. It does not mention alternatives or exclusions, but for a context-checking tool, the 'first call' directive is sufficient and clear enough to guide an agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses the exact line format of the returned tree, including ID, type, text, class, events, bindings, and children_count, which gives the agent concrete expectations. It also mentions the performance behavior ('faster lookup') for the optional parameter.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: one sentence for purpose, one for output format, and one for usage hint. Every part carries actionable information with no fluff, and the front-loaded 'Get full detail' immediately clarifies the operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given there is no output schema, the description fully specifies the return format and how to use the optional parameter. For a read-only detail tool, this is complete: it tells the agent what to expect (the tree lines) and how to optimize lookup, with no missing critical context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides descriptions for both parameters (100% coverage). The description adds extra semantic value by explaining when 'component' should be omitted (if list_global_sources was already called) and reinforcing its role as a lookup hint, which goes beyond the schema text.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Get' with a clear resource ('full detail of a global source') and specifies the output as 'compact tree view showing all elements'. This clearly distinguishes it from sibling tools like get_global_source_element or get_global_source_contents.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives practical guidance on the 'component' parameter ('Provide component for faster lookup; omit if you already called list_global_sources'), implying when to use the tool effectively. However, it does not explicitly contrast with alternative retrieval tools, so it lacks explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations to rely on, the description carries the burden of disclosing behavior. It clearly states that the tool returns a summary/overview (counts and class names) and does not mention any mutations or side effects, implying a safe read operation. It could go further by noting whether this is the entire source or just a summary, but the provided information is sufficient for basic understanding.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only two sentences: the first states the output content, the second gives usage guidance. It is front-loaded, contains no filler, and every sentence adds value. This is an exemplar of concise, structured tool documentation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple tool with one parameter and no output schema. The description explains exactly what the tool returns (section count, element type counts, custom CSS classes) and gives contextual guidance for the next step. It is complete for the tool's complexity and fits well within the sibling context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% because the single parameter page_id is documented in the schema. The description does not add any additional meaning or constraints about the parameter, sticking to the baseline where the schema provides all necessary semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Get' with a clear resource 'page source overview'. It enumerates concrete outputs (section count, element type counts, custom CSS classes), which clearly distinguishes it from siblings like get_page_schema or list_elements. It also names search_page_elements, showing awareness of its complementary role.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use this tool ('Use this first') and provides the specific alternative for the next step ('then use search_page_elements to find specific elements'). This is clear, actionable guidance for an agent deciding between tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses a key behavioral trait—that the response excludes HTML content—which sets expectations for the return payload. However, it does not mention pagination behavior or other potential side effects, though the schema does cover parameters.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences that are front-loaded with the action. Every word earns its place, avoiding redundancy and providing essential context without unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list operation with optional filters and no output schema, the description is fully sufficient. It explains the returned scope (metadata only), directs to get_article for full content, and the schema handles parameter documentation, making the tool complete for its intended use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% coverage with descriptions for all three parameters (page, limit, category_id). The description adds no additional parameter-specific meaning beyond what the schema already conveys, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists blog articles and specifies it returns metadata only, without HTML content. This distinguishes it from the sibling get_article, which provides full content, making the purpose and scope immediately clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly directs users to use get_article for full content, providing a clear alternative. It implies that this tool is for metadata-only needs, giving a distinct use case versus its sibling.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that the tool returns only summaries with specific fields, which is a meaningful behavioral detail. It also implies a read-only operation via the verb 'list'. Without pagination or error details, it is not a 5, but it provides solid transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, compact sentence that front-loads the main action and scope, then provides necessary output details. There is no unnecessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple, parameterless list tool, the description is complete. It explains what the tool does, what it returns, and the scope ('current site'). No output schema is needed because the description lists the fields. There is no missing information that an agent would need to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema is empty. The description does not need to add parameter explanations. According to the rubric, a zero-parameter tool gets a baseline of 4, and the description adds nothing to contradict that.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List'), the resource ('local page drafts'), and the scope ('for the current site'). It also specifies the return format ('summaries only' with a list of fields), which distinguishes it from sibling tools like get_page_draft or list_pages.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The context is clear: this tool is for listing page drafts, not individual draft details or committed pages. However, it does not explicitly mention when not to use it or name alternatives, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full responsibility. It discloses that the tool returns only metadata and not page source, which makes its behavior predictable. It does not mention potential edge cases like pagination or draft pages, but these are less critical for a simple list operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is front-loaded with the action and resource, and the parenthetical qualifier adds crucial detail without wasted words. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with zero parameters, no output schema, and no annotations, this description fully covers what the tool does and what it returns. No additional context is necessary for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 does not attempt to add parameter details that do not exist, and the schema is already empty.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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 ('pages of the site'), and clearly distinguishes from siblings by adding 'metadata only, without source'. This differentiates it from content or source retrieval tools like get_page_source and list_page_contents.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear context for when to use the tool (listing page metadata), and the 'without source' qualifier implies when not to use it (when source is needed). However, it does not explicitly name alternative tools or provide exclusion criteria, so a small gap remains.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses return fields and that it lists all custom themes. As a read operation, it is reasonably transparent, though it does not explicitly state side effects or permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that front-loads the purpose and includes essential return information without any wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple zero-parameter list tool with no output schema, the description fully captures purpose and return contents. No additional context is necessary.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With zero parameters, the description has no need to elaborate on them. The baseline of 4 applies since the description still adds value by clarifying scope and output.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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 ('all custom themes of the site'), clearly distinguishing it from sibling tools like list_template_themes and semantic_search_themes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It clearly states this is for site custom themes, implying when to use it. However, it does not explicitly mention alternatives or exclusions, though the context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden. It states the exact return value and that it's a valid page source, which is transparent for a simple factory-like tool. It doesn't mention side effects or prerequisites, but for a zero-parameter 'return' tool, this is sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences, front-loaded with the literal output format and ending with actionable next steps. Zero wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no params, no output schema, no annotations), the description fully covers the return value and the surrounding workflow. It is contextually complete for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, and schema coverage is 100% vacuously. The description doesn't need to explain parameters; baseline for zero-param tools is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as returning an empty valid page source with the exact structure { sections: [] }, and it names the workflow companions (new_section, build_page), distinguishing it from siblings like create_page or update_page.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides a mini-workflow: start with this skeleton, add sections via new_section, then save with build_page. This gives clear context for when to use it, though it doesn't explicitly list exclusions (e.g., when not to use).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and does so excellently. It discloses the critical CDN re-hosting behavior (raw Pexels URLs won't display), explains the default upload=true behavior, caching benefits, and the required environment variable. This is rich, non-obvious 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: it starts with the purpose, then a critical warning, explains the default behavior, provides usage guidance, and ends with the requirement. Every sentence earns its place and nothing is redundant.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having no output schema, the description covers the essential aspects: purpose, key behavioral constraint (CDN whitelist), return value (cdn_url), and environment requirement. For a straightforward search tool with well-documented parameters, this is complete enough for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds a little context around the upload parameter by explaining the CDN re-hosting and cdn_url, but the schema already describes each parameter well. No significant additional meaning is provided beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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: 'Search stock photos (Pexels) for a page/product.' It clearly identifies what the tool does and its intended use case, distinguishing it from sibling image tools like upload_images or read_image.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context: use this tool to fetch stock photos and use the returned cdn_url for image src/product images. It also notes the environment variable prerequisite. It doesn't explicitly exclude alternatives, but the context is sufficient for an agent to decide when to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the disclosure burden and does reveal key behavioral traits: subsequent calls target the new site and the selection is saved locally for auto-connect next session. It does not cover failure modes, permissions, or return values, but the most important state-changing behavior is transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is four short sentences with no filler. It front-loads the action, then explains the session and persistence implications, and ends with a concrete prerequisite.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter state-switching tool, the description covers what it does, how it affects subsequent calls, persistence behavior, and how to obtain the parameter. No output schema is needed, and the description is sufficiently complete to invoke the tool safely.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents site_id, but the description adds practical guidance by instructing the user to call list_my_sites first to retrieve it. This provides meaning beyond the schema's terse 'The site ID to switch to.'
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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: 'Switch to a different site by site_id.' It distinguishes the tool by stating its persistent effect on subsequent calls, making its purpose unambiguous relative to the extensive sibling list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear usage context, including that all subsequent calls will target the new site and that the choice persists across sessions. It also directs the user to 'Use list_my_sites first to find the site_id,' but it does not explicitly mention when not to use the tool or name alternative tools for the same action.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly states this replaces the ENTIRE source, requires user approval, and includes a safeguard that blocks the update if the new source is less than 50% of the existing size. This goes beyond typical descriptions, though it does not mention return values or post-conditions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized with a clear main statement, numbered prerequisites, and a final safeguard/alternative note. Every sentence serves a purpose, and the numbered list makes the instructions easy to follow.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite lacking an output schema and annotations, the description provides all necessary context: purpose, required pre-steps, destructive nature, safety guard, and an alternative tool. This is highly complete for a destructive mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for both parameters, so the schema already documents them fully. The description does not add extra semantic meaning beyond what is in the schema, but it does reinforce that 'source' is a full replacement.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Replace full source of a global source.' It also distinguishes itself from siblings by explicitly noting 'For element-level changes, prefer update_global_source_element instead.'
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use guidance: it mandates reading existing source first, showing changes to the user, and obtaining explicit confirmation before calling. It also names an alternative tool for element-level changes.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It discloses that updates are partial ('Only sends fields you specify — others remain unchanged'), that CSS is 'auto-wrapped in <style>', and that HTML/script insertion points are specific. It does not mention permissions, rate limits, or failure behavior, but it adds meaningful context beyond the raw schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured with a clear opening sentence, critical usage warning, and a bulleted list of parameters. It is slightly verbose but every sentence carries important information, and the front-loaded warning ensures safety is emphasized first.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of annotations and an output schema, the description covers the essential aspects: what the tool does, how it behaves (partial update), prerequisites, per-parameter specifics, and safety requirements. It does not describe return values or error cases, but these are less critical for an update tool with optional parameters and no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, but the description adds value by explaining the meaning of each parameter (e.g., 'code_before_head: HTML/script inserted before </head>') and clarifying the update semantics ('only sends fields you specify'). This goes beyond the schema's minimal descriptions like 'Custom CSS for the site'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update custom code (CSS/JS) for the entire site' with a specific verb and resource. It also distinguishes this from sibling tools like get_site_custom_code and append_site_custom_code by emphasizing 'Only sends fields you specify — others remain unchanged', making it clear this is a partial update rather than a read or append operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit usage guidance: MUST read existing code with get_site_custom_code first, show the user what will change, and get explicit confirmation. Also states 'NEVER update without user approval', giving a strong when-to-use directive and a clear prerequisite. This is more than typical and effectively distinguishes the required workflow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and covers the return types (errors, warnings, stats) with concrete examples. It does not explicitly state whether the operation has side effects, but the verb 'validate' implies a read-only check, which 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the action, but the first sentence packs a dense list of error/warning types. Still, every clause contributes useful information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter validation tool without an output schema, the description explains purpose, usage, and return categories sufficiently. It leaves out details about the 'stats' content and invalid JSON handling, but these are minor gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already describes 'source' as a page source object or JSON string, achieving 100% coverage. The description adds the expected shape '{ sections: [...] }', enriching the meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'validate' with resource 'page source' and enumerates exact error and warning categories, making the purpose unmistakable. It also distinguishes itself from build_page by referencing it, which helps disambiguate from sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The instruction 'Always run this before build_page' provides explicit guidance on when the tool should be used, establishing a direct workflow context. While alternatives are not mentioned, the directive is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description takes on full responsibility. It discloses key behaviors: reading current source, appending, validating, saving only when dry_run=false, and re-id'ing sections to avoid collisions. This is exemplary transparency for a potentially 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences deliver purpose, process, and safety guidance without wasted words. The description is front-loaded and every sentence serves a distinct purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core workflow and side effects well. It is missing return value description (preview output) and behavior on validation failure, but the tool complexity is moderate and the safety workflow is well documented.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all three parameters. The description adds extra meaning by directing users to build the section with new_section and explaining the re-id behavior, which clarifies the section parameter's role beyond its raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action: 'Append a section to an EXISTING page's source.' This distinguishes it from page creation or draft-specific tools, especially with the mention of re-id and building with new_section.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives concrete usage context: it appends to existing pages, requires a section from new_section, and provides a two-step safety workflow with dry_run. It lacks explicit comparisons to alternatives like add_draft_section or update_page_source, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully carries the burden and does so excellently. It discloses incremental persistence, per-request timeout, mode-specific behavior, progress saving, and failure recovery semantics (page_id + committed_count). This goes far beyond a generic 'commit draft' statement.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tightly written sentences with clear emphasis (INCREMENTALLY, dry_run=true, RESUMABLE). No wasted words, and the structure naturally guides from primary purpose to operational modes to failure handling.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (incremental, resumable, multi-request), the description is highly complete. It covers the process, retry behavior, and mode semantics. It does not describe return values or stats preview details, but the absence of an output schema makes this a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds meaningful context: it explains the default dry_run=true, contrasts the two modes, and ties draft_id to the resumability mechanism. This enriches the schema descriptions rather than merely repeating them.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource: 'Persist a local page draft to the backend INCREMENTALLY' and clarifies the one-section-per-request behavior. This distinguishes it clearly from sibling tools like add_draft_section, get_page_draft, and clear_page_draft. The dry_run vs false modes further specify the tool's scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly explains when to use dry_run=true (validate/preview) versus dry_run=false (create and persist), and notes resumability for retries. It does not explicitly name alternatives or say 'use X instead,' but the mode guidance provides strong practical direction for the primary use case.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses the dual side effect: persisting a record and embedding the section into page sources, with header/footer placement behavior. It also explains the dry_run default and atomic save. It doesn't mention permissions or conflict handling, but the key behavioral traits (what gets modified and the safety mechanism) are transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences with no filler. It front-loads the purpose, provides a prerequisite action, and explains the dry-run mode. Every sentence contributes meaning, and the structure is easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no annotations and no output schema, the description covers the core behavior, the required sequence, and the safety mechanism. It doesn't specify response format or what happens on conflicts, but the essentials for invocation are present. The complexity is moderate, and the description is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already has 100% coverage with descriptions for all five parameters, so the baseline is 3. The description adds workflow context (e.g., 'give it a real bg/padding + logo/menu/links' for the section parameter) and explains the `type` field's role in placement (header→top, footer→bottom) beyond the schema enum. This supplementary guidance elevates it above baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a reusable global section and explicitly contrasts with the builder's behavior: it persists a global_section record AND embeds the section node into page sources. It distinguishes from sibling tools like new_section (which builds the section) and list_global_sections (which reads). The reference to 'Header / Footer / shared block' and the top/bottom placement provides concrete scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit workflow guidance: 'Build the section first with new_section ... then pass it here.' It also explains the two-step safety with dry_run=true preview vs dry_run=false atomic save, which tells the user when to use each mode. It implies alternative/complementary tool (new_section) and the distinction between creating the content vs embedding it site-wide.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description deserves credit for outlining the workflow: ask a short batch, restate the plan, get a yes, then build. It discloses the sequential behavior, but it does not clarify what the tool returns (e.g., the exact questionnaire content) or any potential side effects, leaving a minor gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is just two sentences, front-loaded with the primary purpose and followed by concise usage guidance and exclusions. Every word contributes value, with no unnecessary repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter guide tool, the description sufficiently covers purpose, timing, and skip conditions. It does not specify the return format, but the description implies the output is a questionnaire/batch, which is probably enough for an agent. A more explicit statement of the output structure would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema already provides complete coverage. The description adds no parameter details, but none are needed. The baseline of 4 for zero-parameter tools applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool 'gets the INTAKE questionnaire + build flow' and specifies the exact context ('before creating a new site/store/page'). It uses a specific verb and resource, and the mention of fresh builds distinguishes it from sibling tools like get_build_guide.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit when-to-use instructions ('at the start of any fresh build') and when-to-skip conditions ('tiny edits, data questions, or when the user already gave the brief / says "just do it"'). This gives the agent concrete decision rules for invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden and does an excellent job. It discloses the exact output categories (datasets, field names, page types, repeater children behavior) and even notes that IDs are auto-minted when attaching bindings. This is rich, specific behavioral context beyond a simple 'lists bindings' statement.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single long sentence with several clauses, but every part contributes useful information (examples, page types, usage). It is front-loaded with the main purpose and then provides specifics. It could be split into multiple sentences for better readability, which is why it doesn't get a 5.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no parameters, no output schema, and no annotations, the description is remarkably complete. It covers the purpose, the information returned, examples of field names, page type requirements, repeater behavior, and how to use the results (auto-minted IDs). There are no obvious gaps for an agent to select and invoke this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, so there is nothing to explain. Baseline for zero params is 4. The description adds contextual value by explaining what the output contains and how to use it, though it doesn't need to discuss parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action ('List every dynamic-data BINDING target') and identifies the resource (datasets, field names, page types, repeater children). It goes beyond a generic list by enumerating examples and usage context, effectively distinguishing it from other listing tools like list_global_sources or list_elements.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool: when you need to discover dynamic-data binding targets. It also gives an explicit downstream usage ('Attach via new_element opts.bindings') with an example, but it does not explicitly mention alternatives or when not to use this tool, which 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses key behavioral traits: responsive auto-collapse with default tablet/mobile breakpoints, and the fact that it returns a node to be placed inside a section. However, it does not mention permissions, side effects, or return format details, which are less critical for a builder tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: starts with the core purpose, then use cases, then responsive behavior, then nesting guidance, and ends with an example. Each sentence adds value, and the content is front-loaded for quick scanning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (6 parameters, nested objects, no output schema), the description provides sufficient context: it explains the row vs. column distinction, responsive behavior, placement within a section, and includes an example. It does not explicitly detail the return value beyond mentioning the returned node, but this is a minor omission because the schema describes the parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema already covers all 6 parameters with descriptions (100% coverage), so the baseline is 3. The description adds a concrete example of the children array and clarifies the responsive behavior, which helps the agent understand how parameters like collapse and column_gap work in practice.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as a multi-column row container with children laid out side by side. It distinguishes itself from stacked sections and provides specific use cases like feature cards, category tiles, and footer columns, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly explains when to use the row (for horizontal layouts) and when not to (sections stack vertically), and instructs to place the returned node as a child inside a section. Also gives concrete examples of real-page use cases, effectively guiding the agent's tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It discloses a key behavior: the attrs object is 'merged onto the subscription', and gives typical structures (`{ settings: {...} }`, `{ status }`). However, it doesn't mention side effects like whether the merge is shallow/deep or whether existing settings are replaced, so it is not fully transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with purpose, and every phrase is informative. No filler or repetition of schema details. Efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple config-update tool with two parameters and no output schema, the description covers purpose, usage, and key behaviors. It lacks return-value information, but given the low complexity, it is nearly complete. The explicit alternative for product-review apps adds important context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds value by clarifying the merge semantics and showing typical shapes for attrs, which goes beyond the schema's generic 'Fields to update' description. This strengthens parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the specific verb+resource: 'Update an installed app's configuration.' It clearly distinguishes from sibling tools by explicitly naming update_app_review as the preferred alternative for product-review apps. This gives a precise, actionable purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit usage context: pass the subscription id and attrs object. It also names an alternative (update_app_review) and the specific condition for using it, effectively telling the agent when to choose a different tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full behavioral burden and does so excellently. It discloses that the backend auto-seeds sample data, that the tool deletes it by default, that the site has no pages, and that free accounts have a 4-site quota. These are critical non-obvious behaviors.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense and well-organized, starting with the primary action and then layering important caveats and workflow steps. There is no fluff, and every sentence adds meaningful information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having no output schema, the description covers the creation process, default behaviors, quota limitations, and next steps. It provides enough context for an agent to invoke the tool and understand the immediate consequences and follow-up actions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds extra semantic value by explaining the practical effect of keep_seed (keep sample data vs. delete) and switch_to (changes session context), which goes beyond the schema's straightforward definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a brand-new storefront site for the current account, with specific behavior (switching to it, returning an empty clean site). It distinguishes itself from related sibling tools like create_site_from_template by emphasizing the blank, no-template nature of the created site.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when to use this tool and a recommended follow-up workflow (get_build_guide → new_section/new_element → build_page). It does not explicitly mention alternatives like create_site_from_template, so it lacks explicit exclusion guidance, but the context is strong.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden. It discloses that the tool clones the template's pages, global sections, cart, popups, styles and fonts, and that it switches the session to the new site—a key side effect. It implies the new site is not yet published by directing next steps to publish_site, which is useful disclosure, though return values and error cases are not mentioned.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, each earning its place: what it does, what it clones, and how to use it next. It is front-loaded with the core purpose and avoids filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Even without annotations or an output schema, the description provides a complete operational picture: prerequisites, cloned content, session switching, and next steps for editing and publishing. This is sufficient for an agent 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.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All four parameters are already described in the schema (100% coverage), so the baseline is 3. The description adds meaningful workflow context by explaining where theme_id comes from (semantic_search_themes/list_template_themes) and confirming the switch_to behavior, which helps an agent correctly construct the invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The opening sentence states a specific action ('Create a NEW site from a marketplace TEMPLATE') and designates it as the dedicated API, distinguishing it from the sibling create_site. It also names the cloned resources (pages, global sections, cart, popups, styles, fonts), making the tool's role unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a concrete workflow: pick a template with semantic_search_themes/list_template_themes, pass its theme_id, then edit with update_page_element(s)/site-style tools and publish_site. This explicitly frames the prerequisite and follow-up actions, and the 'dedicated API' wording subtly distinguishes it from create_site.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the disclosure burden. It reveals useful behavior: server finds function boundaries automatically, replacement is whole-function, appending goes to end of file, and update_imports affects lines before first export. It also discloses the return value. However, it doesn't explicitly warn about the destructive nature of replace/remove or error handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: a leading sentence for purpose, a clear alternative, a bulleted action list, and a return note. Every sentence adds information; no tautology or padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite lacking annotations and output schema, the description fully covers the tool's actions, parameter usage, and return value. It also provides usage boundaries versus update_http_function. No significant gaps are apparent for this complexity level.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds value by mapping each action to which parameters are meaningful and how they're used (e.g., replace entire function vs append; import block vs code). It clarifies the relationship between action, code, and function_name beyond the schema's short descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Edit') with a clear resource ('HTTP function file') and scope ('by function name'). It lists four concrete actions and explicitly contrasts with update_http_function, making the tool's purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states when to use this tool ('best for targeted changes...') and when to use an alternative ('For writing multiple new functions or major refactors, use update_http_function with full content instead'). This is a clear when/when-not statement naming the alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the transparency burden. It discloses the tool returns the authoritative schema (read-only nature) and clarifies it does not enforce semantic rules (validate_page does). However, it doesn't explicitly state no side effects or mention any error behaviors, but for a simple getter the key traits are covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two focused sentences pack significant detail: the resource, the schema version, the shape, and the distinction from validation. No fluff, front-loaded with the verb and target.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters, no output schema, and no annotations, the description sufficiently explains what is returned, why it matters, and how it relates to validation. It covers the essential context for an agent to use this tool correctly without needing additional information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters, so baseline is 4. The description provides context about the schema's structure and purpose, adding value by explaining what the returned schema governs, though there are no parameters to elaborate on.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool retrieves the authoritative JSON Schema for page source, with specific details (Draft 2020-12, sections array, structural contract fields). It distinguishes itself from siblings by positioning this as the shape definition versus validate_page for semantic rules.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells when to use: 'Use it as the shape to emit' and contrasts with validate_page which 'enforces the semantic rules'. This gives clear context for selection among sibling tools like validate_page or get_page_source.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and delivers: it discloses the no-network behavior, the incremental resumable commit, and the disposable cache with Redis/in-memory sliding ~2h TTL. It also sets expectations about draft loss and recovery ('never a failure'). This goes well 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but front-loaded with the core purpose, followed by workflow, usage alternative, and cache behavior. Each sentence contributes distinct value and there is no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description fully covers the draft lifecycle: start, add sections, incremental commit, cache disposability, and failure recovery. It explains the relationship to build_page and the resumability on timeout, making it complete for a workflow-oriented tool with no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and parameter descriptions already provide detailed semantics (e.g., slug leading slash, type prerequisites, SEO mapping). The tool description does not add parameter-level insight, but none is needed given the schema's completeness. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Start a page draft') and resource, clarifies it makes no network call, and contrasts with build_page for large/multi-section pages. This clearly distinguishes it from siblings like create_page and add_draft_section.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use this instead of build_page for large/multi-section pages', providing a direct alternative. It also outlines the intended workflow with add_draft_section and commit_page_draft, and notes the resumable-on-timeout benefit, giving clear usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full responsibility for behavioral disclosure. It discloses the two-step process, the default dry_run behavior, the requirement for explicit user approval, the risk of data loss, and the specific merge rules for different field types (style/config/specials shallow merge, events/bindings replace). This is exemplary transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact yet information-dense, organized as numbered steps with an important warning and merge rules. Every sentence serves a purpose: the first states what the tool does, the steps explain the required workflow, and the final sentence clarifies field-level behavior. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a batch mutation tool with a required confirmation step, the description covers the process, the risk, the merge rules, and hints at the expected return (diff from step 1). No output schema exists, but the description does not need to detail return values because step 1 explicitly returns a diff. Complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already describes all 4 parameters with 100% coverage, so the baseline is 3. The description adds value by explaining the semantic meaning of dry_run (preview vs apply), tying it into the workflow, and clarifying the merge behavior for fields within the updates array, which goes beyond the schema's basic descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Batch update multiple elements in one global source,' which clearly specifies the action (update), the resource (global source elements), and the batch aspect, distinguishing it from the singular update_global_source_element and the broader update_global_source. The verb and resource are 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.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a detailed two-step workflow with explicit instructions on when to call the tool (dry_run=true for preview, then dry_run=false only after user confirmation). It clearly states when not to proceed, but it does not explicitly compare against alternative tools beyond the implied batch vs single distinction. Strong context and safety guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses behavioral traits: it reads/downloads and re-uploads, processes up to 20 entries in parallel, converts non-jpeg/png/webp to JPEG, caches per site, and defaults to actual uploads (dry_run=false). It also explains dry_run semantics including local path existence checks. This goes far beyond what structured metadata would provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is about 150 words across two paragraphs, but every sentence carries essential information. It front-loads the primary purpose, then adds usage guidance, technical constraints, and error/edge-case handling. No filler or repetition; the length is justified by the tool's complexity and lack of annotations.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having no output schema and no annotations, the description is complete. It explains the return format ('images' map), the default mutation behavior, caching benefits, batch/parallel processing, format conversion, dry_run preview, and file path restrictions. This is more than sufficient for an agent to decide when and how to invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds operational meaning beyond the schema: parallel processing limit, format conversion behavior, dry_run defaults and preview details, and the stdio-only restriction for local paths. These extras justify above baseline, though the schema already documents the core parameter types and defaults.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource: 'Convert external image URLs, data: URIs, or LOCAL FILE PATHS into site-hosted CDN URLs by reading/downloading each image and re-uploading it to the WebCake backend.' This clearly states the tool's function and differentiates it from sibling tools like read_image or search_images by emphasizing conversion to CDN URLs and the requirement for whitelisted domains.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use the tool: 'Use this whenever the user supplies their OWN images...' and 'This is REQUIRED for any external image (incl. Pexels search results)...' It also provides a when-not constraint: local file paths are only permitted on stdio, not remote HTTP. However, it does not name alternative tools, so it stops short of fully explicit alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of disclosure. It clearly states that only a slice is read, that pagination is supported via offset/length, and that the response includes next_offset and remaining_chars to indicate progress. This gives the agent a precise mental model of the tool's behavior without relying on 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the primary purpose, then adding precise operational details. There is no redundant or filler content; every phrase contributes to understanding the tool's function and usage.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having no output schema, the description explains the key return semantics (next_offset, remaining_chars) and the pagination loop. It provides enough context for an agent to use the tool correctly with just the cache_id, and it handles the typical use case of reading large cached results. The tool's complexity is low and this description covers the essential aspects completely.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so parameters are already documented. The description adds significant semantic value by explaining how offset/length relate to slicing and pagination ('Page through', 'response reports next_offset + remaining_chars until done'). This goes beyond the bare schema descriptions of 'Start character offset' and 'Number of characters to return.'
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description specifies a clear verb ('Read') and resource ('slice of a large cached result'), and explains where these results come from (another tool's output with 'cached':true + cache_id). This clearly distinguishes it from siblings like list_cached_results, which presumably list available cached results rather than reading them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context on when to use the tool: after another tool produces a cached result, look for a cache_id. It explains the pagination workflow with offset/length and next_offset/remaining_chars. It does not explicitly mention alternatives or when *not* to use it, but the intended usage is unambiguous given the family of sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully carries the behavioral transparency burden. It discloses that the operation can cause data loss, that dry_run returns a diff, that user confirmation is mandatory, and it details complex merge/replace semantics for different field types (style/config/specials shallow merge, responsive merge by bp key, events/bindings full replacement). This is exemplary transparency beyond basic safety hints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but every sentence serves a purpose. It is structured clearly with STEP 1/2/3, an IMPORTANT warning, and merge rules. It is front-loaded with the tool's purpose and immediately jumps into the critical workflow. No redundant or filler content exists; the structure aids readability and comprehension.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (10 parameters, nested objects, two-step process, no output schema), the description is exceptionally complete. It covers the full workflow, explicit confirmation requirements, merge vs replace behavior, and normalization details. The only missing piece is return value specifics, but the description does mention the diff output in step 1, and without an output schema this is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Even though schema coverage is 100%, the description adds significant meaning to parameters by explaining how they behave. For example, it clarifies that 'events' and 'bindings' arrays are completely replaced and must contain the full list, and that 'style', 'config', and 'specials' are shallow-merged. It also explains the dry_run default and the need to read existing data first, which the schema does not convey.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Update a single element within a global source.' It uses a specific verb ('update') and resource ('single element within a global source'), and the singular wording distinguishes it from the sibling tool 'update_global_source_elements' (plural). The purpose is unambiguous and immediately understandable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides excellent usage guidance with a step-by-step process: dry_run=true first, show diff, get explicit user confirmation, then dry_run=false. It clearly instructs when to call with each dry_run value and warns against skipping confirmation. However, it does not explicitly mention alternatives or when not to use this tool (e.g., for batch updates), so it lacks the explicit sibling differentiation described in a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It openly discloses that the response is a slim summary, lists the exact fields returned, and explicitly warns that the full element tree is intentionally omitted due to size. This prevents the agent from assuming a complete payload and points to alternate tools.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is tight and front-loaded: the first clause defines the operation and object, the second details the return fields, and the third explains a limitation and directs to alternatives. Every sentence earns its place; no filler or redundant schema repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, no-output-schema list tool, the description is complete. It covers what is returned, the format of each entry, the intentional omission of the full tree, and the relevant sibling tools for deeper exploration. Nothing essential is missing for an agent to invoke and interpret this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so per the rubric the baseline is 4. While the schema is empty and there is nothing to document, the description adds contextual meaning by describing the shape of each entry (id, name, slot, element count, type histogram, custom classes), which helps the agent understand what the output means.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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 ('reusable global sections'), and precisely defines the scope (Header, Footer, shared content blocks) and output type (SLIM summary only). It explicitly distinguishes itself from the drill-in sibling tools by stating that the full element tree is not returned.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It clearly states when to use this tool: to list global sections in summary form. It also provides explicit alternatives for deeper inspection ('drill in with get_global_section, search_global_section_elements, or get_global_section_element'), giving the agent actionable guidance on choosing between related tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full transparency burden. It clearly discloses what each mode returns (function names/line ranges vs full code + schemas) and explains the include_guide behavior. No contradictory or misleading statements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact at four sentences, uses bullet points for clarity, and every sentence provides useful information. No fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with two optional boolean parameters and no output schema, the description covers purpose, modes, parameter usage, and a recommended workflow. It is self-sufficient and complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds significant meaning beyond the schema by detailing the practical effects of each boolean parameter and providing use-case guidance for them. This exceeds the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Get the main HTTP function file' with a specific verb and resource. It also distinguishes two modes (overview vs full) and references the sibling tool get_http_function_snippet, making differentiation clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly explains when to use overview=true (browsing, structure) vs overview=false (writing, refactoring). Provides a concrete tip for small fixes to use overview first then snippet, naming the alternative tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full burden. It discloses default mode, persistence across sessions, and the safety tradeoff between the two modes, which is exactly the behavioral context an agent needs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a concise opening statement, a bulleted list of modes, and a usage mapping. Each sentence provides useful information without fluff, and the structure front-loads the essential purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter configuration tool with no output schema, the description fully covers what the tool does, its two modes, persistence, and when to invoke it. No critical information is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already has 100% coverage including enum descriptions, but the tool description enriches the meaning of the 'mode' parameter by explaining the default, the diff preview behavior, and mapping natural language phrases to each value. This adds real semantic value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a clear verb ('toggle') with a specific resource ('update confirmation mode'), explains what it controls, and distinguishes it from the sibling toggle_debug_render. It clearly states the tool's function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit trigger conditions ('Call this tool when the user says things like') along with concrete user phrases for each mode, covering both Vietnamese and English. This gives clear when-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description fully carries the behavioral burden. It discloses important traits: dry_run defaults to confirm_mode setting, merge rules (shallow merge for style/config/specials, merge by bp key for responsive, REPLACE for events/bindings), auto-normalization of event/binding entries, and a warning that skipping confirmation risks data loss. This is exemplary transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but every sentence carries essential information. It is structured into clear steps and merge rules, making it easy to parse. No redundancy or fluff; it earns its length given the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description fully covers the workflow (dry-run to apply), necessary prerequisites (reading get_page_element), merge behavior, and risk warnings. It also explains the default behavior of dry_run and references toggle_confirm_mode. Given the tool's complexity (9 params, nested objects, no output schema), this description is remarkably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds critical semantics beyond the schema. It explains merge rules per parameter (e.g., events and bindings replace the whole array, requiring the complete list), and that entries are auto-normalized so clients can pass simplified objects. This significantly enhances understanding of parameter usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Update properties of a specific element in page source.' It specifies the resource (page element) and action (update), and distinguishes it from sibling tools like update_page_elements or update_page by focusing on a single element and the two-step dry-run process.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit step-by-step usage: call with dry_run=true (default), show diff, get explicit user confirmation, then call with dry_run=false. It also advises reading get_page_element first to get the complete list for events/bindings, preventing data loss. This is strong guidance on when and how to use the tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

Copy to your README.md:

[![webcake-storefront-mcp MCP server](https://glama.ai/mcp/servers/vuluu2k/webcake-storefront-mcp/badges/card.svg)](https://glama.ai/mcp/servers/vuluu2k/webcake-storefront-mcp)

Score Badge

Copy to your README.md:

[![webcake-storefront-mcp MCP server](https://glama.ai/mcp/servers/vuluu2k/webcake-storefront-mcp/badges/score.svg)](https://glama.ai/mcp/servers/vuluu2k/webcake-storefront-mcp)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/vuluu2k/webcake-storefront-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server