voog-mcp

by runnel

Overview Schema Related Servers Score Discussions

Python

Remote

Server Quality Checklist

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

Latest release: v1.5.0
Disambiguation5/5
Every tool targets a distinct resource and action. With 111 tools, the descriptions are detailed enough that there is no real overlap; even similar operations like node_move vs node_relocate are clearly separated.
Naming Consistency4/5
Most tools follow a consistent resource_verb pattern (e.g., article_get, articles_list). Minor deviations include the voog_ prefix for administrative tools, layout_rename alongside layout_update, and asset_replace being a misnomer for a rename.
Tool Count2/5
At 111 tools, this server is far beyond the typical well-scoped range. While Voog's API is broad, many tools are redundant (page_set_hidden vs page_update, layout_rename vs layout_update), and the huge number can overwhelm an agent.
Completeness4/5
The tool set covers most of Voog's resources with full CRUD for pages, products, layouts, nodes, redirects, webhooks, etc. However, article_delete, language_update, and content_partial creation are missing, though passthrough tools can fill these gaps.
Average 4.3/5 across 111 of 111 tools scored. Lowest: 2.8/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 20 commits in the last 12 weeks
- Last stable release on August 13, 2026
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
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?
Annotations already declare readOnlyHint true and destructiveHint false. The description confirms 'Read-only' but adds no new behavioral traits such as pagination, rate limits, or side effects. Minimal value beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two sentences, front-loading the purpose. However, it misses critical parameter information, making it slightly less efficient despite its brevity.
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 no output schema and no parameter descriptions, the description should compensate. It explains the node concept but fails to describe the required 'site' parameter, and omits details on ordering, filtering, or pagination for a list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has one required parameter 'site' with no description and 0% schema description coverage. The description does not mention or explain the 'site' parameter, leaving the agent without guidance on what value to provide.
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 verb 'List' and the resource 'page nodes', including the exact fields returned. It also clarifies the language-agnostic node concept, distinguishing it from pages and implicitly from sibling tools like node_get.
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 (e.g., node_get for a single node). The description only states what the tool does, without any context for 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?
Adds beyond annotations: explicitly states deletion is IRREVERSIBLE and that Voog does not retain deleted articles. Annotations already had destructiveHint=true, so description adds meaningful 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?
Two concise sentences, no filler. Every word adds value.
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 delete tool with destructive hint and no output schema, description lacks details on return values, error handling, or post-deletion state. Could mention what the response looks like.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%. Description only mentions force parameter, ignoring site and article_id. No explanation of parameter types, formats, 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 clearly states the action ('Delete an article') and the resource. It distinguishes from siblings like article_create, article_get, articles_list by specifying deletion and irreversibility.
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 on when to use this tool vs alternatives like article_delete_data or article_set_data. No mention of prerequisites or conditions beyond force=true.
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?
Annotations already provide readOnlyHint, destructiveHint, and idempotentHint. The description adds the HTTP method and endpoint, reinforcing that this is a safe read operation. No contradictions, but no additional behavioral context (e.g., rate limits, auth needs) beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no unnecessary words. Every part is essential and immediately conveys the tool's purpose.
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 description fails to cover return values, error scenarios, or required context. With no output schema and minimal parameter guidance, the agent lacks information to invoke the tool confidently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 2 required parameters (site, cart_rule_id) with zero description coverage. The description only mentions 'by id' but does not explain the site parameter, its purpose, or format. No value added beyond schema names.
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 action ('Get a single cart rule by id'), the resource ('cart rule'), the HTTP method and endpoint, and marks it as read-only. This clearly distinguishes it from sibling tools like cart_rules_list, cart_rule_create, etc.
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 fetching a single cart rule, contrasting with cart_rules_list for listing. However, it does not explicitly state when to use this over alternatives, nor does it provide exclusions or prerequisites.
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?
Annotations already provide readOnlyHint, destructiveHint, idempotentHint; description adds 'Read-only' which is consistent but redundant. No additional behavioral info like pagination or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with front-loaded verb and resource, zero waste. Perfectly 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?
For a simple list tool with one parameter and no output schema, the description is minimal. It fails to explain the required 'site' parameter, leaving the agent without enough context to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage for the required 'site' parameter, and the tool description does not explain its purpose, format, or allowed values. The agent has no clue what to pass.
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 'List all cart rules' with HTTP method and path, and adds 'Read-only' to confirm safety. This distinguishes it from sibling tools like cart_rule_get (single rule) and cart_rule_create (write).
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?
Description implies usage for retrieving a list of all cart rules, but does not explicitly state when to use this over alternatives like cart_rule_get or how to filter results. No guidance on prerequisites.
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?
Annotations already indicate idempotentHint=true. Description adds that it's a partial update and at least one field must be supplied, but lacks details on side effects, permissions, 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with key information, no redundancy. Could benefit from clearer structure but efficient overall.
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 11 parameters, no output schema, and no param descriptions, the description is insufficient. It misses details on required permissions, error cases, and parameter semantics beyond two fields.
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?
With 0% schema description coverage, the description should compensate but only mentions two common fields (enabled, position) and an envelope structure that doesn't match the flat schema. Most parameters remain unexplained.
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 (update), the resource (cart rule), the HTTP method and endpoint, and gives common update fields. It distinguishes from sibling tools like cart_rule_create and cart_rule_delete.
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 this is for updating an existing cart rule, but it does not explicitly compare to alternatives or provide when-to-use guidance. It mentions partial updates but no exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description directly contradicts the idempotentHint annotation. It states 'REFUSES to overwrite an existing tree that already contains .tpl files', meaning repeated calls on the same target directory will fail, which is not idempotent behavior. Per the rubric, any contradiction of annotations warrants a score of 1. The description does disclose useful behaviors (skip binaries, manifest, preservation of non-tpl files) but the contradiction is a severe issue.
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 dense paragraph, but each sentence carries meaningful information: what is fetched, where it is written, what is skipped, manifest generation, and refusal behavior. It is front-loaded with the core action. Slightly long but appropriate for the tool's complexity.
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 explains the tool's side effects (writing files, manifest) and edge cases (binary skip, refusal, preservation). It does not explicitly mention what the function returns, but the extensive behavioral details cover the essential context for selection and invocation. Sibling differentiation is adequate via the explicit reference to layout_asset_upload.
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 baseline is 3. The description echoes the schema's parameter meanings (site from voog_list_sites, target_dir absolute path) and adds a bit of context about what gets written there, but does not provide any additional parameter-level constraints or examples beyond the schema. No compelling need for more given full 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 verb ('Fetch every layout + component') and the resource (/layouts, layout_assets), and explicitly notes the output destination (target_dir). It also distinguishes from siblings by mentioning layout_asset_upload for binary assets, which differentiates its 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 tells when to use this tool (to pull text-based layouts/components/assets to local disk) and explicitly excludes a specific alternative ('Binary assets are skipped... use layout_asset_upload for those'). It also provides a clear caveat about existing .tpl files, guiding use in fresh or clear directories. It does not enumerate other alternatives but the context is sufficient.
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?
Annotations already declare readOnlyHint, destructiveHint, and idempotentHint. The description confirms read-only but adds no additional behavioral traits (e.g., pagination, rate limits, or result format). No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, front-loading the action and endpoint, with no wasted words. Every sentence is necessary.
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 list operation with one parameter and annotations, the description is adequate but not richly informative. It lacks details about return values, pagination, or parameter format, relying heavily on inferred knowledge.
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 coverage is 0% with one required parameter 'site' lacking description. The description does not mention the parameter or provide any guidance on its usage, leaving the agent to infer meaning.
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 ecommerce discounts, includes the API endpoint, and notes it's read-only, which effectively distinguishes from sibling tools like discount_create or discount_get.
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 (to list all discounts) but provides no explicit guidance on when not to use it or how it differs from siblings like discount_get or discounts search tools. The context of sibling tools is not addressed.
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 disclosure mentions validation is left to Voog and that invalid combos return a 422, adding context beyond annotations. Annotations show it's not read-only, destructive, or idempotent, but description adds behavioral nuance.
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?
Two sentences are concise and front-loaded with the main action. The second sentence adds structural details, though it could be slightly more streamlined.
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?
No output schema is provided, and the description does not mention return values. For a tool with 10 parameters and nested objects, more detail on response or side effects would be helpful.
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?
Despite 0% schema coverage, the description explains the inner structure of conditions and result, but only covers 2 of 10 parameters (conditions, result). Required fields are listed but not described individually.
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 'Create a cart rule' and provides the endpoint. It clearly distinguishes from sibling tools like cart_rule_delete, cart_rule_get, cart_rules_list, and cart_rule_update.
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 (to create a cart rule) but does not state when not to use or provide alternatives. It gives details on the structure but lacks explicit usage 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?
Annotations already indicate idempotent and non-destructive behavior. The description adds useful context about the payload envelope and runtime discovery of translation keys with caching, which goes beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with three sentences, front-loading the action. It could be more structured, but it avoids unnecessary detail.
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 envelope and translation discovery but does not mention return values, errors, or permissions. For an update tool, response information would be beneficial.
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?
With 0% schema description coverage, the description must compensate. It gives brief examples for attributes but lacks detailed structure or allowed values for the object parameters, leaving ambiguity.
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 ecommerce settings, distinguishing between attributes (flat fields) and translations (nested), and specifies the payload envelope. This differentiates it from sibling tools like ecommerce_settings_get.
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 hints that translatable keys are discovered from GET /settings, implying a prerequisite, but does not explicitly state when to use this tool versus 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare idempotentHint=true and destructiveHint=false. The description adds value by explaining reversibility and the role of body as raw HTML for a Liquid tag, which goes beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, each earning its place. Front-loaded with the action and parameters, followed by a key behavioral note. No extraneous 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?
Adequate for a simple update tool with good annotations, but lacks explanation for site and text_id parameters and does not mention output or return values. The description is sufficient but not thorough.
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 3 parameters with only body having a description (33% coverage). The description explains body's purpose in detail but does not clarify site or text_id, leaving some ambiguity.
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 the verb 'Update' and the resource 'text body', including the HTTP method and path. It explains that the body is raw HTML for a Liquid tag, and mentions reversibility, making the purpose very clear and distinct 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 Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives like page_set_data or content_partial_update. The description implies it's for updating text bodies but does not specify prerequisites 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?
Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description confirms read-only nature and lists fields, but adds no new behavioral traits beyond what annotations provide (e.g., pagination, auth requirements). No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences. The first sentence defines purpose and endpoint, and the second provides actionable usage guidance. No redundant or unnecessary text. Front-loaded with key 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?
Given the tool has only one parameter and no output schema, the description lists return fields and links usage to another tool. However, it fails to explain the 'site' parameter, which is critical for invocation. This gap reduces completeness for a low-complexity tool.
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 has one required parameter 'site' with 0% description coverage. The description does not explain what 'site' represents (e.g., site identifier or domain), leaving the agent to guess. The description adds no 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 'List all ecommerce product categories' and includes the endpoint path. It explicitly mentions the fields returned (id, name, slug, parent_id, depth, created_at, updated_at) and provides a usage example linking to products_list, distinguishing it from sibling tools like category_get.
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 explicit guidance on using the output with products_list via 'Use category.id from the results as the products_list(category_id=...) filter.' It also marks the tool as read-only. However, it does not state when not to use this tool or mention alternatives like category_get for a single category.
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 adds important behavioral details beyond the annotations: products are orphaned (not deleted) and the operation may be rejected for categories with child categories. The annotations already indicate destructiveHint=true, and the description aligns with that.
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—two sentences front-load the purpose and key conditions. Every sentence adds value 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?
The description covers the destructive behavior and a rejection condition, but does not mention return values, success/error responses, or any other behavioral implications. Since there is no output schema, more context would be helpful.
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 input schema has 3 parameters with 0% description coverage. The description only adds context for the 'force' parameter (requires force=true), but does not explain 'site' or 'category_id', leaving meaning ambiguous.
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 ('Delete a category') and includes the exact HTTP endpoint. It also specifies that products are orphaned, which uniquely distinguishes this tool from sibling tools like category_update or category_get.
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?
It mentions that force=true is required and that deletion may be rejected if the category has child categories, providing usage conditions. However, it does not explicitly state when to use this tool over alternatives like category_update or category_create.
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 adds the REST endpoint (GET) and reinforces the read-only nature. Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, so the description complements these by providing the HTTP method 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 extremely concise with one sentence plus endpoint and read-only flag. Every word is purposeful and no 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?
Given the simplicity of a GET operation with two parameters and no output schema, the description is adequate but lacks explanation of the 'site' parameter and does not describe the return value. More detail would improve completeness.
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 0%, and the description only hints at 'by id' for category_id but completely ignores the 'site' parameter. It does not add meaningful semantics beyond the schema's bare types.
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' and resource 'single category by id'. It effectively distinguishes from siblings like categories_list (list all) and category_create/delete/update (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 does not provide explicit guidance on when to use this tool versus alternatives (e.g., categories_list for multiple categories). The context of retrieving a single category by ID is implied, but no when-not-to or alternative tool mentions 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?
Annotations (readOnlyHint=false, destructiveHint=false) indicate it is a mutation. Description adds a note about flat body structure but lacks details like existence handling or authorization 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?
Two sentences, front-loaded with purpose and key parameters, no unnecessary wording. Efficient and to the point.
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?
Covers essential aspects: purpose, required/optional params, body format. But omits error scenarios (e.g., duplicate code) and does not mention return value, which is acceptable given 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 high (89%). Description reiterates required and optional params with some context (e.g., content_origin_id for duplication), adding marginal 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 'Add a new language to the Voog site' and provides the HTTP method and endpoint, making the purpose clear. It distinguishes from sibling tools like language_delete and languages_list.
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?
No explicit guidance on when to use versus alternatives. While no sibling update tool exists, the description does not mention when not to use or potential constraints like code uniqueness.
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 goes beyond the destructiveHint annotation by detailing that the language is 'IRREVERSIBLE' and that it 'unbinds associated content'. This adds behavioral context about what happens during deletion, which is not fully captured by the annotation alone.
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 exceptionally concise, consisting of two sentences that front-load the core action and then deliver critical warnings. Every sentence adds essential information 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?
The description covers the destructive nature, force requirement, and a safety suggestion, but lacks details on prerequisites (e.g., required permissions), response behavior, or asynchronous processing. For a delete tool with no output schema, it is adequate but not exhaustive.
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 description adds minimal value beyond the input schema. It repeats the force=true requirement already documented in the schema and does not explain the 'site' parameter or provide new insights into 'language_id'. With 67% schema coverage, the description falls short of compensating for gaps.
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: 'Remove a language from the site (DELETE /languages/{id})', identifying the verb, resource, and HTTP method. It distinguishes itself from sibling tools like language_create or languages_list by specifying deletion of a language, 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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides usage guidance by noting the requirement for force=true and suggesting a site_snapshot first if uncertain. However, it does not explicitly advise when to choose this tool over alternatives (e.g., other delete tools), leaving the context of use implied rather than explicit.
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 adds that the new page is hidden by default, which is not captured by annotations. Annotations indicate it is non-read-only, non-destructive, and non-idempotent, which is consistent. The description is clear about behavior beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, with two sentences that each provide useful information: the action and endpoint, and a specific behavioral note. No unnecessary 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?
While the core purpose is clear, the description lacks details about return values (no output schema), parameter explanations, prerequisites, or limitations. It is complete enough for a simple duplicate action but leaves gaps for an agent.
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 0%, but the description does not explain the meaning or usage of the 'site' or 'page_id' parameters. It only references page_id in the URL pattern. The description fails to add value beyond the bare 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 it creates a copy of the page including its content, and distinguishes from siblings like page_create by noting the new page is hidden by default. It provides a specific verb-resource pair and endpoint pattern.
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 duplicating a page but does not explicitly state when to use this tool versus alternatives such as page_create. No guidance on prerequisites or when not to use 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?
Annotations already declare readOnlyHint, destructiveHint, idempotentHint. Description adds response field details and optional includes (SEO, children). No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with key purpose, lists specific fields. No 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?
Adequate for a simple get tool with 4 params and no output schema. Lacks error handling details but sufficient for basic usage.
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 is documented. Description briefly mentions 'include SEO fields' and 'include children array' but does not add significant new meaning beyond 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?
Description clearly states it gets full details of a single page by ID and lists specific fields returned. Differentiates from sibling tools like pages_list, page_create, etc.
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 on when to use this tool vs alternatives like pages_list or page_get with different parameters. No mention of 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds value by specifying the response includes full nested lists for parcel carriers and warns about multi-KB payloads per method, providing behavioral context beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description consists of two impactful sentences, front-loaded with the main action and endpoint. Every sentence adds critical information without redundancy, achieving high efficiency.
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?
While the tool is simple, the description covers the core purpose and notable response characteristics. However, it omits details about the 'site' parameter (e.g., enum values, case sensitivity) and does not mention pagination or sorting, leaving gaps for a production scenario.
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 input schema has one required parameter 'site' with no description (0% schema coverage). The description does not explain the purpose, format, or allowed values of 'site', leaving the agent without sufficient guidance for correct 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 description clearly states the tool lists all shipping methods, specifies the endpoint, and highlights the significant detail of nested options[] lists for parcel-machine carriers. This clearly differentiates it from sibling tools that are either write operations or list other entities.
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 does not provide explicit guidance on when to use this tool versus alternatives. It notes the large payload size, which implies performance considerations, but lacks direct 'when-not-to-use' or references to sibling list 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?
Annotations already declare readOnlyHint, destructiveHint, and idempotentHint. The description reinforces with 'Read-only' and adds value by enumerating typical returned fields (title, code, data, languages), improving transparency.
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 one sentence, very concise. However, it could be restructured to separate purpose and behavioral notes for quicker parsing.
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 get tool with good annotations, the description covers purpose and return scope. It lacks parameter documentation, but overall is mostly complete given the tool's simplicity.
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 single parameter 'site' is not described in either schema or description. Schema description coverage is 0%, and the description fails to explain what value to provide or its purpose, leaving the agent guessing.
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' and the resource 'site singleton', listing example fields (title, code, data, languages). It distinguishes from sibling mutation tools like site_update by emphasizing read-only nature.
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?
No explicit when-to-use or when-not-to-use guidance is provided. The readOnlyHint annotation implies safe usage, but the description does not elaborate on context or alternative tools for site data.
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?
Consistent with annotations (readOnlyHint), adds return shape context but no new behavioral traits beyond what annotations and schema imply.
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 sentences with key information front-loaded, no redundant text.
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?
Covers return shape and use case but lacks pagination details and parameter explanation; adequate for a simple list tool.
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 has 0% description coverage and the description does not explain the 'site' parameter, leaving its meaning and format ambiguous.
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 lists all tags, includes HTTP method and return shape, distinguishing it from sibling tools like tag_get.
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 use case ('categorising articles / suggesting related content') but no explicit contrast with alternatives or 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint, destructiveHint, and idempotentHint. The description adds value by listing the returned fields (title, path, body, etc.), giving agents concrete expectations beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence followed by a parenthesized list of fields. Every word serves a purpose, and it is appropriately terse for a simple retrieval 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 low complexity, presence of annotations, and lack of output schema, the description provides the return fields which is helpful. However, it does not clarify parameter constraints (e.g., article_id must be an integer) or potential error conditions.
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 has 0% description coverage, and the description does not explain the parameters 'site' or 'article_id' beyond referencing 'by id.' It fails to add meaning about parameter types, formats, 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 clearly states the action: 'Get full article details by id.' It lists the specific fields returned, distinguishing it from sibling tools like article_create, article_update, and article_delete.
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 marks the tool as read-only, implying it is safe for retrieval. However, it does not explicitly state when to use it versus alternatives (e.g., articles_list) or provide exclusions, relying on context from sibling names.
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?
Annotations already provide readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds no additional behavioral context beyond restating 'Read-only'. This is adequate but does not go beyond what annotations convey.
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 core purpose. 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 simple (get by id) and annotations cover safety. No output schema, so return format is not described, but this is standard. Missing error handling info (e.g., 404), but overall nearly complete for the operation.
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 coverage is 0%, meaning the description does not describe parameter semantics beyond the schema. However, the schema parameter names ('site', 'discount_id') are self-explanatory. The description adds no extra meaning, such as format 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 clearly states 'Get a single discount by id', specifying the verb and resource. It distinguishes from sibling tools like discounts_list (listing) and discount_update/discount_delete (mutation).
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 indicates it's a read-only operation and provides the endpoint. However, it does not explicitly mention when to use this tool vs alternatives like discounts_list or discount_update. The tag 'Read-only' implies safe usage but 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?
Annotations declare readOnlyHint=true and idempotentHint=true. The description adds context about per-language translations and the relationship to product price interpretation, complementing the annotations without contradiction.
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, with the main purpose in the first sentence and additional context in the second. It is well-structured and front-loaded, though slightly verbose in listing fields.
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 one parameter with no schema description and no output schema, the tool description should explain both input and output. It lists returned fields but omits what 'site' is, leaving a gap despite adequate context on usage.
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 only parameter 'site' has no description in the schema (0% coverage) and the tool description does not explain its meaning or expected format. The description lists returned fields but fails to clarify the input 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 'Get ecommerce store settings' with a specific verb and resource, and lists example fields. It is distinct from the sibling 'ecommerce_settings_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 Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly marks the tool as 'Read-only' and explains its role as the source of truth for 'price_entry_mode', helping agents decide when to use it vs. product tools. However, it does not explicitly 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?
Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. Description adds fields returned and purpose, reinforcing the read-only nature but not adding new behavioral traits.
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 states purpose and returned fields, second gives usage hint. No unnecessary words, 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?
Describes return fields and provides usage context. Lacks details on parameter format, pagination, or error conditions, but sufficient for a simple list tool.
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 has one required parameter 'site' with no description. The description does not explain what 'site' should be (ID, name, etc.), leaving the agent to infer from 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?
Clearly states 'List all languages on the Voog site' with specific fields, distinguishing it from sibling tools like language_create and language_delete.
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 guidance: 'Use the returned ids for page_create.language_id / article fields.' However, does not mention when not to use it or 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?
Annotations indicate destructiveHint=true and readOnlyHint=false, but description adds context: irreversibility and that templates referencing deleted file will render with empty content, going beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is concise with two sentences covering key points: action, irreversibility, force requirement, and side effect. Well front-loaded but slightly fragmented.
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, description covers critical behaviors: irreversibility, force requirement, and template impact. Missing explanation of parameters and error conditions, but overall adequate for a simple delete 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 0%, so description must compensate. It explains the 'force' parameter's necessity but does not describe 'site' or 'asset_id', providing only partial semantic help.
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 'Delete a layout_asset' with specific verb and resource, and distinguishes from sibling tools like layout_asset_create/update by emphasizing irreversibility and force requirement.
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?
Description mentions that the tool 'Refuses without force=true', providing a clear usage condition, but lacks explicit guidance on when to use vs alternatives or 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only, non-destructive, and idempotent behavior; the description reinforces 'Read-only' and adds the detail about the price mode dependency. It also reveals the ?include= parameter syntax to expand data, which is not in the schema, providing additional transparency.
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 three sentences, front-loading the main action and key fields. It is concise and to the point, with no wasted words. The optional include syntax could be split into a separate note but does not harm 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 no output schema, the description adequately explains what is returned (variants, variant_types, translations) and the price mode nuance. It does not cover error cases or edge cases, but the core behavior is clearly communicated, making it sufficient for most use 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?
Both parameters (site, product_id) have descriptions in the schema (100% coverage), so the description does not need to add much, but it also doesn't elaborate on them. The mention of the ?include= parameter is extra but not part of the schema, which could confuse. Overall, the description adds minimal value beyond the schema for 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 retrieves full product details by ID, listing specific included fields (variants, variant_types, translations). It gives a clear verb-resource pair ('get product'), but does not explicitly differentiate from similar 'get' tools like product_update or product_create, which is acceptable for a read-only retrieval 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?
Provides explicit guidance on when to call ecommerce_settings_get to determine price entry mode before using price fields, and advises using effective_price for customer-facing pricing. Does not mention when to avoid using this tool, but as a read-only operation, the guidance is sufficient.
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?
Annotations already declare readOnlyHint, destructiveHint, idempotentHint. Description adds the endpoint method (GET) and the return shape, providing moderate additional context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two efficient sentences: first states action and endpoint, second lists return fields and a usage hint. No superfluous 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?
Covers the tool's purpose, output shape, and a key prerequisite. Lacks detail on the 'site' parameter but overall adequate for a simple list tool with strong annotations.
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 50% (only article_id has a description). The description reinforces article_id's purpose but omits the 'site' parameter, leaving it unexplained. Baseline 3 with partial improvement.
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 action ('List comments on an article'), provides the HTTP endpoint, lists the returned fields, and distinguishes from sibling mutation tools like comment_delete and comment_toggle_spam by emphasizing 'Read-only'.
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 specifies the prerequisite 'Use article_id from articles_list', and the read-only nature implies it's for retrieval, not modification. While it doesn't explicitly exclude misuse, 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate mutability (readOnlyHint=false) and non-destructiveness (destructiveHint=false). The description adds behavioral details: 'Body is FLAT.' and the precedence rule for element_definition_id over title, and auto-generation of path. These go beyond the annotations without contradicting them.
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 very concise, consisting of two sentences with key information front-loaded. Every sentence adds value: the purpose, the flat body requirement, and the required/optional breakdown. No unnecessary 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?
The tool has 7 parameters and no output schema. The description covers conditional requirements, auto-generation, and the values parameter. However, it lacks details on return values, error handling, and the site parameter. The error about required parameters also detracts from completeness.
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 high (86%), so baseline is 3. However, the description misstates required parameters: it claims element_definition_id or element_definition_title is required and omits site, which contradicts the schema's required list. This error significantly misleads the agent, reducing 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 clearly states 'Create an element (POST /elements).' This is a specific verb+resource combination that distinguishes the tool from sibling tools like element_update, element_delete, and element_get. The mention of the HTTP method further clarifies the action.
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 describing what it creates, but it does not explicitly compare with sibling tools or provide when-not-to-use guidance. However, the context is clear enough for an agent to infer when to use this tool versus others like element_update.
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 confirms the tool is read-only, aligning with annotations, and adds context about mutation handling being deferred to another API. This goes beyond the annotations by explaining how mutations should be performed.
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 concise sentences that front-load the core purpose and return structure, then immediately provide usage guidance. Every sentence adds value 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?
Given the lack of an output schema, the description adequately describes the return fields but omits details about the 'site' parameter. This gap reduces completeness for a simple list tool.
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 description does not explain the 'site' parameter at all. With 0% schema description coverage, the description should clarify the parameter's meaning and format, but it fails to do so, leaving ambiguity.
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 lists element definitions with specific fields (id, title, property_keys) and explicitly tells how to use the returned id for element_create, which distinguishes it from similar sibling tools like elements_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?
The description indicates this tool is read-only and directs mutations to voog_admin_api_call, providing clear guidance on when to use this tool versus alternatives. It could be more explicit about not using it for filtering or other operations, but the guidance is sufficient.
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?
Annotations already carry readOnlyHint, destructiveHint, idempotentHint. Description adds 'full values hash' but does not expand on behavioral traits beyond what annotations already 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?
Two sentences, no filler. Front-loaded with purpose and output. Every sentence 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?
Simple tool (get by id) with no output schema. Description covers purpose and output. Could add more on what 'full values hash' entails but enough for typical 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?
Schema coverage is 50% with one parameter (element_id) described. Description does not add meaning to the site parameter but reinforces element_id's origin via reference to elements_list. 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?
States 'Get a single element by id' with verb and resource clearly. Mentions 'full values hash' to describe output. Distinguishes from sibling 'elements_list' to find ids.
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?
Explicitly says when to use the tool (get by id) and directs to 'elements_list' to find ids, providing context. Lacks explicit 'when not to use' but sufficient for a simple retrieval.
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?
Annotations already declare read-only and idempotent; description adds endpoint and fields, consistent with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Short, front-loaded with key info (purpose, endpoint, fields), no wasted sentences.
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?
Describes returned fields but omits explanation of the 'site' parameter and does not mention missing output schema.
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 has 0% description coverage for the required 'site' parameter; description does not explain its purpose or allowed values.
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 'List all payment gateways' with HTTP endpoint and returned fields, distinguishing it from siblings like products_list or orders_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?
No explicit when/alternatives, but context is clear for a unique list tool; no sibling confusion.
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?
Annotations indicate readOnlyHint=false and destructiveHint=false, consistent with creating a new product. The description discloses that the new product inherits status='draft' and returns full payload with new_id and new title. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences: the first states the action and endpoint, the second provides workflow guidance and return value. It is concise and well-structured without any 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?
While the description covers the action, return value, and workflow, it lacks explanation of input parameters. With no output schema, it partially covers output but is incomplete for a tool with two undocumented parameters.
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 coverage is 0%, but the description does not explain the two parameters (site and product_id). It only names the endpoint, which implies product_id but gives no details about their meaning or required format.
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 'Duplicate a product' and provides the HTTP endpoint. It distinguishes from siblings like product_create and product_update by specifying that the duplicate inherits status='draft' and suggests chaining with 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 description advises using product_update after editing to make the duplicate public, which implies when to use and provides an alternative workflow. However, it does not explicitly state when not to use compared to product_create or other 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?
Annotations already indicate destructive hint. Description adds details on duplicate id collapsing, no empirical batch-size cap, and response format, but omits the force requirement for 'all' target.
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?
Well-organized with summary, warning, bullet points. Front-loaded but includes a slightly verbose note about batch-size cap with a specific date and name.
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?
Provides response format and clarifies behavior (dedup, batch), but misses explanation of the force parameter and site parameter, and lacks guidance on error handling or prerequisites.
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 high (75%), so description adds moderate value by listing allowed actions and response shape, but lacks documentation for the site parameter and does not compensate fully for its absence.
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 it applies the same actions to many products in one request, distinguishing from product_update for per-row varied edits. Includes endpoint URL.
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?
Explicitly contrasts with product_update for different use cases, but does not mention the force parameter or when to use alternative tools like products_list.
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?
Discloses that the tool refuses without force=true and that deletion is only reversible by re-creation, adding behavioral context beyond the annotations' destructiveHint.
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 fluff, front-loaded with the action.
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?
Adequate for a simple tool but leaves parameter details to be inferred from schema alone.
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 coverage is 0%, and the description only mentions force in a usage context without explaining its semantics. No detail on site or redirect_id.
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 deletes a redirect rule, distinguishing it from sibling tools like redirect_add and redirect_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?
Explicitly mentions the force=true requirement, providing clear usage guidance. However, it does not explicitly compare to sibling tools or state 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.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description claims a read-only backup, but the annotation readOnlyHint is false, creating a direct contradiction. While the description adds many behavioral details (overwrite behavior, partial snapshot handling, _meta.json), the contradiction undermines trust. The description does not clarify why readOnlyHint is false.
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 comprehensive yet concise, with a logical structure: it opens with the tool's scope, then covers default behavior, overwrite flag, required pre-flight contexts, and the manifest output. Every sentence serves a purpose, 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?
Given the complexity (many resources, overwrite behavior, error handling, manifest), the description covers most aspects. However, it does not explicitly describe the tool's return value (though it implies success through file writing). The lack of output schema is not critical, but an agent might want to know what the tool returns besides writing files.
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 three parameters have descriptions in the input schema (100% coverage). The description adds valuable context: it explains the default behavior of output_dir (fresh vs existing), the semantic of overwrite (authorizing writing into existing dir, distinct from force), and the relationship to automation/cron. This 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 it is a comprehensive read-only backup of all mutable Voog resources, listing many specific resource types. It distinguishes from sibling tools like layouts_pull or pages_snapshot by being a full site backup, and it identifies when to use it (pre-flight for risky operations).
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 guidance: it is required pre-flight before risky operations like layout rename, mass push, or page_delete. It also explains the default refusal to overwrite and the overwrite flag for automation. This clearly establishes 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate idempotency and non-destructiveness. The description adds important behavior: keys starting with 'internal_' are rejected client-side. It also mentions the HTTP method, aligning with annotations. No contradictory information.
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 brief: two sentences with a clear structure. The first sentence states the action and HTTP method, the second provides an alternative and a constraint. Every sentence adds value 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?
Given the required parameters and lack of output schema, the description covers the core operation, key deletion alternative, and a security constraint. It does not mention overwriting behavior, but that is implied. Combined with schema descriptions, it is sufficiently complete.
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 25%, and while the value parameter's description is detailed (non-null, nested storage), the main description does not explain site, article_id, or key beyond their basic role. The description adds minimal semantic value for these 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 sets a single article.data.<key> value, with the HTTP method included. It differentiates from the sibling tool article_delete_data, 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 Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells when to use article_delete_data instead (for deletion) and warns about rejected 'internal_' keys. It lacks guidance relative to other data-related siblings but provides sufficient context for common use cases.
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?
Annotations already indicate read-only, non-destructive, and idempotent. The description adds that the tool returns 'full pages array — one entry per language', which is useful context beyond annotations. No contradictions, but no mention of rate limits or other 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?
Two sentences, front-loaded with the main purpose. The second sentence adds specific usage guidance. No wasted words, though the structure could be slightly improved by separating parameter explanations.
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 no output schema, the description partially explains the return value (full pages array per language) but not the exact structure. For a simple get operation with two required params, it's adequate for usage but leaves parameter details unexplained.
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 has two required parameters (site, node_id) with 0% description coverage. The description only mentions 'node id' in usage context but does not explain 'site' or the format/constraints of node_id. With no parameter descriptions, the agent may guess incorrectly.
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 a single node by id' with the specific verb 'Get' and resource 'node'. It distinguishes from siblings like 'nodes_list' by mentioning 'full pages array — one entry per language' and provides a specific use case for parallel translation.
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 when preparing a parallel translation' and outlines a workflow: 'read the node id from one page, then pass node_id to page_create with the second-language details'. This provides clear when-to-use and an alternative tool (page_create).
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?
Annotations already provide idempotentHint=true and destructiveHint=false. The description adds that the operation is reversible and returns a per-id breakdown of success/failure, which goes beyond the annotations and helps the agent understand the return format.
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: first states the main function, second adds key details (reversible, return format). No unnecessary words. Well-structured and front-loaded.
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 bulk update tool with full schema coverage and annotations, the description covers all essential aspects: what it does, that it's reversible, and what the return value looks like. No gaps given 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 coverage is 100%, so baseline is 3. The description does not add new information about the parameters beyond what the schema already provides; it merely rephrases the purpose. The schema descriptions for site, ids, and hidden are clear and 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 it does bulk toggling of the hidden flag on pages. The verb 'toggle' is clarified by the reversible nature and the hidden parameter. It distinguishes well from siblings that handle other page operations like create, delete, or set_data.
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?
No explicit guidance on when to use this tool versus alternatives like page_update for single page hidden changes. The bulk nature is implied by the name and description but not directly compared to other 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?
Beyond annotations (idempotentHint=true), the description adds that it uses PUT and that 'internal_*' keys are refused client-side. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core action, includes key constraints and sibling reference. No redundant info.
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?
Adequate for a simple setter with 3 params. Missing explicit explanation of 'site' and 'value' roles, but overall complete for the operation type.
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?
With 0% schema description coverage, the description adds minimal parameter insight. Only 'key' gets partial explanation via the internal keys note; 'site' and 'value' are not described at all.
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 'Set site.data.<key> to a value' with HTTP verb and resource path. Distinguishes from sibling site_delete_data by referencing 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?
Provides explicit alternative for deletion (site_delete_data) and notable constraint on 'internal_*' keys. Lacks comparison to similar set tools like page_set_data or article_set_data, but context is clear for its scope.
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 adds value beyond annotations by specifying the HTTP method (GET) and explaining what texts contain. It also provides a practical tip for locating the text_id. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences: purpose+endpoint, resource explanation, and id location guidance. No unnecessary words, front-loaded with essential info.
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 strong annotations, the description covers retrieval and id source. It lacks mention of response format or error handling, but these are implicit for a GET operation. Adequate but not exhaustive.
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 0%, so the description must explain parameters. It adds meaning for text_id (integer, sourced from content areas) but does not describe the 'site' parameter at all. This partial compensation warrants a low 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 clearly states the action (get), the resource (text resource by id), and includes the HTTP endpoint. It explicitly distinguishes the tool's purpose from siblings by specifying it retrieves text-type content areas.
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 guidance on how to find the text_id via a specific path, which implies the prerequisite step. However, it does not explicitly mention when to use this tool vs. other get tools (e.g., article_get), though the context is 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?
Annotations are all false, so the description carries the burden. It mentions creation (not read-only) and error behavior (422), but does not disclose idempotency, duplicate handling, or safety beyond that. Some behavioral context is added, 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 plus a concise matrix, all front-loaded and free of redundancy. Every sentence provides essential information, making it efficient and easy to scan.
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 no output schema, the description does not explain what the tool returns (e.g., created webhook ID). It covers parameter semantics well but lacks return value information. With 8 parameters and minimal annotations, it leaves some gaps in 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?
Schema coverage is 88% with descriptions. The description adds value by clarifying required vs optional, defaults (enabled=true, source='api'), and the target-event matrix. However, it omits the 'site' parameter (required) from the description text, relying solely on 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 'Create a webhook (POST /webhooks)', identifies the HTTP method and endpoint, and specifies that the body is flat (no envelope). This distinguishes it from sibling tools like webhook_delete, webhooks_list, and webhook_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 description lists required and optional parameters with defaults (enabled, source), and provides a detailed matrix of valid target+event combinations. It also notes that Voog returns 422 for invalid combinations, guiding proper use. However, it does not explicitly state when to use this tool over 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?
The description discloses the tool is 'Read-only,' which matches the annotations readOnlyHint: true, destructiveHint: false, and idempotentHint: true. It also lists the fields returned, providing additional behavioral context. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise with two sentences, no redundant words, and essential information front-loaded. Every sentence 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?
Considering there is only one parameter, no output schema, and annotations already cover safety, the description covers the essential aspects: what it does, what it returns, and how to use the results. The missing explanation of the 'site' parameter prevents a perfect score.
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 input schema has one required parameter 'site' with no description, and schema description coverage is 0%. The description does not explain what 'site' represents or how to specify it (e.g., site ID or name). This is a significant gap for a required 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 'List all webhooks on the site' and enumerates the fields returned (id, enabled, target, event, url, target_id, description). It uses a specific verb 'List' and specifies the resource 'webhooks on the site,' distinguishing it from sibling tools like webhook_create, webhook_delete, and webhook_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 description instructs to 'Use the returned id for webhook_update / webhook_delete,' providing clear guidance on how to use the output. It also explicitly states 'Read-only,' setting expectations. However, it does not explicitly state when not to use the tool or mention alternative tools for other operations.
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?
Annotations already indicate idempotentHint=true and non-destructive. The description adds context about partial updates and flat body structure, which is helpful but does not disclose additional behavioral traits beyond what annotations provide. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, dense sentence that conveys all essential information: method, partial update, body structure, and required field constraint. No unnecessary words, highly efficient.
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?
While the description covers the core behavior and constraints, it omits details about return values or error handling. With no output schema, the agent might need to infer the response format. However, for a PUT update, the behavior is standard enough to be acceptable.
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 89%, so most parameters are already documented. The description adds a critical constraint: 'At least one updatable field besides webhook_id is required,' which is not in the schema. It also clarifies the body format (flat), adding 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 clearly states the tool's purpose: 'Update a webhook (PUT /webhooks/{id}).' It specifies the HTTP method, partial update mechanics, and required fields, distinguishing it from siblings like webhook_create or webhook_delete.
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 usage guidelines: 'Partial — supply ONLY the fields to change' and 'At least one updatable field besides webhook_id is required.' This instructs the agent on how to call the tool correctly, though it does not explicitly mention when not to use it or 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?
Annotations already indicate destructiveness; description adds that force must be true and past orders are unaffected, providing extra context beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences that convey the essential information without superfluous 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?
Covers the main delete action, force requirement, and effect on past orders. Could mention irreversibility but is sufficient for a delete tool with annotations.
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?
With 0% schema description coverage, the description partially compensates by noting force=true requirement but does not clarify the site or cart_rule_id 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 action (Delete a cart rule) and provides the endpoint. It distinguishes this tool from sibling tools like cart_rule_create or cart_rule_update by specifying the delete 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?
Explicitly mentions that force=true is required and that past orders are unaffected. However, it does not explicitly contrast with alternatives like cart_rule_get or cart_rule_update.
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 adds value beyond annotations by disclosing that Voog does not support description/image_id on categories despite some documentation suggesting otherwise, based on empirical verification. This is a notable behavioral trait not covered by annotations. However, it does not mention permissions or 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 extremely concise (two sentences plus a note) and front-loads the purpose. Every sentence provides essential information, and the empirical note is valuable without being verbose.
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 4 parameters and no output schema, the description covers the key aspects: required/optional, auto-generation, and a known limitation. It does not detail the response structure or error handling, but it's sufficient 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.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% (no property descriptions in schema), so the description carries full burden. It explains that name is required, slug is optional and auto-generated if omitted, and parent_id is for sub-categories. This adds meaningful semantics beyond just listing 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 starts with 'Create a category' and includes the HTTP endpoint, making the action and resource clear. It specifies required and optional parameters, and it's distinct from sibling tools like category_update or category_delete.
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 notes that slug auto-generates if omitted and parent_id is for sub-categories, which provides some context. However, it lacks explicit guidance on when to use this tool versus others (e.g., root vs sub-category, or compared to batch creation endpoints).
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?
Annotations indicate mutability, non-destructiveness, and idempotency. The description adds partial update behavior and the envelope format. It does not contradict annotations but lacks details on authentication, rate limits, or 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 pack essential information: action, endpoint, envelope, and partial constraint. 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?
Covers core usage, partial update detail, and required optional fields. Without an output schema, a note on return value or error handling would improve completeness, but the current description is sufficient for basic 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?
With 0% schema description coverage, the description compensates by stating that at least one of name/slug/parent_id must be supplied, adding critical constraint beyond the schema's required fields. It also explains the envelope structure, enhancing parameter 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 the tool updates a category, specifies the HTTP method and endpoint (PUT /admin/api/ecommerce/v1/categories/{id}), and indicates partial update with mandatory fields. It unambiguously distinguishes from sibling tools like category_create or category_delete.
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 mentions partial update and required fields, providing clear context. However, it does not explicitly compare to alternatives or state when not to use this tool (e.g., preferring bulk update).
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?
Annotations already indicate idempotentHint=true, readOnlyHint=false, destructiveHint=false. The description adds behavioral details: PUT body is flat, update is idempotent, and the requirement for at least one field. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the purpose, and includes only essential details. Every sentence adds value 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?
For an update tool with 4 parameters and no output schema, the description covers the essential aspects: function, idempotency, flat body requirement, and field constraints. It omits error handling or auth requirements but is generally 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 50% (body and metainfo have descriptions in schema). The description adds context about the flat PUT body and the requirement to supply at least one of the two optional fields, but does not explain the `site` or `content_partial_id` parameters beyond being required.
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 'Update' and the resource 'content partial', defines what content partials are, and distinguishes this from sibling tools which target different entities. The HTTP method and endpoint are also mentioned.
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 critical usage constraints: at least one of `body` or `metainfo` must be supplied, and the operation is idempotent. However, it does not explicitly state when to use this tool over alternatives, nor does it mention prerequisites 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.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds valuable behavioral context beyond annotations: it explains that the deletion only prevents future use and that past orders retain the discount record. This complements the destructiveHint and idempotentHint annotations without contradiction.
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: a single sentence that starts with the action, then the endpoint, requirement, and behavioral nuance. Every part is informative with no redundancy or fluff.
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 core action and key nuance (past orders unaffected) but is incomplete regarding parameter definitions. Given the simple tool and presence of annotations, it is adequate but could be improved by explaining 'site' and 'discount_id'.
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?
With 0% schema description coverage, the description must explain all parameters. It only addresses 'force' ('Requires force=true') but provides no explanation for 'site' or 'discount_id', leaving the agent to infer their meaning from names and the URL path.
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 action ('Delete a discount'), includes the HTTP method and endpoint path, and distinguishes it from sibling tools like discount_create, discount_get, discount_update, and discounts_list by its 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 gives clear usage context: requires force=true and explains the effect on past and future orders. However, it does not explicitly contrast with alternatives or provide when-not-to-use guidance, though the uniqueness is 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?
Annotations provide idempotentHint=true, and description adds client-validated enum constraints. No contradictions, but the description could disclose more about side effects or error states.
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?
Concise, front-loaded with purpose, and every sentence provides necessary information 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?
Given 15 parameters and no output schema, the description covers partial update behavior and enum constraints. Could mention response format or that discount_id is required, but overall complete for an update 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?
With 0% schema coverage, the description adds value by enumerating enum-restricted fields and their allowed values, helping the agent understand constraints without detailed param 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 the tool updates a discount, specifies the HTTP endpoint, and distinguishes from siblings like discount_create by noting it's a partial 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?
Indicates partial update with at least one field required and lists enum restrictions. While it doesn't explicitly compare to alternatives, the context from sibling tools is sufficient.
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?
The description's 'Re-order or re-parent' implies mutation, consistent with readOnlyHint=false. The idempotentHint=true from annotations is not echoed in the description, but no contradiction exists. The description adds context about query-string param usage but doesn't significantly expand on behavioral traits beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, well-structured, and front-loaded with the core action. Every sentence adds value, including the scope note and docs reference. 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 5 params (2 required) and no output schema, the description covers purpose, usage, parameter semantics, and scope. It references related tools for ID discovery. It lacks details about return values or error states, but for a reorder tool, the description is largely 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 description explains the role of page_id, before, and after in plain language, adding value over schema descriptions (e.g., 'supply at least one of' and mutual exclusivity implied). With 80% schema coverage, it effectively compensates.
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 'Re-order or re-parent an element instance' and distinguishes from element_definitions (schema) and sibling tools like node_move. It specifies the HTTP method and path, 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 Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains that inputs are query-string params, requires at least one of page_id, before, or after, and references elements_list for finding IDs. It doesn't explicitly state when not to use this tool but provides clear context and 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?
Annotations already indicate idempotentHint=true, which aligns with the description's 'set' operation. The description adds behavioral details: keys starting with 'internal_' are server-protected and rejected, and null values are not allowed (deletion handled by sibling). This adds value beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the action and HTTP method. Every sentence adds value: operation, sibling reference, and key constraint. 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 set operation with no output schema, the description covers the core action, key constraints, and value type rules. It lacks auth requirements or return value hints, but these are somewhat implied by the tool's nature. The sibling context helps.
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 only 25% (only 'value' has a description). The description adds meaningful context for 'value' (types allowed, null prohibition, nesting behavior) but does not explain 'site', 'page_id', or 'key'. This partially compensates for the schema gaps.
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 it sets a single page.data.<key> value via PUT. It distinguishes from the sibling tool 'page_delete_data' for deletion, making the purpose clear 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 an explicit alternative for deletion (page_delete_data) and warns about internal keys being rejected. However, it does not offer further guidance on when to use this tool versus other page-related siblings like page_update or page_set_layout.
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?
Annotations declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and the description adds 'Read-only' and lists returned fields, which aligns and adds value. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, front-loaded with the purpose and key details. Every word is informative and no 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 the absence of an output schema, the description adequately explains the fields returned and default behavior. However, it omits details on pagination, sorting behavior despite a sort parameter, and result format beyond fields.
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 clear descriptions for all parameters. The description adds meaning by stating default behavior (no filters returns everything) and listing the fields returned, which is not in 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 'List pages on the Voog site' specifying the verb and resource, and lists the returned fields. It distinguishes from sibling tools like 'page_get' by being a list operation.
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 mentions that all filters are optional and with no filters it returns every page, providing usage context. However, it does not explicitly compare to alternatives like 'page_get' or other list 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?
Annotations already indicate idempotentHint=true and non-destructive/non-read-only. The description adds context about creating directories and overwriting existing pages.json, which are useful behavioral traits not fully captured by annotations. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no fluff. The first sentence immediately states the core action, and the second adds necessary context and usage guidance. 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 tool with 2 simple required parameters and no output schema, the description adequately covers what the tool does, what files it produces, and when to use it. It lacks details on error handling or performance but is sufficient for selection and 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 schema already fully describes the parameters. The description adds minimal extra meaning beyond what is in the schema (e.g., the output file names are already in the schema decription for output_dir). 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 uses a specific verb 'backup' and identifies the resource as 'all pages + per-page contents', clearly stating the tool's function. It also distinguishes itself from the sibling tool 'site_snapshot' by noting it is lighter and for page structure/contents only.
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 this tool over site_snapshot ('use this when you only need page structure and contents'). It also mentions that it creates directories if needed and overwrites existing files, providing context. However, it does not explicitly state when not to use it or list prerequisites like needing the site name from a previous 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?
Annotations already mark the tool as destructive. The description adds context that force=true is required to execute the delete and that deletion removes the tag from all associated articles, which goes beyond the annotation.
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 with 4 sentences, each adding value. It front-loads the core action and requires 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?
Given the destructive annotation and schema coverage, the description adequately covers the tool's purpose, prerequisites, and side effects. The lack of output schema is not a gap as per rules.
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 67% (site param lacks description). The description reiterates the force parameter's necessity but adds little new semantic meaning beyond what the schema already provides for tag_id and force.
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 'Remove a tag' and specifies the HTTP endpoint and method. It also notes the side effect of removing the tag from all articles, distinguishing it from read-only siblings like tag_get and tags_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?
The description advises running tags_list or tag_get first to confirm the id, and mentions the force parameter requirement. However, it does not explicitly state when not to use the tool or compare with 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?
Discloses that the operation creates a new asset, leaves the old one in place, and returns both ids. Consistent with annotations (non-readOnly, non-destructive, non-idempotent). Does not detail authorization or rate limits but covers the key behavioral trait beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences: first states the purpose and workaround, second details outcome and next steps. Front-loaded, 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?
Despite no output schema, the description documents the return (both ids), explains the workaround, and provides manual cleanup steps. Sufficient for an agent to correctly invoke and follow up.
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 clear parameter descriptions. The description adds no new meaning beyond the schema (repeats the filename constraints). Baseline 3 is appropriate because schema already 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?
Explicitly states 'Rename a layout_asset by creating a new one with the desired filename' – a specific verb, resource, and workaround for API limitation. Distinguishes from sibling tools like layout_asset_update, which cannot change filenames.
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?
Clearly explains when to use (when a filename change is needed, because PUT is rejected) and gives post-usage instruction (delete old asset manually after updating templates). Lacks an explicit 'when not to use' but context implies alternatives are inappropriate.
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?
Annotations indicate non-readOnly, non-destructive, non-idempotent. The description confirms it creates a discount via POST, and adds empirically verified enum values. It does not mention authentication, rate limits, or error behavior beyond client-side validation.
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 with the endpoint and required fields. The use of bullet-like enumeration organizes information well, though it could be slightly more 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?
Given no output schema and 14 parameters, the description covers enums and required fields but lacks information about return values, error handling, or behavior for optional fields. More details on the response or side effects would improve completeness.
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?
With 0% schema description coverage, the description compensates by listing all optional parameters, specifying enum values for 4 parameters, and noting date format (ISO8601). This adds significant 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 ('Create a discount'), specifies the HTTP method and endpoint (POST /admin/api/ecommerce/v1/discounts), and lists required fields. This distinguishes it from sibling tools like discount_update or discount_delete.
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 indicates when to use the tool (to create a discount) and provides required parameters. However, it does not explicitly mention when not to use it or compare with alternative tools like discount_update for modifications.
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?
Annotations are all false (readOnly, idempotent, destructive), so they provide little. The description compensates by disclosing an important encoding behavior: `data` crosses a JSON boundary, literal \uXXXX escapes arrive decoded, and raw U+2028/U+2029 and C0 controls are refused as a fingerprint of that issue. This adds real behavioral context beyond the schema, though it does not cover other aspects like response format or 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but not overly long. It front-loads the core purpose, then provides encoding warnings, alternative tools, and parameter guidance. Some redundancy exists (e.g., 'TEXT content only' and later 'this tool is for text assets'), and the image-upload protocol sentence is wordy, but every sentence contributes meaningful 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 create tool with no output schema and minimal annotations, the description covers key context: constraints, parameter requirements, encoding pitfalls, and alternatives. It does not mention the `site` parameter despite it being required in the schema, and it doesn't state what the successful response looks like. Still, it is reasonably complete for an AI agent to use 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 only 25% (only `data` has a description). The description adds value by listing `asset_type` enum values, explaining the encoding constraint on `data`, and stating required fields. However, it entirely omits `site` and gives no semantic context for `filename`. It partially compensates for the low schema coverage but not completely.
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 layout_asset' – a specific verb and resource – and immediately clarifies it is TEXT content only, distinguishing it from sibling tools like layouts_push and layout_asset_upload. It explicitly states the tool is for text assets (CSS/JS/HTML fragments), leaving no ambiguity about its 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?
The description provides explicit when-to-use and when-not-to-use guidance: use for text assets, avoid for images (use product_set_images), avoid for binary uploads (use layout_asset_upload), and avoid for tracked file deployment (use layouts_push). It names the exact alternative tools, making the decision tree 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?
Annotations already indicate readOnly=false, destructive=false, idempotent=true. The description adds useful context: PUT method, flat body, and limitation to title only, enhancing transparency beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the main purpose, no wasted words. Highly efficient.
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 simple mutation tool with no output schema. Covers purpose, alternatives, and request 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 67% (site parameter lacks description). The description adds no parameter-specific meaning beyond the schema, only a note on request format. Does not fully compensate for missing site description.
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 ('Update a node's title'), specifies the HTTP method and endpoint, and distinguishes from sibling tools like node_move and node_relocate.
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 alternatives for tree restructuring, implying when not to use this tool. Lacks explicit prerequisites like obtaining node_id from nodes_list, though that is covered in the schema.
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?
Annotations already declare readOnlyHint, destructiveHint, and idempotentHint. The description adds value by confirming 'Read-only' and listing the fields returned, establishing no hidden 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?
Extremely concise: one sentence plus a 'Read-only' tag. Front-loaded with action and resource, 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?
Given the simple input (single required parameter) and no output schema, the description fully covers purpose, inputs, and return fields. No gaps remain.
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 a clear parameter description ('Site name from voog_list_sites'). The tool description does not add meaningful additional semantics beyond restating the context, so baseline score 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 it lists all redirect rules on a Voog site and enumerates the returned fields (id, source, destination, redirect_type, active). It distinguishes itself from sibling tools like redirect_add, redirect_delete, and redirect_update by explicitly stating it's read-only.
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?
While not explicit, the read-only nature and listing function imply usage for viewing existing rules. The sibling tools are clearly for modifications, so the context is sufficient without explicit when-not statements.
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?
Annotations already declare readOnlyHint, destructiveHint, idempotentHint. Description adds context of HTTP method and the exact endpoint pattern, plus confirms the return shape. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short, clear sentences. Front-loaded with the core action. No unnecessary 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 read tool with two parameters and strong annotations, the description covers purpose, parameter sourcing, and behavior completely. No missing context needed for correct usage.
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 covers 1 of 2 parameters with description (tag_id). Description reinforces the source of tag_id from tags_list, but does not add information about 'site' parameter. Marginal value beyond 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?
Clearly states it gets a single tag by id, specifies the HTTP endpoint and return type (full Voog tag shape). Distinguishes from sibling 'tags_list' which is for discovering ids.
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?
Explicitly tells the user to use 'tags_list' to discover ids, providing a prerequisite step. Implicitly guides usage by stating read-only nature, but could be more explicit about when to use this vs other tag 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?
The description adds significant behavioral context beyond the annotations (destructiveHint=true, etc.), notably the irreversible nature ('IRREVERSIBLE — the key is removed permanently'), the force requirement, and the server-protected key restriction. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences long, each sentence providing essential information without fluff. It is front-loaded with the main action and logically 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 destructive tool with 4 parameters and no output schema, the description covers the key behavioral aspects: action, irreversibility, force requirement, and key restrictions. It does not specify the expected return status (e.g., 204), but this is not critical given the lack of output schema. Slightly more detail on the response could 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?
With only 25% schema description coverage (only the 'force' parameter has a schema description), the description adds value by explicitly stating that force must be true to execute the deletion. However, it does not detail the 'site', 'article_id', or 'key' parameters beyond their path usage, which the schema already provides as required. The baseline is 3 due to low coverage, and the description partially compensates.
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 deletes a specific key from an article's data, including the HTTP method and path. It distinguishes itself from siblings like article_delete (which deletes entire articles) and article_set_data (which sets data).
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 explains that force=true is required and that internal_ keys are rejected, providing clear usage conditions. However, it does not explicitly compare this tool to alternatives or state when to use it over article_set_data or article_delete, but the context from sibling names offers implicit 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?
Annotations already indicate readOnlyHint, destructiveHint, and idempotentHint as true/false. The description adds value by stating 'Read-only' and listing the returned fields. No additional behavioral traits (like pagination limits or side effects) are surfaced, but the description aligns with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description consists of two concise sentences that convey the tool's purpose, fields, filter optionality, and read-only nature. Every sentence adds value 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?
Given the 7 parameters (1 required), high schema coverage, and annotations, the description is mostly complete. It lists returned fields despite no output schema. Minor gap: no mention of pagination, but that is acceptable for a basic list 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 high (86%). The description confirms all parameters except site are optional, adding clarity beyond the schema. However, it does not explain parameter meaning 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 states the tool lists blog articles on the Voog site and enumerates the simplified fields returned. It unambiguously distinguishes this list operation from sibling tools like article_get or article_create.
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 notes all filters are optional and the operation is read-only, providing clear usage context. However, it does not explicitly contrast with sibling tools or state when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate the tool is idempotent and not read-only; the description adds that the body is flat and the endpoint is used by Voog's UI. This provides enough behavioral context beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three concise sentences: action, body format, and context/alternative. No wasted words, and the most important 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?
Given the tool's simplicity (4 params, no output schema), the description adequately covers purpose, parameters, and alternative tools. It is complete enough for an agent to use 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?
Schema description coverage is 75% (site missing). The description adds value by specifying the flat body format and the boolean nature of is_spam, which complements the schema's existing parameter 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 flips a comment's spam flag, specifies the HTTP method and path, and distinguishes the tool from siblings by noting that for other field edits, one should use voog_admin_api_call.
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 guidance: use this tool for toggling spam, and for other field edits use voog_admin_api_call. It implies the appropriate usage context without explicit when-not-to-use, but the alternative is clearly stated.
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?
Annotations already indicate destructiveHint=true and readOnlyHint=false. The description adds valuable behavioral details: the need for force=true (without it the call is rejected), the response code (204), and the prerequisite to confirm the id. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, each conveying essential information: what it does, the force requirement, and a prerequisite. It is concise and front-loaded with the core 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 delete tool with no output schema and three parameters, the description covers the action, return code, mandatory flag, and prerequisite verification. This provides sufficient context 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.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 67% with descriptions for element_id and force. The description reinforces the force parameter's requirement ('requires force=true') and echoes the need to get the id from elements_list, adding clarity. The site parameter lacks extra context, but overall the description enhances 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 explicitly states the action (Delete an element), the HTTP method and endpoint, the expected response (204), and key requirements (force=true). This clearly distinguishes it from sibling tools like article_delete or element_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 description provides clear guidance on when to use the tool (to delete an element) and a prerequisite (run elements_list first to confirm the id). It does not explicitly mention when not to use it or alternatives, but the context is sufficient for a delete operation.
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?
The description adds significant behavioral detail beyond the idempotentHint annotation, explaining reversibility and the JSON boundary edge case with literal \uXXXX escapes and refusal of raw U+2028/U+2029 and C0 controls. This is exactly the kind of context that helps an agent avoid subtle failures and does not contradict any annotation.
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 with a distinct role: core purpose, constraints/reversibility, and a niche gotcha with an alternative. No filler or repetition; it communicates dense information efficiently.
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?
It covers the main function, constraints, idempotency, reversibility, an edge case, and an alternative tool. It does not explicitly mention return values or error handling, but given there is no output schema and the operation is straightforward, 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?
Schema coverage is only 25% (only body has a description). The description deepens understanding of body by explaining decoding/escaping behavior, but site, layout_id, and title receive no added meaning beyond their names. It partially compensates for the low schema coverage but does not fully describe all 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 explicitly states 'Update a layout' with specific fields (body, title, or both), making the operation clear. It distinguishes itself from the sibling layouts_push by noting the latter is for byte-exact deployment of tracked .tpl files.
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 constraints ('At least one must be supplied', 'Reversible by calling again') and gives an explicit alternative for a specific scenario ('use layouts_push'). However, it does not compare with other layout-related siblings like layout_rename or layout_create, leaving some ambiguity about when to prefer this over them.
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?
Annotations already indicate idempotency and non-destructiveness. The description adds behavioral details like query-string parameter transport and HTTP method, enhancing the agent's understanding of the operation's side effects. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no fluff. Key information is front-loaded: the purpose and endpoint. Every sentence 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 no output schema, the description adequately covers the necessary information for invocation: parameters, their roles, and the nature of the operation (query-string, default position). Minor omission: no mention of error handling or permissions, but overall sufficient for an agent.
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?
While schema coverage is 75% (missing site description), the description adds meaningful guidance for parent_id and position (e.g., 'pass current to just reorder' and '1-indexed, Voog default 1'), exceeding the schema's own descriptions. This compensates for the missing site parameter description.
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 the tool moves/reorders a node within the page tree, explicitly mentioning the HTTP PUT endpoint and distinguishing between moving and reordering. This verb+resource combination is specific and differentiates from sibling tools like node_relocate.
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 useful guidance on how to use parent_id (pass current for reorder, new for move) and position (optional, 1-indexed, defaults to 1). However, lacks explicit comparison to sibling tools (e.g., node_relocate) or scenarios where this tool should not be used.
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?
Describes read-only nature, PII stripping, and force requirement. However, annotation 'destructiveHint=true' contradicts read-only claim.
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, no extraneous 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?
Covers key behavioral aspects for a simple get operation. Missing error handling or response details, but acceptable given 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?
Adds meaning to include_pii and force beyond schema (defaults, requirements). Slight complement to 50% 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?
Clearly states 'Get a single order by id' with HTTP path. Distinguishes from sibling 'orders_list' for listing.
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?
Implicitly indicates when to use (single order retrieval) vs listing. Provides conditions for include_pii usage but lacks explicit 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?
Annotations show it is not read-only, destructive, or idempotent; description adds that parent_id and node_id are mutually exclusive and explains multilingual binding behavior, which goes beyond structured fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (~100 words), front-loaded with purpose, and structured into required/optional lists and a separate multilingual note. No unnecessary repetition.
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?
Covers most important parameters but misses 'publishing' and does not mention return value (no output schema). Some optional fields like hidden and image_id are listed without elaboration, leaving minor gaps.
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?
With 0% schema description coverage, the description compensates by explaining each parameter's purpose, including constraints (e.g., parent_id vs node_id), examples (content_type values), and nested object (data).
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 page' and distinguishes required vs optional parameters. It explains the role of parent_id and node_id, differentiating page creation from sibling tools like page_duplicate or page_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?
Provides explicit guidance on when to use parent_id vs node_id for subpages and translations, and notes they are mutually exclusive. However, it does not explicitly mention alternatives like page_duplicate or page_update.
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?
The description discloses many behavioral details beyond annotations, such as required fields, validation of status enum, rejection of unknown keys, difference between POST and PUT, and dependency on price entry mode settings. Annotations are minimal, so the description carries the full burden well.
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 main purpose sentence followed by details. It could be slightly trimmed but remains clear and informative for a complex 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?
The description covers required fields, validation, argument shapes, and hints at results (new product id). It does not include error handling details or full return structure, but is adequate for an agent to use correctly.
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 description adds significant meaning beyond the input schema by explaining the three argument shapes, allowed keys, combinations, and legacy format. Even with 75% schema coverage, it enriches 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 'Create a new product (POST /products on ecommerce v1).' It specifies the verb and resource, and distinguishes from related tools like product_update by focusing on creation.
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 does not explicitly compare with sibling tools like product_update or product_duplicate, but it implies usage for creating new products. It provides guidance on required fields and argument shapes, which helps in correct usage.
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?
Annotations already declare readOnlyHint=true and destructiveHint=false, and the description aligns by saying 'Read-only'. It adds valuable context beyond annotations: the response shape is identical to the voog://products resource, price fields depend on settings.price_entry_mode, and the 'simplified' field list implies a partial representation. This goes beyond the baseline safety profile without contradicting annotations.
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 fairly long but every sentence serves a purpose, covering scope, field list, consistency, follow-up, filtering, and price-mode caveats. It front-loads the core action and is well-structured, though slightly verbose.
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?
Without an output schema, the description compensates by listing all returned fields. It also explains the resource consistency, price-mode dependency, and appropriate follow-up tool, making it complete enough for an agent to use the tool correctly. No pagination info is given, but not essential for a tool that lists all items.
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 both parameters already having descriptive comments. The description repeats the category_id mapping but does not add substantive meaning beyond what the schema provides. It does mention follow-up actions, but that's not parameter-level semantics. 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 opens with 'List all ecommerce products on the Voog site', a specific verb+resource statement that clearly distinguishes it from sibling tools like product_get (which targets a single product). It also enumerates the exact fields returned, reinforcing 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 Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states to follow up with product_get for per-variant stock, and to call ecommerce_settings_get to determine price mode before using price fields. This gives clear when-to-use and prerequisite guidance, differentiating it from 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?
Annotations already indicate mutation (readOnlyHint=false), non-destructive, and idempotent. The description adds the important behavior that site.code is immutable, which is a key constraint. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no filler. Front-loaded with purpose, then constraint, then alternative tool reference. Every sentence 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's simplicity (update singleton with two params) and lack of output schema, the description covers necessary usage and constraints. Could mention response or side effects, but not essential.
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 0%, but description explains 'attributes: flat root-level fields' and hints at what attributes are. However, it doesn't detail specific fields or the 'site' parameter semantics beyond identity. Partially compensates for 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 states the tool updates the 'site singleton' for flat root-level fields, distinguishing it from 'site_set_data' which handles per-key data. It gives specific verb and resource, and differentiates from sibling.
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 guidance: when to use (updating flat root-level fields vs per-key data using site_set_data) and a critical constraint (site.code is immutable and raises error). This helps the agent choose correctly.
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?
Annotations already declare readOnlyHint, destructiveHint, idempotentHint. Description adds value by explaining it is a GET request passthrough and that MCP hosts may skip confirmation prompts, though no contradictions. Could be more detailed about error handling or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose, no unnecessary words. Efficient and clear.
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 passthrough tool, description covers purpose, usage, and behavioral hints. Lacks mention of return format, but that is endpoint-dependent. Sibling tools listed provide context. Adequate for the 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 covers all three parameters with descriptions. Description adds example paths and states params optional, but does not significantly add meaning beyond 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?
Description clearly states it is a read-only Admin API passthrough forwarding GET requests, with a specific URL pattern and examples. Distinguishes from siblings by indicating it is for endpoints not covered by typed read 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?
Explicitly states when to use: when no typed read tool covers the endpoint, listing examples like forms, tickets, tags. Also notes it is read-only, so confirmation prompts may be skipped, providing clear usage context.
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?
Annotations already provide readOnlyHint, destructiveHint, and idempotentHint. The description adds value by explaining the HTTP method (GET), the URL structure, and additional query parameters like include and language_code, without contradicting 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?
Two concise sentences that front-load the purpose and efficiently convey the key usage details without unnecessary 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 the tool's simplicity and full schema coverage, the description is nearly complete. It explains the URL pattern and query parameters, though it could mention the expected response format (e.g., JSON) for perfect 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 input schema has 100% description coverage for all three parameters. The description further clarifies that the 'path' should start with '/' and provides examples, and mentions query parameters that go into the 'params' object, adding context 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 it is a read-only ecommerce API passthrough that forwards GET requests, specifying the URL template and supported query parameters. It distinguishes itself from sibling tools like 'voog_ecommerce_api_call' by emphasizing the read-only 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 indicates it should be used for read-only operations and that MCP hosts can skip confirmation prompts, but it does not explicitly contrast with other read tools like 'voog_admin_api_read' or mention 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate destructiveHint=true and readOnlyHint=false. The description adds value by stating 'Voog returns 204' (HTTP status on success) and the required 'force=true' flag, which are beyond what annotations 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?
Two concise sentences, front-loaded with the action and endpoint. Every sentence provides essential information without unnecessary verbosity.
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 includes the HTTP response code (204) and prerequisites. It does not cover error cases or side effects, but for a simple delete operation it is adequately 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?
Schema coverage is 67% (2 of 3 parameters have descriptions). The description adds meaning by explaining the requirement for 'force=true' and advising to retrieve the id via webhooks_list. The 'site' parameter lacks a description in the schema, but the description does not address it, slightly reducing 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 specifies 'Remove a webhook (DELETE /webhooks/{id})', which includes the verb 'remove', the resource 'webhook', and the exact HTTP method and endpoint. It clearly differentiates from sibling tools like webhook_create and webhooks_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?
The description provides explicit usage conditions: 'Requires force=true; without it the call is rejected' and 'Run webhooks_list first to confirm the id.' While it does not explicitly state when not to use it, the prerequisite and mandatory parameter are clearly communicated.
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?
Description explicitly states the tool is NOT idempotent, aligning with idempotentHint=false. It explains the autosaved fields convention and publish behavior (sets publishing:true atomically), adding behavioral context beyond annotations. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is well-structured with purpose first, then required/optional fields, then special behaviors. At 6 sentences, it is appropriately sized for the tool's complexity, though it could be slightly more concise without losing clarity.
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 11 parameters and no output schema, the description covers creation essentials, publish flow, and idempotency. It omits return value (e.g., created article ID) and error handling, but these are often inferred from the tool's nature. Overall, it's 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?
Schema description coverage is only 27%, but the description adds meaning for key parameters like path (auto from title), tag_names (array), data (custom dict), publish (default false), and explains autosaved fields. It compensates for low coverage, though not all 11 parameters are detailed.
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 starts with 'Create a new blog article' with specific verb and resource. It lists required and optional fields, clarifying the tool's purpose. Sibling tools like article_update and article_delete indicate distinct usage, so the description effectively distinguishes 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?
Description states when to use (to create articles) and notes non-idempotency, which guides repeat calls. However, it does not explicitly mention alternatives like article_update for editing or when not to use. Still, the context is clear for basic usage.
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?
Annotations declare destructiveHint=true, but the description adds crucial behavioral details: the call is rejected without force=true, and Voog returns 204. This provides safety and response info beyond the annotation, though permission requirements 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?
Three sentences covering HTTP method, return code, prerequisite, and a critical requirement, with no fluff. Well-structured for quick 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 simple delete operation and no output schema, the description sufficiently covers action, prerequisites, safety mechanism, and HTTP response. No critical gaps for an AI 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 already describes 75% of parameters, but the description adds context by linking to comments_list for the id and emphasizing the force flag requirement, enhancing understanding beyond schema details.
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 'Remove a comment' with specific verb and resource, and includes the HTTP method and URL path for precision. It distinguishes from siblings like comment_toggle_spam by focusing on deletion.
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 a prerequisite ('Run comments_list first to confirm the id') and a requirement ('Requires force=true'), providing clear usage context. However, it does not specify when not to use this tool compared to alternatives like comment_toggle_spam.
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?
Discloses partial nature, flat body, and required fields beyond annotations which already indicate idempotence and non-destructiveness.
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 sentences, front-loaded with purpose, no redundant 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?
Covers key aspects for an update tool, though could mention that the element must exist and does not specify return value.
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?
Adds critical constraint that at least one of title/path/values is required and confirms they are updatable, enhancing schema with 80% 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?
Clearly states action (Update), resource (element), HTTP method (PUT), and supports partial updates, distinguishing from element_create and element_delete.
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?
Specifies to supply only fields to change and requires at least one updatable field besides element_id, but does not explicitly mention when not to use or 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?
Beyond annotations (destructiveHint=true, idempotentHint=false), the description adds critical behavioral details: same filename creates a second asset, result is editable=false, Voog derives asset_type/content_type, and assets are served from /images not /photos. This significantly clarifies the tool's behavior without contradicting annotations.
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 in the first sentence and uses paragraphs logically. It contains some minor extras (issue #140 item 4) that aren't essential but don't harm clarity. Overall it's efficient for the amount of context it provides.
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 output schema, the description is reasonably complete: it explains the endpoint, serving path, asset types, editable=false, and duplicate behavior. It doesn't explicitly state the return value or error cases, but the provided context is sufficient 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.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 67% (site lacks description). The description adds some context about binary files and serving paths, but doesn't enhance parameter meaning beyond the schema's existing descriptions for filename and file_path (default, absolute path, allowed extensions). The site parameter remains unexplained in both description and schema, and the description doesn't fully compensate for the gap.
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: 'Upload a BINARY layout asset from disk', and clarifies scope (favicon, icon, font, inline image) with an explicit endpoint. It distinguishes itself from sibling tools by contrasting with layout_asset_create (text data only) and asset_upload (photos).
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 when-to-use and when-not-to-use guidance: binaries needed a raw curl call before, photos should use asset_upload, and layout_asset_create is for text data. It also warns about duplicate filenames and recommends asset_replace for replacement, going beyond a simple use case.
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?
The description discloses rich behavioral details beyond the annotations: content read directly from disk (avoiding JSON boundary decoding), files filter semantics, 200-without-persisting reported as failure, per-entry error capture without aborting the batch, and return breakdown. No contradiction with annotations (idempotentHint=true, readOnlyHint=false, destructiveHint=false).
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 well-organized, front-loading the core action, then filter behavior, critical warning, error handling, and pre-flight recommendation. A few sentences are long with embedded details, but each earns its place. Slightly tighter formatting would 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?
With no output schema, the description compensates by explaining the per-file success/failure breakdown and non-aborting error handling. It also mentions the pre-flight snapshot. Minor gaps remain (e.g., exact response format, how IDs are resolved from manifest), but overall it is complete enough for a deployment tool of moderate 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 input schema already covers all 3 parameters with descriptions (100% coverage). The description adds meaningful semantics: files=null/omitted means 'push all manifest entries', target_dir must contain manifest.json, and clarifies how file content is handled relative to layout_asset_update. This exceeds 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 clearly states the tool reads manifest.json and tracked files from target_dir and PUTs each to the type-mapped endpoint (layout or layout_asset), with explicit endpoint mapping. This specific verb+resource+scope distinguishes it from siblings like layouts_pull and layout_asset_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 description explicitly positions this as the 'BYTE-EXACT WAY' to deploy JS/CSS assets, contrasting with layout_asset_update's JSON decoding issue. It also recommends site_snapshot as a pre-flight. However, it doesn't provide comprehensive when-to-use/when-not-to-use guidance for all sibling 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?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds valuable detail about the return format (curated view with id, title, kind, ordered assets array with specific fields) and reiterates read-only, enhancing transparency beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the verb and resource, then return structure, then usage guidance. 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.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with 2 well-documented parameters and no output schema, the description fully covers the purpose, return contents, and intended usage. It also relates to sibling tools for a complete workflow, making it sufficient on its own.
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% (both parameters have descriptions), so the baseline is 3. The description doesn't add much about the parameters themselves, though it hints at the use case by mentioning 'discover asset ids and current titles', which indirectly clarifies the value of the media_set_id 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 purpose: 'Get a media_set (gallery) by id' with the specific endpoint. It distinguishes itself from sibling tools by framing it as a read operation for discovering asset info, contrasting with update tools like media_set_update_asset_titles.
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 given: 'Use this to discover asset ids and current titles before calling media_set_update_asset_titles.' This tells the agent exactly when to use the tool and names the related tool, providing clear context and an implicit alternative.
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?
Discloses read-only nature, the destructive hint for force (PII gate), and the rejection mechanism for include_pii without force. Adds value beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with purpose, each sentence adds value. Slightly long but efficient for the complexity.
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?
Covers purpose, filters, security considerations. No output schema, but that's acceptable. Could mention pagination, but not required.
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?
Adds meaning to parameters by explaining filter options and the security gate for PII. The site parameter lacks description but is compensated by 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?
Clearly states 'List ecommerce orders' with specific HTTP method and endpoint, distinguishing it from sibling tools like order_get.
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 optional filters and explains the special include_pii/force interaction, guiding appropriate use. Lacks explicit 'when not to use' but offers sufficient 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?
Annotations already indicate destructiveHint=true, readOnlyHint=false, idempotentHint=false. The description adds critical context: irreversible deletion, force=true required, and server-protected keys rejected, which goes beyond what annotations 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?
Two sentences, no superfluous words, front-loaded with essential information. Every sentence 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 tool's 4 parameters, no output schema, and existing annotations, the description covers all essential behavioral aspects (irreversibility, force requirement) and parameter significance (key naming restriction) adequately.
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 low (25%, only force has a description). The description adds meaning by explaining force's requirement and default, and mentions the internal_ key restriction. However, no additional meaning for site, page_id, or key beyond 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 'Delete' and the specific resource 'single page.data.<key>' along with the HTTP method and path, effectively distinguishing it from sibling tools like article_delete_data or site_delete_data.
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 by stating the endpoint and requirements (force=true), but does not explicitly guide when to use this tool vs. alternatives such as article_delete_data or site_delete_data. No when-not or alternative mentions.
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?
Annotations already declare idempotentHint=true and destructiveHint=false. The description adds critical behavioral context: asset_ids are translated to a specific envelope, sending variants alone wipes all variants, overlapping attributes and translations cause rejection, and validation catches unknown keys before round-trip errors. It also mentions reversibility.
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 well-structured with bullet points and clear sections for each argument shape. Every sentence adds value, though it is somewhat long. The front-loaded purpose and shape list help 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 complex mutation tool with nested objects and multiple modes, the description covers most scenarios (side effects, validation, legacy support). It does not describe the output or return value, which is a minor gap given no output schema. Overall, it is fairly complete for an agent to use 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?
Schema coverage is 67%, but the description compensates by explaining the three argument shapes, listing allowed keys for each, warning about variants/asset_ids behavior, and clarifying the 'force' parameter. The site and product_id parameters are not elaborated, but the schema already provides 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 starts with 'Update a product', clearly stating the verb and resource. It details three distinct argument shapes (attributes, translations, fields) and enumerates updatable fields, distinguishing it from sibling tools like product_create or product_delete.
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 extensive guidance: which argument shapes to use, their combinability, constraints (e.g., asset_ids translation, variants wipes with warnings, no overlapping translations and attributes), and prerequisites like checking price mode via ecommerce_settings_get. However, it does not explicitly state when not to use this tool versus 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?
The description discloses critical behavioral details beyond annotations: the race window in fallback mode, the idempotent nature (via PUT with publishing:true), and the rejection of mixed autosaved_args. Annotations (readOnlyHint false, destructiveHint false, idempotentHint true) are consistent and complemented by these 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 well-structured: a concise purpose sentence, a key explanation of why a separate tool is needed, and a clear two-mode breakdown. Every sentence adds value, and the most critical 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?
Given no output schema, the description could mention expected return values (e.g., published article object) or error scenarios. However, the mode selection and race condition are fully covered, making it adequate for an agent to use correctly. A minor gap exists regarding success behavior.
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 covers 60% of parameters with descriptions (autosaved_* group). The description adds significant meaning by explaining the mode logic and how these parameters control fast vs fallback path. For site and article_id, no extra info is provided but their purpose is self-evident.
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 'Publish an article' and explains the two modes, distinguishing this tool from article_update by highlighting the need for a separate tool due to the autosaved field copying requirement. The purpose is specific and well-differentiated from 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 provides explicit guidance on when to use the fast path (pass all three autosaved_* args) vs the fallback (pass none), and warns against mixed args. However, it does not explicitly state when to use article_update instead, though the context implies it.
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?
Annotations already provide readOnlyHint, destructiveHint, idempotentHint. The description reinforces 'Read-only' and adds useful behavioral context: include_values is off by default because values clutter, and recommends element_get for detailed data. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: one sentence for fields, one for filters, one for include_values caveat, and ends with 'Read-only'. No redundancy or unnecessary text.
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?
While there is no output schema, the description lists the fields returned. For a list tool, this is adequate. It references element_get for full shape. Could mention pagination, but not essential given 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?
Schema coverage is high at 90%. The description adds meaning beyond the schema by explaining the include_values default and clutter concern, and describing the filters parameter as an escape hatch with pattern 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 uses a specific verb 'list' with a clear resource 'elements', lists the returned fields, and distinguishes from element_get by recommending it for full shape. Sibling tools are also differentiated by context.
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 states when to use include_values (rarely) and advises using element_get for full shape. However, it lacks explicit when-not guidance compared to other list tools like articles_list, but the context implies this is for elements under a 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?
Annotations indicate readOnlyHint=false, destructiveHint=false, idempotentHint=false. The description adds context by explicitly stating it is NOT idempotent and mentions the return value (new id). It does not contradict annotations and provides useful behavioral cues.
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 (3 sentences), front-loaded with the main purpose, and every sentence adds value. No 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 create tool with 5 parameters (4 required), the description covers the non-idempotency, return value, and parameter-specific behaviors. Annotations are present and consistent. No output schema, but the return value is mentioned. Complete for the complexity.
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%. The description adds meaning beyond the schema: it explains the effect of 'kind' on behavior, defaults and ignored status of 'content_type', and constraints on 'title' (no '/', '\', or leading '.').
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 layout or component', references the HTTP endpoint, and distinguishes between kind='layout' and kind='component' with their respective behaviors. It is specific and actionable.
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 explains when to use each kind and notes that content_type is only relevant for layouts. It also warns about non-idempotency. However, it does not explicitly compare to sibling tools like layout_update or layout_delete.
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?
Annotations already indicate destructiveHint=true. The description adds valuable context: deletion is IRREVERSIBLE, Voog does not retain deleted pages, and force is a defensive opt-in. This goes beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences: purpose, critical warning, usage guidance. Front-loaded, no superfluous words. 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?
Covers purpose, usage, parameters, and behavioral aspects thoroughly. Lacks info on return value/error handling, but for a delete operation with no output schema, this is 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%, but description adds meaning: explains the force parameter's role (must be true to delete, defaults to false) and clarifies that site comes from voog_list_sites. Adds value beyond 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?
Clearly states 'Delete a page.' with specific verb and resource. Distinguishes from sibling tools like page_delete_data and page_duplicate by highlighting the force parameter and irreversibility.
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 the force=true requirement to prevent accidental deletion. Provides a concrete when-to-use alternative: run pages_snapshot or site_snapshot if the page might be needed later.
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?
Annotations are neutral (readOnlyHint=false, destructiveHint=false, idempotentHint=false). The description adds value by explaining that for 410, destination is ignored but still stored, and that defaults apply. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, each earning its place. It is front-loaded with the core purpose and follows with precise, essential details. No redundant or verbose language.
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 6 parameters (3 required, 1 enum) and no output schema, the description covers all essential behavioral aspects, parameter semantics, special cases, and defaults. It is complete without being overly long.
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%, yet the description adds significant extra context: examples (e.g., /old → /new), explanation of regexp and active flags, and clarification of 410 behavior. This goes beyond the schema's 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 'Add a redirect rule' and explains the tool's verb and resource. It distinguishes from sibling tools like redirect_delete, redirects_list, and redirect_update by being the creation tool. The examples and parameter details reinforce its unique 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 context for using the tool, including parameter defaults and special behavior for 410. However, it does not explicitly contrast with alternatives (e.g., 'use redirect_update to modify existing rules'), which would make it 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?
The description goes beyond annotations by explaining the full-replace nature of the underlying API and how the tool merges updates to preserve unspecified fields. It also notes reversibility, providing valuable behavioral insight.
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 clear sentences: purpose with constraints, underlying API behavior, tool's handling. No unnecessary words; each sentence adds distinct 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 no output schema and simple annotations, the description covers key aspects: what it does, required parameters, optional fields, merge behavior, and reversibility. It could mention the return value, but overall complete for an update 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?
With low schema coverage (14%), the description adds meaning by listing the optional fields and specifying the enum values for redirect_type. Required parameters (site, redirect_id) are not explained but their purpose is inferable from 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 explicitly states 'Update an existing redirect rule' and lists the updatable fields. It clearly distinguishes from sibling tools like redirect_add, redirect_delete, and redirects_list by focusing on 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 specifies that at least one of the optional fields must be supplied, guiding partial updates. It also explains the merge behavior to avoid pitfalls. While it doesn't explicitly say when not to use, the purpose is well-defined.
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?
Annotations indicate destructive behavior; description adds crucial details: irreversibility, force requirement, and server protection for internal keys, enhancing transparency beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences that front-load the action and resource, every sentence adds value with no waste.
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?
Covers key behavioral aspects (irreversibility, force, protected keys). Lacks return value explanation, but acceptable for a destructive tool without 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 coverage is low (33%), but description adds meaning to 'key' (under site.data) and explains 'force' role and default. Does not detail 'site' parameter, but compensates for incomplete 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?
Clearly states it deletes a key from site.data with specific HTTP method and path. Distinguishes from sibling delete_data tools by specifying 'site.data' and irreversible 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?
Provides explicit usage constraints: requires force=true and refuses internal_* keys. However, it does not discuss when to use this tool over similar delete tools for other resources.
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?
Annotations already declare read-only, non-destructive, idempotent. Description adds key behavioral traits: hourly indexing, public content only, sentinel query for disabled indexing. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is well-structured, front-loads purpose, and each sentence adds value. Slightly verbose but efficient overall.
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 and richness of sibling tools, the description provides complete guidance on usage, limitations, and alternatives. No output schema, but return type is implied by search 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 description coverage is 80%, so schema already explains most parameters. Description adds minor guidance (e.g., use scope to narrow), but does not significantly supplement what is already in 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?
Clearly states the tool performs full-text search across published content, specifying the endpoint and types of content (pages, articles, elements, products). Distinguishes from sibling tools by referencing alternatives for draft/fresh content.
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 advises when to use this tool (published content) and when not (draft/fresh edits), providing specific alternative tools (pages_list, articles_list, text_get). Also explains the scope parameter to narrow search.
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?
Discloses irreversibility (IRREVERSIBLE — Voog does not retain), the need for force=true, and the restriction on deletion when pages are assigned. This goes beyond the destructiveHint annotation by adding specific 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?
Four sentences, each adding essential information. No redundancy, front-loaded with the core purpose. Every sentence 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 parameter set (3 params, no output schema) and annotations (destructiveHint=true), the description fully covers prerequisites, behavior, error conditions, and best practices. A model example.
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 0%, so description must compensate. It explains the force parameter (Refuses without force=true) but does not define site or layout_id. The parameter names are self-explanatory, but the description adds minimal extra 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 starts with 'Delete a layout,' which is a clear verb-resource pair. It distinguishes from sibling layout tools (layout_create, layout_rename, etc.) by specifying the deletion action. No ambiguity.
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 (with force=true if needed), when to avoid (if pages are assigned), and provides alternative actions (reassign pages via page_set_layout) and a precaution (backup with site_snapshot).
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?
The description adds 'Reversible' beyond annotations (idempotentHint, destructiveHint false), providing concrete behavioral context on how to revert.
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, no wasted words. Every sentence adds value.
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 three-parameter tool with no output schema, the description covers purpose and reversibility adequately. No missing information needed for selection or 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?
Schema coverage is 100% with descriptions for all three parameters. The description adds value by specifying that layout_id is used for reverting, going beyond schema basics.
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 'Reassign a page's layout,' using a specific verb and resource. It distinguishes from sibling tools like page_update or page_create, which do not reassign layouts.
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 notes reversibility and how to revert by calling again with the original layout_id. While it does not compare against alternatives, no direct alternatives exist among siblings.
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?
Annotations already set destructiveHint=true; description adds critical detail about irreversibility ('Voog does not retain deleted products') and the defensive force parameter, exceeding annotation info.
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 cover action, warnings, and prerequisites with zero wasted words or redundancy, front-loading the core 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 deletion tool with destructive annotation and no output schema, the description fully covers irreversibility, required force flag, and recommended prior steps, leaving no critical 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 schema documents 3 parameters with only force having a description (33% coverage). The description adds context about confirming product_id but does not elaborate on site or product_id semantics, leaving some gap.
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?
Explicitly states 'Delete a product' with HTTP method and path, clearly distinguishing it from other product tools like product_create, product_update, and product_get.
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 guidance: requires force=true to prevent accidental deletion, and advises confirming the product ID via products_list or product_get and using site_snapshot for backup.
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?
Beyond the annotations (destructive, idempotent), the description discloses a wealth of behavioral details: dry-run by default, force flag required to write, phase dependency order, state_dir safety and refusal rules, and specific Voog platform limitations (created_at/published_at reset, duplicate article path auto-suffix, asset quota checks). This far exceeds the annotation baseline.
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 lengthy but every paragraph serves a distinct purpose: core function, dry-run safety, resumability, phase ordering, exclusions, and platform limits. It is front-loaded with the most critical information (destructive overwrite) and uses capitalized headers for key behaviors, making it scannable for a complex tool.
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 (7 parameters, multi-phase workflow, no output schema), the description is remarkably complete. It tells the agent what the 'plan' phase returns, how quota exhaustion is handled, what will not be cloned, and how to safely resume an interrupted run. No behavioral gaps remain.
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 100% parameter descriptions, but the description adds meaningful context: it marks site as SOURCE read-only and target_site as OVERWRITTEN, explains the dry-run semantics for force, elaborates on state_dir's pair-binding refusal, and clarifies that phases run in fixed dependency order. This adds value beyond the schema rather than merely restating it.
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: 'Copy one Voog site's content onto another' and enumerates the content types (layouts, layout assets, media, site settings, pages, content areas, articles). It clearly distinguishes the source and target roles, and the scope differentiates it from siblings like layouts_pull/push or page_duplicate.
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 operational context: both sites must come from voog_list_sites, it recommends running the 'plan' phase first, and it explains dry-run behavior and resumability. It also lists what is NOT copied, which helps an agent decide whether this tool fits a task. However, it does not explicitly name alternative tools for narrower operations or describe 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.
Behavior4/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 reveals the return shape ([{name, host}, ...]), the config source (voog.json), and hints at a refresh mechanism (voog_reload_config). It does not explicitly state side effects, but for a list operation, read-only behavior is strongly implied, and the additional context is valuable.
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, each serving a distinct purpose: stating the action and result, providing usage priority, and offering a troubleshooting tip. 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?
For a zero-parameter list tool with no output schema, the description fully covers its role: what it returns, when to call it, and how to handle a missing site. This is 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 tool takes zero parameters, so there is no parameter information for the description to add. The schema is empty, and the description appropriately focuses on the output. According to the rubric, baseline for 0 parameters is 4, which is appropriate here.
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 ('sites configured in the global voog.json'), and clearly distinguishes from sibling tools like voog_list_my_sites. It also specifies the return format, 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 states when to use the tool: 'Call this first to see what sites are available before invoking any other voog_* tool.' It also provides an alternative action when a site is missing: 'call voog_reload_config.' This is clear guidance on usage and 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?
Beyond the annotations (idempotent, non-destructive), it discloses that cached clients are dropped, running calls finish against their current client, and a malformed config leaves the current one in place. This enriches the agent's understanding of side effects and failure 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?
Every sentence serves a purpose: action, use case, return value, and edge-case behavior. It is compact, front-loaded, and free of 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 zero parameters, no output schema, and moderate complexity, the description fully covers purpose, usage, return data, and failure behavior. Nothing necessary is missing.
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 description cannot add parameter-specific semantics. The baseline for 0 params is 4, and the description adequately covers the tool's operation without needing parameter details.
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 ('Re-read the global voog.json and drop cached clients') and explains the outcome (newly registered sites become usable without restarting). It also states the return value, clearly distinguishing this from sibling tools like voog_list_sites.
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?
Explicitly gives concrete when-to-use scenarios: when an 'unknown site' error appears or after rotating a token. It adds context about in-flight calls being unaffected, but does not 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.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate idempotent and non-destructive; description adds that renaming is reversible and details title constraints, which helps the agent understand behavior beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with front-loaded purpose. Every word adds value; no 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 rename tool with three well-documented parameters and clear annotations, the description provides sufficient context including reversibility and title constraints. No gaps identified.
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 provides full coverage with descriptions for all three parameters. The description adds additional constraints on new_title (no '/' or '\' or starting with '.'), which enhances 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?
Clearly states the tool renames a layout, provides the HTTP method and path, and specifies constraints on the new title. Distinguishes from sibling tools like layout_create, layout_update, and layout_delete.
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?
Explains the tool is for renaming layouts and is reversible. However, it does not explicitly mention when not to use it or provide alternatives like layout_update for other property changes.
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?
Adds behavioral details beyond annotations: GET-then-PUT-full-array dance, preservation of other assets, rejection of unknown ids, and idempotency. The description aligns with idempotentHint=true and destructiveHint=false without contradiction.
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?
Description is long but each sentence adds necessary context, particularly the safety warning and behavioral guarantees. Structured with a clear WHY section that justifies its length.
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?
Covers all user-relevant aspects: purpose, safety, input constraints, idempotency, and edge cases (empty titles). No output schema exists but description provides enough context for a mutating tool without needing return details.
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?
Adds meaning for `titles` with example mapping, constraint that keys must be existing asset ids, and empty-string clearing semantics. While `site` lacks description, the tool's core parameter is thoroughly explained 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?
States specific verb+resource: 'Safely edit one or more asset titles in a media_set (gallery).' Clearly distinguishes from siblings like media_set_set_assets by explaining it's for title-only edits, and contrasts with dangerous partial PUT.
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 why: 'WHY THIS TOOL' explains that PUT /media_sets/{id} is replace-not-merge and partial edits silently drop assets. It gives the safe scenario and warns about unknown ids, so the agent knows exactly when to use it.
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?
Discloses that body is flat, the mutual exclusivity constraint, and the idempotent nature (matching annotations). No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no wasted words. Key information is front-loaded: action, positioning options, and constraint. Very efficient.
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?
Covers all necessary aspects: action, parameters, constraints, and idempotency. No output schema, but description adequately addresses the tool's behavior.
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?
Adds meaning beyond schema by explaining each positioning option's effect (before, after, parent_node_id) and the mutual exclusivity rule. With 80% schema coverage, this extra context is valuable.
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 it relocates a node to a precise position relative to a sibling or to first slot under a new parent. Includes HTTP endpoint and differentiates from sibling node_move by specifying precise positioning.
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?
Explicitly instructs to supply exactly one positioning parameter and warns that handler rejects multiple. Does not explicitly compare to node_move, but the mutual exclusivity is well communicated.
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?
Beyond annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=false), the description adds significant context: the GET pre-check to avoid duplicates, the default refusal on duplicate names, the force flag to bypass, and the historical issue of silent duplicates. This fully discloses the tool's 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 front-loaded with the core purpose and is reasonably concise. Each sentence adds value, covering defaults, constraints, and alternatives. Minor redundancy could be trimmed, but overall efficient.
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 5-parameter tool with no output schema, the description covers the full operation: endpoint, pre-check, defaults, valid values, force behavior, and alternative tools. It addresses edge cases and provides necessary context for correct 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?
Schema description coverage is only 40% (descriptions for name and force only). The description compensates by explaining default values for name and content_type, valid content_type enum values, and the meaning of force. This adds substantial 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 tool creates a content area and linked text on a page, using the POST endpoint. It distinguishes from siblings like text_update by explicitly noting that editing existing content should use that 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?
The description explicitly recommends using this tool on freshly-created pages and advises using text_update for editing existing areas. It also explains the behavior with duplicate names and the force parameter, providing clear when-to-use and when-not-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?
Annotations indicate mutable, non-destructive, idempotent. Description adds that 'data' field uses PATCH merge semantics, while calls without 'data' use PUT full-replace, and explains how to delete keys via page_delete_data. This goes well beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences: first defines purpose, second states requirements, third suggests alternatives, fourth explains data behavior. Well-structured, front-loaded with essential info, 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?
With 11 parameters and no output schema, the description covers required fields, constraints, alternatives, and data semantics. It could mention validation or side effects for non-data fields, but 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.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% parameter descriptions. Description adds critical meaning for 'data' (merge vs replace) and explains the requirement that at least one optional field must be supplied. For other fields, it just lists them, but the data behavior is well clarified.
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 arbitrary fields on a page' and lists the specific fields (title, slug, layout_id, etc.), distinguishing from siblings like page_set_hidden and page_set_layout which are mentioned as more explicit for specific fields.
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 that at least one optional field must be supplied, and recommends using dedicated tools (page_set_hidden, page_set_layout) for updating only hidden or layout_id, providing 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?
Beyond the annotations (destructiveHint=true, readOnlyHint=false), the description discloses critical behavioral quirks: PUT asset references silently drop images unless using a specific shape, variants array is destructive, and data fields replace the entire hash on PUT. These are significant side-effects the agent would not know otherwise, making the description highly 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 long but well-structured with a clear intro, a dedicated 'for reads' note, and numbered PUT gotchas. Each section earns its place and the front-loading of purpose is effective. The length is justified by the complexity of the passthrough tool, though it is denser than strictly necessary.
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 high-risk nature of a write passthrough with no output schema, the description is remarkably complete. It covers method restrictions, endpoint families, query parameter support, envelope conventions, and specific destructive behaviors, plus alternatives. This is more than enough for an agent to safely select and 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?
The schema covers 100% of parameters, so the baseline is 3. The description adds value by explaining supported query parameters (?include, ?language_code), referencing the body envelope conventions, and detailing method-specific behavior (e.g., PATCH merge semantics). However, it doesn't go into exhaustive detail for every parameter, sticking to the most important gotchas.
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 generic write passthrough for the Voog ecommerce v1 API, with a specific verb (WRITE) and resource (ecommerce API). It distinguishes itself from voog_admin_api_call by the base URL and from voog_ecommerce_api_read by explicitly excluding GET requests, and it enumerates common use cases like orders, carts, and discounts.
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 gives explicit when-to-use guidance: it states that reads should use voog_ecommerce_api_read because this tool no longer accepts GET. It also recommends specific typed alternatives (product_set_images, product_update, page_set_data) for tricky PUT operations, clarifying when the passthrough is not the best choice.
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?
Annotations indicate a non-read-only, idempotent, non-destructive operation. The description adds crucial behavioral information: filename causes a 500 error, data is not byte-exact due to JSON decoding, and raw U+2028/U+2029 or C0 controls are refused. These details go well beyond the annotation hint and are essential for safe use.
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 every sentence provides a necessary caveat or alternative. It leads with the core action, then systematically covers read-only field, encoding behavior, alternative tool, and input validation rules—all without 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's complexity (PUT with JSON boundary issues, read-only fields, external alternatives), the description is remarkably complete. It covers purpose, restrictions, alternative tools, error conditions, and encoding pitfalls. With no output schema, it provides enough context for an agent to 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?
Schema coverage is only 25% (only filename has a description). The description compensates by explaining the semantics of `data` (JSON decoding, not byte-exact) and `filename` (rejected, use asset_replace). `site` and `asset_id` are self-evident from the tool name and context, so the added detail is 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 updates a layout_asset's content, using the specific HTTP PUT method and resource path. It distinguishes from sibling tools by explicitly recommending asset_replace for rename and layouts_push for deploying tracked files.
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 gives explicit when-to-use and when-not-to-use guidance: use asset_replace for rename, use layouts_push for tracked files, and warns against sending filename. This makes the tool's usage boundaries clear relative to 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?
Annotations only provide destructiveHint=true, but the description adds substantial context: the multi-step upload protocol, atomic failure behavior (product not updated if any upload fails), the gallery order race condition, and the specific error payload (order_verified: false). No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Though long, every sentence carries essential operational detail. It front-loads the purpose, then logically sequences the upload protocol, failure modes, and remediation steps. No redundant content.
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 complex mutation with no output schema, the description covers all critical aspects: prerequisites, exact HTTP flow, failure atomicity, gallery order verification, and alternative remediation. It leaves no operational gaps for an agent.
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 covers all 4 parameters at 100%, so baseline is 3. The description adds meaning by explaining files list semantics (first is main image), the force requirement (defensive opt-in like page_delete), and the relationship between site and product_id. This exceeds schema alone.
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 'Replace a product's images', a specific verb+resource statement that clearly identifies the action. It distinguishes itself from siblings like asset_upload and product_update by focusing on image replacement for a product.
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 (replacing existing images), requires force=true as a prerequisite, and provides an exclusion: do NOT re-run to fix gallery order, instead use voog_ecommerce_api_call. This gives clear when/when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark destructiveHint=true, but the description adds significant behavioral context: it states Claude will confirm before calling, explains that PUT /media_sets/{id} is replace-not-merge, and warns that ordered assets arrays may be applied only partially despite a 200 response. These are valuable operational details beyond what annotations convey.
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?
Although long, the description is well-structured and every section earns its place. It front-loads the core purpose, then follows with usage direction, a read exception, and clear warnings about known foot-guns. There is no filler or unnecessary repetition of schema fields.
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 generic passthrough with no output schema, this description provides comprehensive context: URL construction, API token usage, method constraints, typed-tool alternatives, and reliability warnings. It also references additional docs for endpoint-specific envelope conventions, covering the complexity of a broad generic 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 input schema already provides 100% parameter coverage, so the baseline is 3. The description adds meaningful extra semantics by explaining JSON serialization for POST/PUT/PATCH, base host derivation from site config, and endpoint-specific body behavior such as assets arrays being replaced. It does not need to repeat schema details, so this is strong but not maximal.
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 'Generic Admin API WRITE passthrough' and explains it forwards HTTP requests to /admin/api<path> with a specific method set. It also explicitly distinguishes it from voog_admin_api_read by stating 'For READS use voog_admin_api_read', making sibling 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?
The description provides explicit usage guidance: 'Use this when no typed tool covers the endpoint' and lists examples of covered areas. It also gives a clear exclusion: 'For READS use voog_admin_api_read — this tool no longer accepts method='GET'', and points to typed alternatives for risky operations like media_sets PUT.
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?
Annotations indicate read-only, idempotent, non-destructive. Description adds that response is always length-1 array, token security implications, and host validation. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear sections, but the R6 NOTE could be integrated more naturally. Still efficient and front-loaded with purpose and return shape.
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?
Covers purpose, return shape, single-site behavior, token security, host override. Without output schema, description compensates fully. No gaps.
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 description adds critical context: preference for token_env, security warnings for token, host default and override reasons. Enhances 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?
Clearly states the tool probes GET /admin/api/me/sites to discover account metadata for a Voog token. Specifically returns fields and notes single-site limitation, distinguishing from sibling tools like voog_list_sites.
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 (discovering account metadata for a token) and when not (multiple sites require separate tokens). Provides token sourcing recommendations and security warnings.
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?
Discloses duplicate-name refusal, the force parameter as a deliberate override for legitimate repeated areas, and the /contents [] behavior until edit-mode opens. These traits go well beyond the annotations' basic 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?
Three focused paragraphs, each earning its place: main action, parameter semantics, and edge-case behavior. Front-loaded and no 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 create tool without output schema, it covers purpose, parameters, behavioral quirks, and error handling. The duplicate policy and force escape hatch are critical context that is fully explained.
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?
Despite only 40% schema coverage, the description adds deep meaning to name (layout tag matching), content_type (valid values), and force (default false, why you'd flip it). This compensates for the sparse 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?
Clearly states it creates a content area + linked text on a blog article, and explicitly distinguishes from sibling page_add_content. The verb+resource+scope 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?
Provides a specific use case (seeding freshly-created article body/gallery), names the alternative tool page_add_content, and explains when to use force for duplicate names. This is explicit when/alternative 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?
Discloses that title/body/excerpt go to autosaved_* fields (not immediately public), data has merge semantics via PATCH, and calls without data use PUT. This adds context beyond annotations (readOnlyHint, destructiveHint, idempotentHint) without contradiction.
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 well-structured paragraphs with clear grouping of information. First paragraph introduces categories and requirement; second paragraph details data field behavior. No extraneous information; every sentence adds value.
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 complexity (autosaved vs. published, PATCH/PUT duality) and no output schema, the description covers input behavior thoroughly, including edge cases like key deletion via sibling tool. Missing return value details are acceptable for a mutation tool with annotations.
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?
With 0% schema coverage, the description compensates by grouping parameters into autosaved vs. direct-update categories, explaining data's merge behavior, and stating the requirement of at least one field. Provides meaningful semantics beyond the schema structure.
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 'Update an existing article' and distinguishes two categories of fields (autosaved vs. direct) with clear roles, differentiating from sibling tools like article_create, article_publish, and article_delete_data.
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 this tool: for updating article fields, with specific guidance that autosaved fields require article_publish to become public, and that data field uses PATCH semantics while non-data uses PUT. Also directs to article_delete_data for key deletion.
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?
Goes well beyond the annotations by detailing the multi-step POST/PUT/PUT flow, the 120s async polling and 5s interval, the 150/600/1280/2048 derivative caps, the duplicate reuse/suffix orphaning behavior, and the CDN 403 caching pitfall. It also clarifies that sizes_complete=false indicates partial results after timeout. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but every sentence serves a purpose: it covers the multipart workflow, sibling discrimination, output format, derivative sizing rules, duplicate behavior, timeout semantics, and a CDN caching warning. It is structured in focused paragraphs and front-loaded with the core 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 the tool's complexity (upload plus async resize, duplicate handling, partial results, CDN side effects) and the absence of an output schema, the description fully discloses the return value shape (id, dimensions, public path, sizes), the 'sizes_complete' flag, and the consequences of HTTP HEAD checks. It anticipates the likely failure modes and tells the agent exactly how to use and interpret the tool.
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?
Despite 100% schema coverage, the description enriches each parameter: files are 'absolute paths' with supported extensions, allow_duplicate and wait_for_sizes receive behavioral consequences (e.g., 'Pass allow_duplicate=true to force a new asset', 'Pass wait_for_sizes=false to skip the wait'). The duplicate-risk explanation adds meaning beyond the schema's raw 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 opening sentence states 'Upload local image files into the site's media library' and explicitly distinguishes from product_set_images with 'use product_set_images when the images are a product's gallery.' It names the exact resource (media library) and verb (upload), making the tool's scope 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?
The description explicitly says 'Use for images referenced from site.data / page.data maps, article galleries or template markup; use product_set_images when the images are a product's gallery.' It also explains when to set allow_duplicate=true (forced re-upload) and wait_for_sizes=false (skip wait), giving clear decision criteria.
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?
Beyond the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=true), the description discloses critical behaviors: the tool reads back and retries on reorder, explicitly reports if the order did not apply, details the unlink semantics (asset survives in library), and the force=true requirement for drops. This adds substantial context beyond the structured hints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but every sentence earns its place given the tool's complexity. It is well-structured: purpose first, then behavior, force, titles, upload prerequisite, and existence requirement. The density is balanced with clear separations of ideas, avoiding fluff while covering necessary edge cases.
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 complex mutable operation with no output schema, the description fully covers preconditions (media_set existence, how to find it), postcondition behavior (read-back retry, explicit failure reporting), side effects (unlinking, asset survival), and parameter semantics. Together with the annotations and schema, it gives an agent everything needed to invoke the tool correctly.
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?
Despite strong schema coverage (80%), the description adds crucial meaning: it explains that asset_ids order matters and that an explicit 1-based position is sent per asset, not just array order; it details the force parameter's exact conditions ('including a same-length swap'); and it clarifies that titles apply to new assets while existing titles are kept unless overridden — all beyond the schema's own 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 a specific verb and resource: 'Set a media_set's FULL asset list in one call' and immediately clarifies the intended operations (filling, reordering, pruning). It explicitly distinguishes itself from the sibling tool media_set_update_asset_titles, which only edits titles, leaving no ambiguity about 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?
The description provides explicit when-to-use and when-not-to-use guidance: it references the alternative media_set_update_asset_titles for title-only changes, instructs to upload files first with asset_upload, and warns that the media_set must already exist (POST /media_sets returns 500). It also explains how to locate the media_set id via content area's gallery field and media_set_get, giving a complete usage path.
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:

[![voog-mcp MCP server](https://glama.ai/mcp/servers/runnel/voog-mcp/badges/card.svg)](https://glama.ai/mcp/servers/runnel/voog-mcp)

Score Badge

Copy to your README.md:

[![voog-mcp MCP server](https://glama.ai/mcp/servers/runnel/voog-mcp/badges/score.svg)](https://glama.ai/mcp/servers/runnel/voog-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/runnel/voog-mcp'

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