LightCMS

Overview Schema Related Servers Score Discussions

Server Quality Checklist

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

Latest release: v4.2.0
Disambiguation3/5
The tool set covers many distinct operations, but there is notable overlap in search-and-replace tools (search_replace_preview/execute vs. scoped_search_replace_preview/execute) and update tools (update_content vs. update_content_by_path vs. bulk_update_content). While descriptions help differentiate, an agent could misselect due to similar purposes.
Naming Consistency5/5
Tool names follow a consistent snake_case pattern with clear verb_noun conventions (e.g., create_content, list_assets, delete_folder). There are no deviations in style, making the naming highly predictable and readable.
Tool Count2/5
With 72 tools, the count is excessive for a CMS server, making it overwhelming and difficult to navigate. This many tools suggests over-fragmentation of operations, which could hinder agent usability and efficiency.
Completeness5/5
The tool set provides comprehensive coverage for content management, including CRUD operations for all entities (content, templates, assets, forks), bulk operations, versioning, search, and publishing workflows. No obvious gaps are present; it supports full lifecycle management.
Average 3.9/5 across 72 of 72 tools scored. Lowest: 2.3/5.
See the Tool Scores section below for per-tool breakdowns.
- 0 of 1 community issues answered or closed in the last 6 months
- 41 commits in the last 12 weeks
- Last stable release on March 24, 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.
This repository includes a glama.json configuration file.
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 idempotentHint=true and destructiveHint=true, establishing the safety profile. The description adds no information about whether this performs partial updates (implied by schema but not confirmed) or full replacement, what gets returned, or side effects like cache invalidation. It merely states the obvious operation type.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely brief at four words, avoiding verbosity. However, the single sentence fails to earn its place by providing tautological information that matches the title. It is concise but insufficiently informative.
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 destructive mutation tool with no output schema, the description should clarify update semantics (partial vs. full) and expected returns. With five parameters and only one required, the partial update capability is strongly implied but undocumented, leaving agents to infer behavior from schema structure alone.
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 parameters are well-documented in structured fields. The description adds no additional parameter context (e.g., path format expectations, that empty strings might unset fields), but baseline 3 is appropriate given the schema's completeness.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update an existing redirect' is a tautology that restates the tool name with minimal variation. While it adds the word 'existing' to imply the resource must pre-exist, it fails to distinguish from sibling tools like 'create_redirect' or explain what distinguishes an update from a creation operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives (e.g., when to update vs. delete and recreate), nor does it mention prerequisites beyond the implied existence of the redirect. There are no explicit exclusions or conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=true, establishing this is a destructive, repeatable operation. The description adds no additional behavioral context such as whether deletion is permanent, if there are cascading effects on linked content, or recovery options. It does not contradict the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
While extremely brief and front-loaded, the three-word description is so minimal it constitutes under-specification rather than efficient conciseness. It wastes no words, but also provides no informational value beyond the tool name itself.
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 (single ID parameter), strong annotations, and complete schema coverage, the description is minimally sufficient for an agent to identify the tool's scope. However, it fails to enrich the structured data with any additional context about redirects or deletion behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the parameter 'id' is already well-documented in the schema as 'Redirect ID (MongoDB ObjectID),required'. The description adds no parameter-specific guidance, syntax details, or examples, warranting the baseline score for complete schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Delete a redirect' is a tautology that restates the tool name/title with only slight modification (adding an article). While it identifies the resource type (redirect), it fails to distinguish this tool from sibling deletion tools like delete_content or delete_asset beyond what is already implied by the tool name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as update_redirect (for modifying vs. removing) or create_redirect. There are no prerequisites, conditions, or exclusion criteria mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate idempotent and destructive behavior, but the description fails to explain what is destroyed (e.g., are previous settings overwritten irreversibly?) or the scope of the update (partial vs full replacement).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely brief at four words, which prevents redundancy, but front-loads so little information that it borders on under-specification rather than efficient conciseness.
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?
Inadequate for a destructive, idempotent operation with 10 parameters. Lacks explanation of side effects, return values, error conditions, or the relationship between parameters like templates and pagination settings.
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 100% schema description coverage, the schema adequately documents each parameter. The description adds minimal semantic value beyond grouping parameters as 'settings', meeting the baseline expectation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
States the action (update) and resource (collection settings), but is vague about what constitutes 'settings' and does not differentiate from sibling tools like update_content or update_template.
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?
Provides no guidance on when to use this tool versus alternatives (e.g., update_content for items within a collection), nor mentions prerequisites or constraints beyond the ID requirement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
While annotations indicate destructive and idempotent behavior, the description fails to explain what 'destructive' means in this context (e.g., whether it replaces all existing title templates) or clarify that partial updates are supported since both parameters are optional. It mentions placeholder syntax but omits behavioral implications of the operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences total. The first sentence ('Update site configuration') is redundant with the tool title and name. The second sentence contains the specific placeholder information. Reasonably brief but front-loaded with less valuable 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 presence of annotations (destructive/idempotent hints) and complete schema coverage, the description barely suffices for a two-parameter tool. However, it fails to explain the partial update behavior (optional parameters), the specific scope limitation (title templates only), or elaborate on the destructive implications hinted in 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 100%, so the schema already fully documents both parameters including the placeholder syntax. The description generically states that title templates support placeholders, which adds minimal value beyond the schema but does not contradict it. Baseline score appropriate for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
States the tool updates 'site configuration' which is somewhat tautological with the tool name, but adds specificity by mentioning title templates and their placeholders. However, it misleadingly implies broad configuration updates when the schema only contains title template parameters, failing to precisely scope the tool's limited functionality.
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?
Provides no guidance on when to use this tool versus alternatives like get_site_config, nor does it mention prerequisites such as understanding current configuration before updating. No explicit warnings about the destructive nature despite the annotation hint.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
While the destructiveHint annotation confirms this is destructive, the description adds no behavioral context about what happens to content referencing the deleted snippet, whether this is a hard delete or soft delete, or error conditions if the ID is not found.
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 four-word description is efficiently front-loaded with no redundant information. However, extreme brevity for a destructive operation leaves it under-specified for the risk level involved.
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 simple single-parameter input and lack of output schema, the description minimally covers the operation but omits critical context for a destructive tool: cascading effects, restore possibilities, and return status expectations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema coverage describing the MongoDB ObjectID requirement, the description meets the baseline. It mentions 'by ID' which aligns with the schema but adds no additional semantic context about ID format constraints or validation beyond the schema definition.
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 verb (Delete) and resource (snippet), distinguishing it from sibling delete operations on assets, collections, or folders. However, it lacks explicit scoping details that would elevate it to a 5, such as clarifying this is for permanent single-item removal versus archiving.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like bulk_field_operation, nor does it mention prerequisites (e.g., whether the snippet must be unreferenced first) or irreversibility warnings beyond the annotation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true (safe read operation) and openWorldHint=false. The description adds no behavioral context beyond the basic operation, such as error behavior when the ID is not found, what fields are returned, or whether the operation is cached.
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?
Extremely efficient at four words. No wasted language. However, the brevity approaches under-specification given the lack of output schema and error behavior context, preventing a perfect score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Acceptable for a simple retrieval tool with complete schema coverage and safety annotations. However, gaps remain regarding error handling (404 vs null responses) and differentiation from sibling list operations, keeping it at minimum viable rather than exemplary.
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 100% schema coverage, the schema adequately documents the single 'id' parameter as 'Folder ID (MongoDB ObjectID)'. The description references 'ID' but adds no additional semantic value regarding format expectations or validation beyond what the schema provides. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
States specific verb (Get), resource (folder), and identification method (by ID). The 'by ID' phrasing implicitly distinguishes it from sibling list_folders which returns multiples. However, it does not explicitly clarify the single-resource vs collection distinction or mention the MongoDB ObjectID format mentioned in the schema.
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?
Provides no explicit guidance on when to use this tool versus alternatives like list_folders or search_content. While 'by ID' implies use when the identifier is known, it does not state prerequisites (having the ID) or exclusion criteria (don't use for searching/browsing).
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 annotations declare readOnlyHint=true and openWorldHint=false, which cover the safety profile. The description adds no additional behavioral context (e.g., error handling when ID not found, what fields a collection contains, or caching behavior), but it does not contradict the annotations either.
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 extremely brief and front-loaded with the action. While it avoids waste, it borders on under-specification. However, for a simple read operation with comprehensive schema documentation, this length is appropriate and every word serves a purpose.
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 simple single-parameter input, high schema coverage, and presence of read-only annotations, the description meets minimum viability. However, with no output schema provided, the description could improve completeness by briefly characterizing what a 'collection' represents in this domain or what the return structure contains.
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 100% schema coverage, the input schema already fully documents the 'id' parameter as a MongoDB ObjectID. The description mentions 'by ID' which aligns with the parameter name, but adds no semantic information beyond what the schema already provides, warranting the baseline score.
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 uses a specific verb ('Get') and resource ('collection'), and specifies the lookup method ('by ID'). This implicitly distinguishes it from list_collections (which returns multiple), though it could explicitly clarify that this retrieves a single item versus the list alternative.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. Given the presence of list_collections, create_collection, and update_collection siblings, the description should explicitly state when to prefer this single-item retrieval over listing or creation workflows.
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 declare readOnlyHint=true, establishing it as a safe read operation. The description adds the lookup mechanics ('by ID') confirming the schema intent, but provides no additional context on error behaviors (e.g., 404), rate limits, or return structure.
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?
Extremely brief (4 words) but appropriately sized for a single-parameter getter. The sentence is front-loaded and contains no redundant information, though its terseness borders on tautology with the tool 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?
Adequate for a simple read operation with complete schema coverage and safety annotations. However, lacking an output schema, the description omits what fields or structure are returned, which could improve agent debugging.
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 100% schema description coverage, the baseline is 3. The description mentions 'by ID', aligning with the parameter, but adds no syntax details, format examples, or semantic 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.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Get'), resource ('snippet'), and lookup method ('by ID'). The 'by ID' phrasing implicitly distinguishes this from the sibling 'list_snippets' tool, though it does not explicitly name that alternative.
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?
Provides no guidance on when to use this tool versus siblings like 'list_snippets' (for browsing) or 'search_content' (for querying). No prerequisites, error handling, or workflow context is mentioned.
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. The description adds value by specifying the scope ('all assets') and defining asset types, but omits pagination behavior, default limits, or error handling when the folder parameter doesn't exist.
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 efficient sentences with no redundancy. The first establishes the operation; the second clarifies the resource type. Could slightly improve by mentioning the optional folder filter in the main sentence.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for a simple read operation with one optional parameter and strong annotations. Missing description of return value structure or pagination behavior, which would be necessary for complete agent understanding given no output schema exists.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema fully documents the optional folder filter. The description implies filtering is optional by stating 'List all assets,' but adds no semantic details about path formats or wildcard support beyond the schema's example.
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 states a specific verb ('List') and resource ('assets'), and defines what constitutes an asset ('files like images, documents, CSS, JS'), helping distinguish from sibling list_asset_folders. However, it lacks explicit contrast with get_asset (single vs. bulk retrieval).
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 provided on when to use this versus get_asset for retrieving a single asset, or whether pagination applies. No mention of performance considerations for large asset libraries.
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 this is non-destructive (destructiveHint: false) and closed-world (openWorldHint: false). The description adds value by explaining what collections do behaviorally ('display grouped content with custom templates'), but omits other behavioral details like error conditions (e.g., slug uniqueness constraints), authentication requirements, or what the tool returns.
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 efficiently structured with two sentences: the first states the action, the second provides behavioral context. No words are wasted, and the information is front-loaded appropriately.
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 9 parameters and no output schema, the description adequately covers the basic purpose but leaves significant gaps. It lacks information about the created resource's structure, error scenarios (e.g., duplicate slug handling), or how this relates to sibling operations like update_collection or list_collections.
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 100% schema description coverage, the schema carries the full documentation burden for all 9 parameters. The description references 'custom templates' which loosely maps to item_template and page_template parameters, but adds no semantic details beyond the schema such as valid slug formats, category filtering logic, or the relationship between sort_field and sort_order.
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 action ('Create') and resource ('content collection'), and adds distinguishing context that collections 'display grouped content with custom templates.' However, it does not explicitly differentiate from siblings like create_content or create_folder, leaving ambiguity about when to use collections versus individual content items or folders.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives (e.g., create_folder for organization, create_content for individual items) or prerequisites needed before invocation. There are no explicit when/when-not conditions.
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?
Adds valuable context that folders create URL path segments (behavioral effect beyond creation), which complements the non-destructive annotation. However, omits error conditions, return value structure, and side effects like validation rules.
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 zero waste. Front-loaded with the core action, followed by functional context. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for a simple 3-parameter creation tool with complete schema coverage and safety annotations. Covers the 'what' and 'why' (organization/URLs) but lacks guidance on hierarchical usage patterns and return values expected from the server.
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 100% schema description coverage, baseline is 3. The description reinforces the 'slug' parameter's purpose via 'URL path segments' but does not add syntax details, validation rules, or explicit notes about parent_id being optional for root folders.
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?
States specific verb 'Create' and resource 'content folder'. The mention of 'URL path segments' adds distinguishing context from sibling tools like create_collection or create_content, though it lacks explicit contrast with those alternatives.
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 folders vs. collections or content items, nor mention of prerequisites like unique slug requirements or valid parent_id constraints. Purely definitional description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare destructiveHint=false (safe operation). Description adds context about field definition structure but fails to disclose validation behavior (e.g., conflict handling for duplicate slugs), return value structure, or relationship between fields and html_layout placeholders.
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 efficient sentences with no redundancy. Second sentence is dense but information-rich. Could benefit from separating field type enumeration from field structure explanation for clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 100% schema coverage and 6 parameters including complex nested structures, the description adequately covers the fields parameter. Missing: explanation of how html_layout references fields via {{.FieldName}}, success indicators, and error conditions.
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 100% coverage establishing baseline of 3. Description adds significant value by enumerating valid type values (text, textarea, richtext, date, image, select) not constrained in schema, and clarifies the fields array structure implicitly.
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?
States specific verb 'Create' and resource 'template'. Lists specific field types (text, textarea, richtext, date, image, select) which helps distinguish from sibling creation tools like create_content or create_collection. However, lacks explicit differentiation from update_template.
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?
Provides no guidance on when to use this versus update_template, no prerequisites mentioned (e.g., slug uniqueness requirements), and no workflow context. The agent must infer usage solely from the name.
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 declare readOnlyHint=true, so the description doesn't need to state safety. It adds 'with full field data' which provides useful context about the response payload richness, but doesn't describe error behavior (e.g., invalid version numbers) or versioning semantics.
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 zero waste. 'Get', 'specific version', 'content item', and 'full field data' each provide distinct semantic value. Front-loaded with the action verb.
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 2-parameter read operation with complete annotations and full schema coverage, the description covers the essential function. However, it lacks versioning workflow context (how version numbers relate to 'get_content_versions') and error scenarios, which would help an agent use this effectively in a sequence.
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 fully documents both parameters (MongoDB ObjectID and version number). The description implies these concepts but doesn't add syntax details, format constraints, or examples beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb 'Get' and resource 'specific version of a content item'. The phrase 'specific version' effectively distinguishes this from sibling 'get_content_versions' (plural). However, it doesn't clarify the difference versus 'get_content' (current version) or 'revert_to_version'.
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 versus 'get_content' (current state) or 'get_content_versions' (list all versions). No mention that one might need to call 'get_content_versions' first to discover valid version numbers.
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 declare readOnlyHint=true. Description adds 'with full data' indicating complete theme configuration is returned, not just metadata. However, missing disclosure of error behavior (e.g., returns 404 if version not found) or whether archived/unpinned versions are accessible.
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 zero waste. 'specific version' and 'full data' each earn their place by defining scope and completeness. Front-loaded with action and resource.
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 read operation with one required parameter and readOnly annotations. 'Full data' hints at return value structure given no output schema is defined. However, lacks sibling differentiation and error condition documentation that would justify higher score.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with parameter 'version' documented as 'Version number,required'. Description neither adds semantic context (e.g., that version is an integer ID from get_theme_versions) nor repeats schema info. Baseline 3 appropriate when schema carries full descriptive burden.
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?
Uses specific verb 'Get' with resource 'theme settings' and scope 'specific version' and 'full data'. Distinguishes from sibling get_theme_versions (list vs specific instance) and get_theme (current vs historical), though could be more explicit about the version-number lookup pattern.
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 provided on when to use this versus get_theme (current settings) or get_theme_versions (list available versions first). No mention that the version number must be obtained from get_theme_versions or that invalid versions will error.
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, confirming the safe read nature. The description adds minimal behavioral context: 'all available' implies broad scope without filtering, and the definitional sentence clarifies what templates contain (fields/HTML). However, it lacks details on pagination, response format, or empty result 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 concise sentences. The first sentence is front-loaded with the core action. The second sentence provides domain context about template structure, which earns its place by helping distinguish templates from similar resources like snippets or assets, though it shifts slightly from describing the tool to describing the resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (no parameters, read-only) and lack of output schema, the description is minimally adequate. However, it should ideally hint at the return value structure (e.g., 'returns array of template metadata') to compensate for the missing 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?
Input schema contains zero parameters (empty object with additionalProperties:false). Per evaluation guidelines, zero parameters establishes a baseline score of 4, as there are no parameter semantics to elaborate upon.
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 action ('List') and resource ('templates') in the first sentence. The scope 'all available' implicitly distinguishes from sibling 'get_template' (single item retrieval), though it does not explicitly name that alternative.
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?
Provides no guidance on when to use this tool versus alternatives like 'get_template' (for single template details) or 'create_template'. The second sentence defines what templates are conceptually, not when to invoke the listing operation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true (safe operation). The description adds valuable return structure disclosure ('page titles, paths, and snippets') which compensates for the missing output schema, but omits other behavioral details like rate limits, result ordering, or empty-result handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two well-structured sentences with zero redundancy. Front-loaded with the action 'Search published content', followed by mechanism (match modes), then return values. 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?
Given 100% schema coverage and readOnly annotations, the description is appropriately complete. It compensates for the missing output schema by specifying the return payload structure ('titles, paths, and snippets'). Could be improved by noting result limits or pagination behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear descriptions for all three parameters (query, mode, limit). The description reinforces the mode options ('full-text exact match', 'semantic (AI)') but does not add syntax guidance, format requirements, or examples beyond what the schema already provides. Baseline 3 is appropriate for high-coverage schemas.
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?
Clear verb ('Search') and resource ('published content') with specific scope. The phrase 'published content' effectively distinguishes this end-user facing search from administrative alternatives like 'search_content' that might include drafts, though it doesn't explicitly name the sibling alternative.
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 the sibling 'search_content' tool, or when to prefer exact vs semantic vs hybrid modes. The description provides no 'when-not-to-use' constraints or prerequisite conditions.
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 establish readOnlyHint=true, so safety is covered. The description adds value by disclosing the return structure ("list of versions with timestamps"), which compensates partially for the missing output schema. However, it omits behavioral details like ordering, pagination, or whether deleted versions are included.
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 efficient at two sentences: first establishes purpose, second establishes return format. No redundant information or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with one well-documented parameter and safety annotations, the description is appropriately complete. The mention of return structure compensates for the lack of output schema, though ordering or pagination details would improve it further.
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 100% schema description coverage for the single content_id parameter, the schema carries the full burden. The description mentions no parameters, so it neither adds nor subtracts meaning, meeting the baseline of 3.
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 uses specific verbs ("Get") and resources ("version history") and implies bulk retrieval via "list of versions," distinguishing it from sibling get_content_version (singular). However, it does not explicitly clarify when to use this versus the singular version 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 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 get_content (current state) or get_content_version (specific version). No mention of prerequisites or error conditions.
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 read-only/safe behavior via 'readOnlyHint: true'. The description adds content scope ('including title templates') but omits other behavioral details like error conditions, permission requirements, or cache behavior. With annotations covering safety, this is minimally acceptable.
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 efficient sentence front-loaded with the action verb. 'Including title templates' adds specific value without verbosity. Zero waste.
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 parameter-less getter with annotations present, mentioning one key configuration aspect (title templates). However, lacks return value description or enumeration of other configuration fields available given no output schema exists.
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?
Input schema has zero parameters. Per scoring rules, 0 params equals baseline 4.
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?
Clear verb ('Get') and resource ('site configuration') with specific content detail ('title templates'). However, it does not explicitly distinguish from sibling 'update_site_config' (e.g., by stating this is read-only retrieval vs. modification).
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, prerequisites, or conditions. The agent must infer usage solely from the action description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only safety (readOnlyHint: true). Description adds domain context that folders map to URL path segments, which helps understand the data model. However, lacks behavioral details like pagination limits, performance characteristics, or cache 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?
Two concise sentences with zero waste. First declares action, second provides domain context. Appropriately front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Simple tool with no input parameters and safety annotations provided. Description adequately covers the 'what' but lacks return value specification (no output schema exists). Does not mention if results are paginated or ordered.
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?
Zero parameters present, which per scoring rules establishes a baseline of 4. No parameter documentation required.
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?
Clear verb 'List' and resource 'content folders'. Explicitly specifies 'content' which distinguishes from sibling tool 'list_asset_folders'. Second sentence explains domain purpose (URL path segments).
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 versus 'get_folder' (which retrieves a specific folder) or versus 'list_asset_folders'. No mention of pagination, filtering, 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 declare read-only safety (readOnlyHint=true) and closed-world scope (openWorldHint=false). Description adds 'unique' constraint (valuable behavioral detail) and 'asset library' scope, but omits output format, pagination behavior, or empty-result handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with zero waste. Front-loaded action verb, no filler words. Efficiently conveys scope, uniqueness constraint, and domain.
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?
Appropriately complete for a zero-parameter read operation. Describes return concept (folder paths) sufficiently despite missing output schema. No prerequisites or complex behaviors to document.
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?
Zero parameters present; baseline score 4 applies per rubric. Schema is empty object with 100% coverage. No parameter compensation needed.
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?
Clear verb (List), resource (folder paths), and scope (asset library, unique). Distinguishes from 'list_assets' by specifying 'folder paths' and from 'list_folders' by specifying 'asset library', though lacks explicit sibling differentiation guidance.
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 when-to-use or when-not-to-use guidance provided. Does not clarify relationship to sibling 'list_folders' or 'list_assets', leaving ambiguity about which listing tool is appropriate for which use case.
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 declare readOnlyHint=true and openWorldHint=false. Description adds 'for the site' which reinforces the closed-world scope, but does not disclose pagination limits, default sorting, or the structure of returned redirect objects.
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 front-loaded sentence with zero redundancy. Every word conveys essential scope (all, configured, site) and action.
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?
Appropriately complete for a zero-parameter read-only tool. Description sufficiently covers the operation's intent, though it lacks details about the return structure (absent output schema) which would be necessary for optimal 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?
Tool accepts zero parameters. With no parameters to document, this meets the baseline expectation for the dimension.
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?
Clear verb (List) and resource (URL redirects) with scope ('all', 'configured for the site'). Distinguishes from sibling create/delete_redirect operations by being a bulk listing operation, though it doesn't explicitly differentiate from other list_* 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 versus alternatives (e.g., when to list vs. create/update redirects) or prerequisites. Does not mention pagination behavior for sites with large numbers of redirects.
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?
Excellent clarification of behavioral nuance: despite 'destructiveHint' annotation signaling state mutation, description explains it 'creates a new version with the old data' rather than destructive overwrite. This preserves history and mitigates data loss fears, adding crucial 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?
Extremely concise with two information-dense sentences. Front-loaded action ('Revert content...') with mechanism explanation following. Zero redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers the essential 'copy-on-write' behavioral quirk adequately for a destructive operation, but lacks coverage of error cases, return value shape, or prerequisites given no output schema exists. Acceptable but 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?
With 100% schema description coverage, parameters are already well-documented. Description implies 'content' maps to content_id and 'previous version' to version, but adds no syntax details, format specifics, or examples beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
States specific verb (revert) and resource (content/version) clearly. Distinguishes from sibling 'revert_theme_to_version' by specifying 'content', but does not explicitly differentiate from 'restore_content' (restore from trash vs. version revert).
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?
Provides no guidance on when to use this tool versus alternatives (e.g., 'get_content_versions' to identify target version first) or prerequisites. No mention of error conditions (e.g., invalid version number).
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 declare destructiveHint=false and openWorldHint=false, covering safety profile. The description adds context about redirect permanence (301 vs 302 behavior), but omits details on propagation delay, validation rules, or conflicts with existing paths.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero waste. First states purpose; second provides specific HTTP status guidance. Efficiently structured without extraneous 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?
Adequate for a 4-parameter creation tool with complete schema annotations. Given the lack of output schema and simple flat structure, the description covers the essential behavioral context (permanent vs temporary) to supplement the structured data.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with complete descriptions for all four parameters. The description text reinforces the status_code semantics but adds no new information beyond what the schema already provides. Baseline 3 is appropriate for high-coverage schemas.
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?
Clear verb (Create) + resource (URL redirect). The mention of 301/302 status codes distinguishes this from generic content creation tools like create_content or create_folder. However, it does not explicitly differentiate from sibling update_redirect regarding when to create new vs update existing.
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?
Provides specific guidance on status_code values ('Use 301 for permanent...'), which helps parameter selection. However, lacks guidance on when to use this tool versus alternatives (e.g., update_redirect for modifying existing redirects) 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 indicate read-only safety (readOnlyHint=true). The description adds semantic context that collections organize content by 'category'. Does not disclose pagination behavior, empty state handling, or auth requirements, but meets the lower bar set by existing 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 zero waste. Front-loaded with the action (List all content collections), followed by brief domain context. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for a zero-parameter read operation with readOnly annotations, but gaps remain: no output schema exists, so description should ideally characterize the returned collection list structure or typical response shape.
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?
Zero parameters present per input schema. As per guidelines, 0 parameters earns baseline score of 4. No parameter documentation burden exists.
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?
States the specific action (List) and resource (all content collections) clearly. Distinguishes from 'get_collection' (singular) by using 'List all' versus 'get', though it could explicitly contrast with the singular fetch sibling.
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?
Provides domain context explaining what collections are ('group and display content by category'), which implies usage. However, lacks explicit when-to-use guidance versus alternatives like 'get_collection' or when pagination might be relevant.
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 establish read-only safety (readOnlyHint: true). The description adds valuable behavioral context by specifying return structure ('paths and match context'), compensating for the missing output schema. It does not mention the soft-deletion behavior (include_deleted), though that is covered in the parameter schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two efficient sentences. First establishes scope (what it searches), second establishes return value (what you get). No redundancy or filler. Front-loaded with core action.
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 100% schema coverage and simple 3-parameter structure, the description is appropriately complete. It compensates well for the missing output schema by describing the return format (paths, match context). Could benefit from pagination or result limit notes, but not required given schema simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the schema fully documents parameters (query, search_type, include_deleted). The description echoes the 'title or full text' distinction but does not add query syntax details (e.g., wildcards) or semantic implications beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb ('Search') and resource ('content items') with specific scope ('title or full text'). However, it does not explicitly differentiate from siblings like 'end_user_search' or 'list_content'.
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 'end_user_search' (which may have different permission scopes) or 'list_content' (which retrieves unfiltered lists). No mention of prerequisites or when to avoid.
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 non-destructive mutation (destructiveHint:false) and stable IDs (openWorldHint:false). The description adds context that this operates on 'existing' resources and identifies which fields are mutable, but doesn't disclose behavioral specifics like error handling for missing IDs or whether unchanged fields must be resubmitted.
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?
高效单句结构（9个词），动作前置。'and/or'略显冗余且与schema中所有字段均为required存在轻微冲突，但整体上零废话。
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?
对于带有完整schema描述的简单三参数更新工具而言基本够用，但缺少关于部分更新行为的重要细节（鉴于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 has 100% description coverage, establishing baseline 3. The description reinforces semantic relationships by grouping 'name' and 'html' as the updatable fields versus 'id' as the identifier, but doesn't resolve the tension between 'and/or' phrasing and the schema's required field 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?
Specific verb ('Update'), specific resource ('snippet'), and clear field scope ('name and/or HTML template'). The phrase 'existing snippet' clearly distinguishes this from sibling create_snippet.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'existing snippet' implicitly signals this is for modifications, not creation. However, it lacks explicit when-to-use guidance (e.g., 'use create_snippet for new snippets') and doesn't clarify that all fields must be provided even for partial updates despite the 'and/or' phrasing.
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?
While annotations declare destructiveHint=true, the description adds valuable scope context: 'Removes both the file and database record' clarifies this affects both filesystem and database layers. Does not mention idempotency behavior (covered by annotation) or error conditions (e.g., non-existent ID), but adds concrete destruction scope.
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?
Optimal two-sentence structure. First sentence delivers core action immediately. Second sentence adds necessary scope clarification without redundancy. Zero padding or generic filler. Front-loaded with critical 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 single-parameter delete operation: annotations cover safety profile (destructive, idempotent), description covers deletion scope. However, lacks mention of error behaviors (404 if ID missing?), return values, or prerequisites (permissions, asset state constraints).
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 the ID parameter fully documented as 'Asset ID (MongoDB ObjectID)'. Description provides no additional parameter semantics, but with complete schema coverage, the baseline score of 3 is appropriate—no compensation needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Excellent specificity: verb 'Delete' + resource 'asset' + location 'library'. Second sentence clarifies scope (file + database record), distinguishing from logical deletes or metadata-only removals. Clear differentiation from siblings like delete_content, delete_folder, etc. by specifying 'asset'.
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 versus alternatives (e.g., no mention of archive_asset if it existed, or bulk operations), no prerequisites stated (e.g., checking if asset is in use), and no 'when-not-to-use' guidance. Only implicit use case from the verb itself.
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 context: the deletion is container-only and preserves content. This prevents the safety assumption that 'destructive' applies to nested content. 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 zero waste. First establishes the action, second clarifies scope/safety. Perfectly front-loaded and appropriate length for the tool 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?
Sufficient for a single-parameter destructive operation. Critical safety information (content preservation) is covered. Could optionally clarify what happens to orphaned content, but adequate given annotations cover idempotency and destructiveness.
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 has 100% description coverage ('Collection ID (MongoDB ObjectID),required'), so baseline applies. Description adds no parameter-specific semantics, but the schema handles this adequately.
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?
Clear verb (Delete) and resource (collection). The second sentence ('This does not delete the content...') begins to distinguish from siblings by clarifying scope, though it could more explicitly differentiate from delete_content or delete_folder.
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?
Provides implicit guidance through the negative constraint about content preservation, helping prevent misuse. However, lacks explicit 'when to use' guidance or comparison to alternatives like archive_fork or bulk operations.
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 cover safety profile (destructive, idempotent). Description adds valuable implementation detail ('Generates the static HTML page') and user-facing effect ('visible on the public site') that help the agent understand the scope of the operation beyond the 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?
Two efficient sentences with no waste. Front-loaded with action and primary effect, followed by technical implementation detail. Every word serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Complete for a single-parameter mutation tool with good annotations. Explains the observable effects (visibility, HTML generation) sufficiently despite lacking output schema. Could improve by mentioning idempotency behavior or error 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?
Schema coverage is 100% with clear parameter description ('Content ID (MongoDB ObjectID)'). The description mentions 'content item' but doesn't add parameter-specific semantics beyond the schema, which is appropriate given the high schema coverage.
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?
Clear verb ('Publish') and resource ('content item') with specific effects ('making it visible on the public site'). Loses one point for not explicitly differentiating from sibling 'publish_multiple' (single vs batch) or 'unpublish_content'.
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?
Describes the outcome (visibility, HTML generation) but lacks explicit guidance on when to use vs alternatives like 'preview_content' or 'publish_multiple', and doesn't mention prerequisites (content must exist first).
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 explains that 'unpin' means removing a lock, which adds conceptual context beyond the annotations. However, it fails to disclose what state the theme enters after unpinning (does it track latest? stay fixed?) or mention the idempotent nature explicitly, though annotations cover safety profiles (destructiveHint=false, idempotentHint=true). No contradictions found.
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 efficient: one descriptive sentence followed by a concrete example. Every element earns its place, with the action front-loaded and zero redundant 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?
For a single-parameter state-change operation with good annotations covering safety/idempotency, the description adequately covers the core operation. It lacks explanation of the post-unpin behavior (which would help agents predict system state), but given the simplicity and lack of output schema, this is reasonable.
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 100% schema description coverage, the baseline is 3. The description adds an example JSON structure ('Example: {"version": 5}'), which helps clarify the expected format, but doesn't add semantic meaning beyond the schema's 'Theme version number to pin/unpin' 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 uses a specific verb ('Remove the lock') with a specific resource ('previously pinned theme version'), clearly distinguishing this from sibling tools like pin_theme_version (inverse operation) and revert_theme_to_version (which changes active version rather than just removing a lock).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'previously pinned' implies a precondition that the version must be locked, but there's no explicit guidance on when to use this vs. pin_theme_version, nor any mention of prerequisites like checking current pin status or what happens after unpinning (e.g., auto-updates resuming).
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, confirming safe read operation. Description adds valuable output context not present in annotations: specifically that it returns a 'list of versions with timestamps', which helps the agent understand the data structure returned despite the lack of output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with zero waste. Front-loaded with the action verb, followed immediately by return value description. 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?
Appropriately complete for a zero-parameter read-only tool. Compensates for missing output schema by describing the return structure (list with timestamps). Could mention that theme ID is inferred from context or required in environment, but sufficient as-is.
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?
Zero parameters present, meeting the baseline score of 4. No parameters require semantic explanation.
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?
States specific action (Get) and resource (version history for theme settings). Implies distinction from sibling 'get_theme_version' (singular) through use of 'history' and 'list', but does not explicitly clarify when to use the plural vs singular variant.
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?
Provides implied usage through the term 'history' suggesting archival/audit use cases, but lacks explicit when-to-use guidance or prerequisites (e.g., no mention that this is for retrieving version IDs needed by 'revert_theme_to_version').
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 declare idempotentHint=true and destructiveHint=false, establishing safety profile. Description adds operational context (triggers: initial setup, staleness) but omits details about execution duration, performance impact, or whether it blocks other operations. Appropriate given annotation coverage.
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 zero redundancy: first defines operation, second specifies usage triggers. Front-loaded with concrete action verb and no filler 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?
Appropriately complete for a parameterless maintenance operation with good safety annotations. Describes scope (all published content) and timing, though could briefly mention relationship to search functionality or execution mode (async vs sync).
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?
Zero parameters present, meeting baseline for this score per evaluation rules. Schema requires no additional semantic elaboration.
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?
Clear verb 'Regenerate' and specific resource 'vector embeddings' scoped to 'all published content'. Effectively distinguishes from sibling 'regenerate_all_content' by specifying the target resource (embeddings vs content), though explicit contrast with that sibling is absent.
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 states trigger conditions ('after initial setup or if embeddings become stale'), providing clear when-to-use guidance. Lacks explicit when-not-to-use warnings or named alternatives, but the conditional requirement signals appropriate 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?
Adds significant value beyond annotations: clarifies 'soft-delete' semantics (recoverable destruction), states the specific side effect of 'Removes the static HTML page,' and confirms idempotency through the restoration capability. No contradictions with destructiveHint=true or idempotentHint=true.
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, all essential: defines operation, states recoverability (critical for soft-delete), and specifies side effect. No redundant or wasted words. Information is front-loaded with the core action.
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?
Comprehensive for a deletion tool: covers soft-delete semantics, recovery path, and specific side effects (HTML removal). Annotations provide safety hints (destructive, idempotent). No output schema present but unnecessary for this operation type given idempotency disclosure.
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 100% schema description coverage for the single 'id' parameter, the schema fully carries the parameter semantics load. Description adds no parameter-specific details, which is appropriate given the high schema coverage baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States specific action 'Soft-delete' targeting a 'content item' and distinguishes from hard-delete siblings by noting it 'can be restored later.' Also differentiates from other delete_* tools (delete_asset, delete_folder, etc.) by specifying the content resource type.
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?
Implies reversibility ('can be restored later') which hints at the restore_content sibling tool, but lacks explicit when-to-use guidance or comparisons against alternatives like archive_fork. Provides minimum viable context for agent 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?
Annotations declare destructiveHint=true and idempotentHint=true. The description adds crucial behavioral context: the empty-folder constraint (precondition) and implied failure mode for non-empty targets, which annotations do not cover.
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 zero waste: first states the operation, second states the critical constraint. Front-loaded and appropriately sized 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?
Adequate for a simple single-param destructive tool. Annotations cover safety/destructive traits; description covers the primary business logic constraint (empty-only). No output schema exists to document.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 100% description coverage for the single 'id' parameter. The description does not reference parameters, but the schema is self-documenting, meeting the baseline score for high-coverage schemas.
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?
Specific verb (Delete) + resource (folder) with clear scope constraint (empty only). The empty-folder restriction distinguishes it from broader delete operations like delete_content or delete_collection, though it doesn't explicitly name sibling alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit 'when' (empty folder) and 'when-not' (contains content/subfolders) guidance. Missing specific alternative tool recommendations for handling non-empty folders, but the constraint is clearly actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations cover destructiveness and idempotency. The description adds valuable behavioral context: validation rules preventing deletion of system templates and templates with dependencies. This explains failure modes not captured in 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, zero waste. Front-loaded with the action ('Delete a template'), followed immediately by critical constraints. 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?
Appropriate for a single-parameter deletion tool. Captures the essential constraint logic (system/dependency blocks). Lacks mention of return values, but destructiveness and idempotency hints reduce ambiguity for a delete operation without 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 has 100% coverage with clear ID description ('Template ID (MongoDB ObjectID)'). The description references 'a template' implying identification is needed but does not augment the parameter documentation beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb ('Delete') and resource ('template'). The scope is implicit given the tool name and sibling tools (delete_content, delete_folder, etc.), though it could explicitly specify 'content template' to distinguish from potential email/code templates.
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?
Strong explicit constraints: 'Cannot delete system templates or templates that have content using them.' This clearly identifies when the operation will fail. Lacks explicit alternatives (e.g., 'use archive instead'), but the constraints provide critical usage guardrails.
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 valuable return payload context ('full template including fields and HTML layout') beyond the readOnlyHint annotation. Confirms this retrieves complete object data, not just metadata. 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, zero waste. First sentence defines operation and lookup keys; second sentence describes return payload. Front-loaded with essential information, no redundancy with title or schema.
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?
Appropriate for a simple 2-parameter retrieval tool. Compensates for missing output schema by describing return structure ('fields and HTML layout'). With readOnlyHint annotation present, no need for safety warnings.
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 100% schema coverage, baseline is 3. Description mentions 'ID or slug' which implies alternative identifiers, but doesn't add syntax details, format constraints, or explicit mutual exclusivity guidance beyond what the schema property descriptions already 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?
Clear specific verb ('Get') + resource ('template') + scope ('single' vs sibling 'list_templates'). The ID/slug specification distinguishes from bulk operations and the 'fields and HTML layout' distinguishes from metadata-only retrieval tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies usage by mentioning 'by ID or slug' but lacks explicit guidance on when to use this vs 'list_templates' (browse/search vs direct lookup) and doesn't clarify that ID and slug are mutually exclusive lookup methods (both marked optional in 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 establish readOnlyHint=true; description adds valuable behavioral context by disclosing exactly which theme components are returned (colors, fonts, header/footer HTML), which helps the agent understand the scope and shape of the data without contradicting safety 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?
Single efficient sentence front-loaded with the action verb. Every clause earns its place: the main clause establishes the operation, while the prepositional phrase specifies the thematic domains returned. No redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While lacking an output schema, the description compensates by enumerating the primary return value categories (colors, fonts, HTML). Adequate for a simple read operation, though explicit mention of whether this returns the active/live theme versus pinned version would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Zero parameters (input schema is empty object), which per guidelines warrants a baseline score of 4. The description appropriately implies no filtering or input is required to retrieve the current theme settings.
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?
Excellent specificity with verb 'Get', resource 'theme settings', and concrete examples of returned data (colors, fonts, custom HTML). The term 'current' implicitly distinguishes this from sibling version-management tools like get_theme_version and update_theme.
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?
Provides no explicit guidance on when to use this versus get_theme_version/get_theme_versions or whether this retrieves the active/pinned version. No prerequisites or exclusions mentioned.
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 valuable side-effect disclosure ('Regenerates static page if content was published') beyond what annotations provide (idempotentHint, destructiveHint). However, misses error behavior (what if ID not found/not deleted) and authorization requirements.
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 zero waste. Main action front-loaded in first sentence; second sentence adds distinct value by describing side effects. Structure is optimal for quick agent comprehension.
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 single-parameter state-change operation. Combines clear annotations with description covering the restoration scope and side effects. Lacks error case documentation but acceptable given tool simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with complete parameter documentation ('Content ID (MongoDB ObjectID), required'). Description provides no additional parameter semantics, but baseline 3 is appropriate given schema already documents everything.
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 action ('Restore') and resource ('soft-deleted content item'), distinguishing it from sibling create_content. The 'soft-deleted' qualifier clearly scopes the operation to recovery of trashed items versus creating new content.
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 term 'soft-deleted' implies prerequisite state, but lacks explicit guidance on when to use versus alternatives (e.g., create_content) or when not to use (e.g., hard-deleted items). No sibling comparisons or workflow guidance 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 indicate destructiveHint=true, but the description adds crucial behavioral context: 'Creates a new version with the old data.' This disclosure that reverting creates a new version entry (rather than destructive rollback) is valuable transparency 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 with zero waste. First sentence establishes operation and resource; second sentence provides essential behavioral information about version creation. Every word earns its place with 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?
For a destructive 2-parameter tool with complete schema documentation, the description appropriately explains what the operation does and its non-destructive version creation behavior. No output schema exists, but the description sufficiently covers the operation's intent and side effects.
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 100% schema description coverage, the schema adequately documents both parameters (version number and optional comment). The description implies the version parameter but does not add semantic details, syntax constraints, or examples beyond what the schema provides. Baseline 3 is appropriate given comprehensive schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verb 'Revert' with resource 'theme' and scope 'to a previous version'. The second sentence 'Creates a new version with the old data' clarifies the semantic behavior. It distinguishes from sibling 'revert_to_version' by explicitly mentioning 'theme' in the description.
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 through resource naming (theme vs content), but provides no explicit when-to-use guidance or comparison to siblings like 'revert_to_version' or 'restore_content'. The agent must infer applicability from the tool name and description alone.
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?
Aligns with destructiveHint=true by describing removal actions. Adds valuable specific context beyond annotations by specifying 'Removes the static HTML page' as the mechanism, clarifying the scope of destruction without contradicting idempotentHint=true.
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 zero waste. Front-loaded with primary action and effect ('Unpublish... removing it from the public site'), followed by technical implementation detail ('Removes the static HTML page'). Optimal length 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?
Sufficient for a single-parameter destructive operation with good annotations. Describes the external effect (removal from public site) and mechanism (static HTML). Could be elevated by describing the resulting content state (draft/archived) or return confirmation, but adequate given schema simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with the 'id' parameter fully documented in the schema ('Content ID (MongoDB ObjectID)'). Description mentions no parameters, but baseline 3 is appropriate given complete schema coverage requiring no additional semantic explanation.
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 action 'Unpublish' on resource 'content item', clearly distinguishing from sibling 'delete_content' by specifying removal occurs only from 'the public site' while implying the item persists internally. Also adds technical specificity with 'static HTML page'.
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?
Implies usage context ('public site') but lacks explicit guidance on when to use versus 'delete_content' or other alternatives. No mention of prerequisites or state transitions (e.g., does it become a draft?).
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 but don't specify what is destroyed. The description adds crucial context that changing HTML layout regenerates all content using the template, explaining the scope and trigger of the destructive operation 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 with zero waste: first states purpose immediately, second delivers critical side-effect warning. Every word earns its place; appropriately front-loaded with no redundant or verbose language.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 7-parameter mutation tool with no output schema, the description adequately covers the core operation and major side effect (regeneration). Given annotations cover safety hints and schema covers all parameters, this is complete enough, though could mention ID retrieval pattern.
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 mentions HTML layout changes causing regeneration, but this information is already present in the html_layout parameter's description within the schema. No additional semantic details provided for other parameters like id, name, or fields.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states specific verb (Update) and resource (template), distinguishing from siblings like create_template or delete_template. The second sentence adds critical scope detail about regeneration behavior.
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?
Provides an important side-effect warning (HTML layout changes regenerate content) which implies when to be careful, but lacks explicit when-to-use guidance versus alternatives like create_template or prerequisites such as needing the template ID.
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. Description adds critical behavioral context: the fork and pages are 'preserved' (explaining destructive=false), becomes 'read-only' (state change), and 'Requires admin role' (authorization barrier not in annotations). Adds significant value beyond 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?
Three tightly constructed sentences: 1) Action + sibling distinction, 2) Preservation semantics + state change, 3) Authorization requirement. Zero redundancy; every word earns its place. Excellent information density.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter state-change tool with no output schema, the description adequately covers the operation outcome (read-only preservation), authorization boundary, and sibling distinction. Completeness is appropriate for the tool's complexity; 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?
Schema has 100% description coverage ('Fork workspace ID to archive,required'), so baseline is 3. Description does not add parameter semantics, constraints, or examples beyond what the schema provides, but none is needed given complete 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?
Description uses specific verb 'Archive' with resource 'fork', states the exact outcome (becomes read-only), and explicitly distinguishes from sibling merge_fork with 'without merging it'. Also distinguishes from delete_fork by stating data is preserved.
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 references the alternative action (merging) via 'without merging it', establishing the choice point. States prerequisite 'Requires admin role'. Could be improved by explicitly stating when to choose archive vs delete, but clearly signals this is a preservation alternative to merging.
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 non-destructive and closed-world. Description adds crucial behavioral context: snippets are Go templates (implementation), render single content items (scope), and integrate specifically into lc:query directives (system integration point). Does not mention idempotency or duplicate name handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences with zero waste: defines action, explains domain concept (Go template + lc:query), and provides usage example. Front-loaded with essential information. Appropriate length for 2-parameter tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Complete for a simple creation tool with good annotations. Explains the templating domain, available integration points, and reference syntax. Lacks explicit error behavior documentation (e.g., name collision handling), but otherwise covers the 2-parameter surface adequately.
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 complete descriptions for both 'name' and 'html' parameters. Description mentions 'Go templates' which reinforces the html parameter type, but does not add semantic detail beyond what the schema already provides. Baseline 3 appropriate 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?
Clear specific verb ('Create') + resource ('snippet'). Distinguishes from siblings (create_template, create_content) by defining snippets as 'Go templates that render one content item in an lc:query index page' and showing the HTML comment reference syntax.
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 context via the lc:query HTML comment example showing how to reference the snippet by name after creation. Explains the specific domain (lc:query index pages). Lacks explicit contrast with create_template, but implied by the specialized definition.
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 the destructiveHint annotation, description adds critical context: cascade scope ('all its pages'), business logic constraint ('Cannot delete a merged fork'), and authorization requirement ('Requires admin role'). These are substantial behavioral additions.
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, zero waste. Front-loaded with the action ('Permanently delete'), followed by constraints and requirements. Each sentence conveys distinct essential 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?
Comprehensive for a single-parameter destructive operation. Covers action, scope, constraints, and permissions. No output schema exists, so return value explanation isn't expected. Could optionally mention if operation is synchronous or idempotent.
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 the fork_id parameter fully documented in the schema. Description doesn't add syntax, format, or examples beyond the schema, which is acceptable given the high coverage baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb 'delete' with resource 'fork' and scope 'all its pages'. Explicitly distinguishes from sibling archive_fork by emphasizing permanence, and from merge_fork via the 'merged fork' constraint. Absolutely clear what the tool does.
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 clear exclusion criteria ('Cannot delete a merged fork') and prerequisite ('Requires admin role'). Tells the agent when NOT to use it, though could explicitly name archive_fork as the alternative for non-destructive removal.
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 valuable indexing mechanics beyond annotations: explains links are 'tracked automatically whenever a page is published' (data freshness constraint) and specifies both [[Wikilinks]] and ordinary <a href> links are indexed (scope completeness). No contradiction with readOnlyHint:true.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight paragraphs: mechanism (link tracking types), use cases (three scenarios), example (JSON). Front-loaded with core action. Every sentence delivers unique information; zero redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, but description compensates by stating tool 'returns every published page whose content contains a link to /about', clarifying return type (pages) and scope. Lacks detail on pagination or field selection, but adequate for simple read-only tool with good 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 has 100% description coverage ('URL path to find backlinks for (e.g. /about)'), so baseline applies. Description provides JSON example {'path': '/about'} but primarily illustrates return behavior rather than adding parameter constraints, formats, or validation rules 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?
Opens with specific verb 'Find' + resource 'published pages' + relationship 'that link to given URL path'. Clearly distinguishes from sibling get_content (returns page content) and search_content (full-text search) by focusing specifically on backlink relationships.
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?
Lists three concrete use cases: 'discover which pages reference a given page (wiki-style backlink graph)', 'assess the impact of deleting or renaming a page', and 'find orphaned pages'. Provides clear when-to-use context, though lacks explicit 'when not to use' or named 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 declare readOnlyHint=true, confirming this is a safe read operation. The description adds valuable return structure documentation: 'fork metadata + array of pages (id, title, full_path, updated_at)' that is not present in structured fields. This discloses exactly what data structure the agent will receive.
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 well-structured sentences with zero waste: (1) core purpose, (2) return specification, (3) usage guidance. Front-loaded with the action, includes line breaks for readability, and every sentence earns its place by conveying distinct information not found in other fields.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite lacking a formal output schema, the description comprehensively documents the return format and fields. It contextualizes the tool within the broader workflow (referencing get_content/update_content). Minor gap: no mention of error cases (e.g., archived forks) or pagination behavior for forks with many pages.
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 the 'id' parameter fully documented as 'Fork ID (returned by create_fork or list_forks),required'. Since the schema carries the full semantic load, the baseline score of 3 applies. The description text does not add additional parameter constraints, examples, or format details 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?
Description uses specific verb 'Get' with clear resource 'fork workspace' and scope 'including its status and list of pages'. The singular 'a fork' combined with the ID parameter clearly distinguishes this from list_forks (which returns multiple forks) and from sibling mutation tools like create_fork or merge_fork.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit workflow guidance: 'Use the page id with get_content or update_content to read/edit fork pages.' This helps the agent understand how to use the output and references specific sibling tools. However, it lacks explicit guidance on when to use get_fork vs list_forks (e.g., 'use this when you have a specific Fork ID').
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 (safe read), but description adds valuable domain context: snippets contain 'Go-template HTML' and are used in 'lc:query index page directives' - behavioral traits not inferable from structured fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with zero waste: first states purpose, second defines domain concept. Appropriately front-loaded and sized.
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?
Complete for a zero-parameter read operation given annotations cover safety profile. Could improve by noting pagination behavior or output structure (absent output schema), but adequately covers domain context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Zero parameters per input schema, triggering baseline score of 4 as per rubric. No parameter documentation burden exists.
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 'List' and resource 'snippets', with 'all' implicitly distinguishing from sibling get_snippet. Second sentence defines snippets as 'reusable Go-template HTML fragments', clearly differentiating from templates/assets siblings.
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 'all' qualifier implies bulk retrieval versus single-item siblings like get_snippet, but lacks explicit when-to-use guidance or named alternatives.
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 cover safety properties (idempotentHint, destructiveHint). The description adds valuable behavioral context by specifying the operation rebuilds 'static HTML pages' and implies it is triggered by structural changes (themes/templates). However, it omits operational details like whether this runs asynchronously, potential site performance impact during regeneration, or whether unpublished/draft content is affected.
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 redundancy. The first sentence states the action and scope; the second provides usage context. Every word earns its place with no filler or repetition of the tool name.
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 zero parameters and no output schema, the description adequately covers the tool's purpose and trigger conditions. It leverages the provided annotations for safety hints. A minor gap exists in not clarifying whether this affects the entire site or specific scopes, though 'all' suggests global scope.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With zero parameters, the baseline score applies. The description requires no parameter clarification, and the schema is trivially complete at 100% 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 provides a specific verb ('regenerate'), a clear resource ('published static HTML pages'), and scope ('all'). The phrase 'static HTML pages' distinguishes this from dynamic content updates and siblings like update_content or publish_content that handle CMS records rather than cached HTML 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?
The description explicitly states when to use the tool ('after major theme or template changes'), providing clear contextual guidance for the agent. However, it lacks explicit guidance on when not to use it (e.g., 'do not use for single page updates') or named alternatives from the sibling 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?
Annotations declare destructiveHint=true and idempotentHint=true. The description adds critical behavioral context beyond annotations: 'discards the fork copy' clarifies what gets destroyed, while 'does not affect the live page' provides essential safety information that prevents accidental misuse. 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?
Single sentence with parenthetical delivers complete information without waste. Every component earns its place: action verb, target resource, destruction clarification, and safety boundary. Front-loaded with the core operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite being a destructive operation (destructiveHint=true), the description adequately covers scope and safety. No output schema is present, but for a removal operation, describing what is/isn't affected suffices. Could slightly improve by mentioning irreversibility explicitly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 100% description coverage with 'Fork workspace ID' and 'ID of the fork page to remove (not the live content ID)'. The description does not add parameter-specific semantics, but with high schema coverage, the baseline 3 is appropriate per rubric rules.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verb 'Remove' with clear resource 'page from a fork workspace'. The parenthetical '(discards the fork copy, does not affect the live page)' effectively distinguishes this from sibling tools like 'delete_content' (live deletion) and 'delete_fork' (entire workspace deletion) by scoping the operation to fork copies 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 parenthetical clause 'does not affect the live page' provides explicit usage boundaries (when NOT to use), establishing that this tool is for fork workspace cleanup only. While it doesn't explicitly name alternatives like 'delete_content', the negative constraint clearly signals this is inappropriate for live content management.
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?
While annotations declare readOnlyHint=true indicating a safe operation, the description adds essential behavioral context by clarifying that 'get' retrieves metadata only, not binary file content. This manages expectations about the return payload that annotations alone don't 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 sentences, optimally structured: first establishes purpose and parameters, second provides critical behavioral constraint. Zero redundancy; every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple retrieval tool with fully documented parameters and read-only annotations, the description is complete. It compensates for missing output schema by clarifying what is returned (metadata) and what isn't (file content).
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 100% schema description coverage (id and path fully documented), the schema carries the primary load. The description adds value by confirming these are alternative identifiers ('ID or path'), implying mutually exclusive usage, but does not elaborate on parameter formats 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 specific action ('Get'), resource ('asset metadata'), and identifiers ('by ID or path'). It further distinguishes itself from assumed file retrieval by explicitly stating it 'Does not return file content', which differentiates it from potential file-serving 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 clear guidance on limitations ('Does not return file content') and points toward the correct alternative method ('use the serve path to access the file'). However, it lacks explicit guidance on when to use this vs list_assets or other 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 establish idempotency and non-destructiveness; description adds crucial behavioral context about 'automatic pruning' protection (lifecycle management) and observability ('marked with locked=true in get_theme_versions'). Discloses protection scope 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?
Three well-structured sentences: functional definition, usage context, and practical example. Every sentence earns its place with zero redundancy. Front-loaded with the core action and mechanism.
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?
Appropriately complete for low-complexity tool (single parameter, no output schema). Covers protection mechanism, verification method, usage scenario, and input format without needing return value documentation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with parameter already documented as 'Theme version number to pin/unpin'. Description provides syntax example ({'version': 5}) but does not significantly expand semantic meaning beyond the comprehensive schema 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?
States specific action (Lock/protect) on specific resource (theme version) with clear scope protection from 'automatic pruning or accidental overwrite'. Distinguishes from siblings by referencing get_theme_versions for observability of the locked state and implies relationship to unpinning operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use guidance ('preserve milestone theme states...before making further changes') with contextual example (after major redesign). References get_theme_versions for verification. Does not explicitly name unpin_theme_version as the reversal mechanism, though sibling naming makes this inferable.
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; the description complements this by detailing the five mutation operations (clear, set, prepend, append, wrap) and their exact behavior, plus explaining dry_run safety mechanics. Adds substantial behavioral context beyond the annotation flags.
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?
Excellent structure: one-line summary, bulleted operation definitions, scope filter guidance, dry_run note, and concrete example. Information is front-loaded and every sentence/section serves a distinct purpose with 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?
Comprehensive coverage for an 11-parameter destructive tool: documents all operations, filtering strategies, and safety mechanisms. Missing return value description, but acceptable given no output schema per rubric guidelines.
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 crucial semantic value by enumerating operation variants (clear vs set vs wrap) and mapping scope filter concepts to specific parameters. The JSON example demonstrates parameter relationships (operation + field + value + template_name).
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 applies a 'single field operation' to 'all matching content pages' using specific verbs (apply, set, prepend, append). The 'field' specificity distinguishes it from sibling 'bulk_update_content' which likely handles full content updates.
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 using scope filters (content_ids, folder_path, etc.) to limit affected pages and emphasizes dry_run for previewing changes. While it doesn't explicitly name sibling alternatives, the 'single field' framing implies use for targeted field edits versus broader bulk updates.
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?
Far exceeds the destructiveHint=true annotation by detailing exact merge semantics (updates existing, creates new, conflict recording), side effects (fork status becomes 'merged', immediate regeneration), and return values (updated count, created count, conflicts). Discloses auth requirements ('admin role') not in 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?
Well-structured with bullet points clarifying merge logic per page state. The ALL-CAPS warning appropriately emphasizes safety for a destructive operation. Slightly verbose for a single-parameter tool, but warranted given operation complexity and destructive nature.
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?
Comprehensive for a complex mutation: covers prerequisites (admin), detailed behavior (update vs create logic, conflict handling), side effects (status change, regeneration), return structure (counts/conflicts), and safety warnings. No output schema exists, but description adequately documents returns.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for single parameter fork_id. Description references 'fork workspace' contextually but adds no syntax, format, or constraint details beyond the schema. Baseline 3 appropriate when schema carries full documentation load.
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?
Opens with specific verb 'Merge' + resource 'pages in a fork workspace' + target 'live content'. Clearly distinguishes from siblings (create_fork, delete_fork, archive_fork, fork_page) by explaining the specific merge strategy (fork wins, conflict handling) rather than just restating the name.
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?
States prerequisite 'Requires admin role' and includes explicit safety directive 'ALWAYS confirm with the user before merging'. However, lacks explicit contrast with alternatives like archive_fork or when NOT to use (e.g., 'use this instead of manually updating when...').
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?
Strong: Annotations declare readOnlyHint=true, and description adds valuable risk context ('Safer than site-wide replacement') and explains that scopes are optional ('leave blank to match all pages'). 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?
Excellent structure: Purpose front-loaded, scope options clearly bulleted, example provided, and workflow guidance included. Zero waste—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?
Thorough for a 9-parameter tool: Covers all scope dimensions, required fields implied by example, and workflow explained. Minor gap: could briefly describe preview output format since no output schema exists.
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?
High value despite 100% schema coverage: Groups scope parameters conceptually with clear semantic explanations (e.g., 'pages under /blog, /docs'), and provides concrete JSON example showing parameter interaction.
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?
Excellent: States specific action ('Preview a search-and-replace'), target resource ('subset of pages'), and distinguishes from siblings ('Safer than site-wide replacement' contrasts with search_replace_preview).
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?
Good: Explicitly recommends workflow ('Always run preview before execute') and contrasts with site-wide alternatives. Could be improved by explicitly naming sibling tools (scoped_search_replace_execute, search_replace_preview) to use instead.
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 security validation behavior ('Validates file type and MIME type') and infrastructure constraints ('MCP transport size limits') not present in annotations. Clarifies upsert/replacement semantics. Annotations declare non-destructive operation, and description frames replacement as a convenience feature rather than data destruction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tightly focused paragraphs: action/replacement behavior, content provision options with clear bullet structure, and validation notice. No redundant text; every sentence conveys distinct operational information. Well front-loaded with primary action.
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?
Comprehensive coverage of upload semantics, security constraints, and transport limitations for a 5-parameter file operation. Absence of output schema is noted but description sufficiently covers input concerns and behavioral expectations for successful 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 100% schema coverage (baseline 3), description adds crucial semantic guidance: specifies mutual exclusivity ('via one of'), size thresholds (>100KB) for choosing between file_path and data_base64, and explains the replacement semantics of serve_path parameter beyond the schema's basic definition.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States specific action ('Upload or replace') and resource ('asset in the asset library'). Explicitly distinguishes from sibling delete_asset by noting replacement happens 'in place — no need to delete first', and implicitly distinguishes from upload_asset_from_url by specifying local file content provision methods.
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 clear operational guidance: explains replacement behavior (re-uploading to same serve_path replaces existing file) and selection criteria for content sources (file_path preferred for >100KB to avoid transport limits vs data_base64 for small files). Stops short of explicitly naming upload_asset_from_url as the alternative for remote URLs.
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-destructive; description adds valuable behavioral context including isolation guarantees ('without affecting the public site'), return value disclosure ('Returns the fork ID needed for subsequent fork operations'), and workflow sequencing. Could mention auth requirements or side effects for a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Four distinct segments: one-line summary, concept explanation, numbered workflow (4 steps), and return value note. Every sentence earns its place with zero redundancy. Clear front-loading with the essential action stated immediately.
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?
Excellent completeness given no output schema exists: description explicitly states the return value (fork ID). Covers the full lifecycle context (creation through merge), explains relationship to live site, and provides sufficient detail for a workspace creation tool with 100% schema coverage.
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 'name' and 'description' parameters fully documented in schema). Description references 'named fork workspace' which aligns with the name parameter, but adds no syntax, format, or example details beyond what the schema already provides. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Opens with specific verb+resource: 'Create a new named fork workspace for staging content changes.' Explains what a fork is (isolated workspace) and distinguishes from siblings by explicitly positioning it as step 1 in a 4-step workflow distinct from fork_page, update_content, and merge_fork.
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 typical workflow with numbered steps showing exactly when to use this tool (step 1: create workspace) versus alternatives (step 2: fork_page, step 3: update_content, step 4: merge_fork). Also clarifies admin restriction applies to merge step, helping users understand this tool's prerequisites.
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 readOnlyHint=true in annotations, description confirms safety with 'without saving.' Critically, it compensates for missing output schema by disclosing return structure ('rendered_html and any warnings') and specific warning types (missing fields, unclosed tags, unresolved placeholders).
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 efficient sentences: purpose, usage, parameter example with syntax, and return value disclosure. No repetition of schema details, appropriately front-loaded with 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?
Thoroughly complete for a preview tool: describes output to compensate for missing output schema, provides parameter usage examples for the nested data object, and clarifies behavioral boundaries (read-only) given the complexity of 3 parameters including nested overrides.
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?
Despite 100% schema coverage (baseline 3), description adds value via concrete JSON example showing override syntax, and reinforces 'not saved' semantics for the data/title overrides. The example provides concrete usage context beyond the schema definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses specific verb 'Render' with resource 'content item's HTML' and explicitly distinguishes from siblings by stating 'without saving or publishing,' clearly differentiating it from update_content and publish_content in the sibling list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear when-to-use context ('verify what a page will look like before publishing'), implicitly establishing the workflow relationship with publish_content. Does not explicitly name the alternative tool, so stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare destructiveHint=true; description complements this with safety protocol (preview requirement) and explains side effects of auto_republish ('immediately re-publish all previously-published pages'). Could further clarify irreversibility implications, but covers key workflow behaviors 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?
Well-structured with critical workflow constraint ('ALWAYS...') front-loaded. Efficient bullet-style scope listing. Example JSON is long but functional. No redundant repetition of schema details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Comprehensive for a complex 9-parameter destructive operation: covers preview requirement, scoping logic, auto-republish shortcut, and provides valid example. No output schema exists, but description adequately explains the operation's behavioral contract.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% so baseline is 3. Description adds significant workflow context for 'auto_republish' (explaining it replaces a separate publish_multiple call) and provides a concrete JSON example showing parameter interaction. Scope options are listed but not semantically expanded 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?
States specific verb ('Execute'), resource ('pages'), and scope ('limited to a subset'). Effectively distinguishes from sibling 'search_replace_execute' by emphasizing scoping, and from 'scoped_search_replace_preview' by identifying this as the execution step.
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 prerequisite: 'ALWAYS run scoped_search_replace_preview first'. Explains workflow alternative (auto_republish 'collapsing the execute + publish_multiple flow into one call'), clearly mapping when to use the flag vs separate calls.
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; the description reinforces this ('without making any changes') and adds necessary return value details ('affected page count, total match count, and per-page field breakdown') to compensate for the missing output schema. Could mention regex flavor or performance characteristics for a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences with zero waste: sentence 1 establishes purpose and critical workflow rule, sentence 2 documents return values, sentence 3 provides scoping guidance. Perfectly 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?
Excellent completeness for a complex operation. Compensates for missing output schema by documenting return values, establishes the preview→execute safety pattern, and maps the sibling tool ecosystem (scoped vs site-wide, preview vs execute).
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%, clearly documenting all three parameters (search, replace, regex). The description does not add semantic details beyond the schema, meeting the baseline expectation.
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 specific action ('Preview a site-wide search-and-replace') and explicitly distinguishes from siblings by naming both 'search_replace_execute' (workflow predecessor) and 'scoped_search_replace_preview' (scope alternative).
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?
Contains explicit workflow guidance ('ALWAYS run this before search_replace_execute') and clear alternative selection criteria ('For targeted replacements... use scoped_search_replace_preview instead').
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 provide destructiveHint=false and openWorldHint=true. The description adds valuable behavioral details not in annotations: the automatic filename derivation logic ('If serve_path is omitted...') and the complete return value structure ('Returns id, serve_path, mime_type, and size') which compensates for the missing output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured with purpose first, use case second, concrete example third, and behavioral details last. Every sentence adds distinct value (purpose, differentiation, example, default logic, return values) 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?
Given the 100% schema coverage and annotations covering safety (destructiveHint), the description provides appropriate completeness by documenting the return payload (compensating for no output schema) and providing a concrete usage example. It adequately covers the tool's contract for an AI 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?
With 100% schema coverage, the baseline is 3. The description adds an inline JSON example demonstrating realistic values for all three parameters, and explicitly explains the default behavior for serve_path derivation, adding semantic meaning beyond the schema definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Fetch a public URL and store it as a LightCMS asset') with clear resource and verb. It distinguishes itself from the sibling 'upload_asset' by emphasizing 'from the web without downloading them locally first,' clearly scoping the tool to URL-based ingestion.
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 ('Useful for importing images or files from the web') and implies the benefit over alternatives ('without downloading them locally first'). However, it does not explicitly name 'upload_asset' as the alternative for local files or state explicit when-not-to-use conditions.
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; description adds return structure ('metadata including title, path, publish status'), soft-deletion handling ('include_deleted'), and workflow concurrency guidance for subsequent operations. Could clarify pagination behavior but solid coverage otherwise.
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 distinct units: purpose/returns (sentence 1), parameter optimization (sentence 2-3), workflow guidance (sentence 4). Zero redundancy; every sentence advances selection or invocation logic.
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?
Compensates well for missing output schema by listing return fields. Covers soft-deletion filtering and bulk workflow integration. Given 5 parameters with full schema coverage, provides sufficient context for correct invocation and result handling.
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 100% schema coverage (baseline 3), description adds semantic value explaining the optimization strategy: include_data 'to get full field data... in one call' and include_fields as 'more efficient than include_data', clarifying *why* to use each parameter beyond the schema definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Opens with specific verb 'List' + resource 'content items' + scope 'with optional filters'. Explicitly distinguishes from sibling get_content by noting it returns 'metadata' vs full field data, and contrasts 'per-item get_content calls' with bulk listing capabilities.
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 names alternatives: 'avoid per-item get_content calls' (select this over get_content for bulk), references bulk_update_content for >20 items vs update_content. Provides clear when-to-use for include_data vs include_fields for 'bulk workflows'.
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 cover idempotent/destructive hints, so description adds valuable behavioral context by specifying return format ('list of published IDs') and crucially notes 'any failures' indicating partial success behavior. Could further clarify publish semantics (e.g., making content live/public).
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?
Efficiently structured with purpose statement, usage guideline, bulleted examples, and return description. Zero redundant sentences; every clause adds selection or invocation guidance.
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?
Absence of output schema is compensated by describing return values and failure cases. 100% input schema coverage means parameters are well-documented. Minor gap: does not elaborate on side effects of 'publish' operation (visibility changes, permissions 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?
With 100% schema coverage, baseline is 3. Description earns additional point by providing concrete JSON examples showing ID format ['abc123', 'def456'] and boolean usage, adding semantic context beyond the schema's type definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States specific verb 'Publish' with resource 'content items' and scope 'in a single call'. Explicitly distinguishes from sibling tool 'publish_content' by contrasting batch vs. loop usage.
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?
Contains explicit directive 'Use this instead of calling publish_content in a loop' identifying when to select this tool over its sibling. Examples further clarify both specific ID batching and bulk draft publishing patterns.
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=true. The description adds valuable behavioral context: 'Only the fields you provide are changed' clarifies partial update semantics, and 'Always include a version_comment' establishes a usage requirement not captured in 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 well-structured sentences: first establishes purpose and differentiation, second provides concrete example, third explains mutation semantics and versioning requirements. No redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 9-parameter destructive operation with no output schema, the description covers the essential behavioral contracts (partial updates, versioning requirement) and distinguishes itself from siblings. Could optionally mention error behavior for non-existent paths, but adequately complete as-is.
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 100% description coverage (baseline 3). The description adds a concrete JSON example showing how to structure the request object, particularly demonstrating the nested 'data' object usage, which adds practical value beyond the structured 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 specific action ('Update content') and resource (content by URL path), and explicitly distinguishes this from siblings by noting 'instead of its MongoDB ID'—directly contrasting with the likely update_content tool that uses ID.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use this tool vs alternatives: 'Useful when you know the page URL but not the MongoDB ID.' This provides clear guidance on selecting this tool over the ID-based update_content sibling.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations establish destructiveHint=true (mutation), while description adds merge semantics ('only the fields you want to change'), explains dry_run validation behavior, distinguishes clear_fields from merge updates, and details return structure ('total attempted, succeeded, failed counts') compensating for lack of output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with core purpose and sibling distinction; structured logically from operation definition → semantics → return values → workflow tip → optimization. No wasted words; each sentence advances understanding of how to invoke correctly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite lacking output_schema, description fully specifies return values ('total attempted, succeeded, failed counts, and per-item success/error details'). Covers batch limits (100 max, 50 recommended), destructive behavior (annotations + merge semantics), and workflow integration for a complex nested update 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?
With 100% schema coverage, description adds crucial semantic context: explains merge semantics on data field vs explicit clearing via clear_fields, clarifies dry_run validates 'IDs exist without committing', and contextualizes version_comment as applying to 'all updates' in the batch.
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 opens with specific verb ('Update') and resource ('content items'), explicitly quantifies scope ('up to 100'), and immediately distinguishes from sibling tool 'update_content' by stating 'Use instead of calling update_content in a loop'.
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 identifies when to use this tool versus alternative ('Use instead of calling update_content in a loop'), provides workflow prerequisites ('Tip: call list_content...first'), and includes performance guidance ('Recommended batch size: up to 50 per call').
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?
While annotations only indicate non-destructive behavior, the description extensively documents behavioral traits: wikilinks auto-update when paths change, Markdown converts to HTML at publish time, templates support {{.lc_toc}} injection, hashtags auto-tag pages, and version_comment affects history readability. This exceeds annotation coverage significantly.
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 visual hierarchy: one-sentence summary, numbered workflow, specific parameter guidance, and rich markup documentation. While lengthy (appropriate for 15 parameters and complex templating behavior), every section serves distinct purposes 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 complexity (15 parameters, nested data object, rich markup features), the description comprehensively covers input requirements, workflow dependencies, and content processing behaviors. No output schema exists per context signals; the description appropriately focuses on creation mechanics rather than return values.
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 100% schema coverage, baseline is 3. The description adds valuable context: template_id requires calling list_templates first, use_header/footer/theme control site layout wrapping, published=true combines creation with publishing, and version_comment is required for readable history. This elevates it above baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear, specific statement ('Create a new content item') and immediately distinguishes this from sibling tools by specifying required fields (template_id, title, slug, data) and contrasting with create_template, create_snippet, and create_collection.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides an explicit numbered workflow (1. Call list_templates, 2. Create content, 3. Call publish_content) that establishes prerequisites and sequence. It explicitly names sibling tool publish_content as an alternative to using the published parameter, clarifying when to use each approach.
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 confirm readOnlyHint=true (safe read operation). Description adds valuable behavioral context: details return structure ('total count and array of items with id, title...') since no output schema exists, and documents that all scope filters are optional. 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?
Perfectly structured with clear information hierarchy: purpose → workflow → filter semantics → field selection → returns. No filler text. Each sentence adds distinct value (workflow guidance, filter categorization, return documentation).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Fully compensates for missing output schema by documenting return fields (id, title, slug, etc.). Explains all 5 optional parameters with usage contexts. Complete guidance for batch operations without external documentation needed.
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 100% coverage (baseline 3). Description adds significant semantic value beyond schema: explains template_name is 'most useful for bulk workflows' with concrete examples ('Concept Page', 'Blog Post'), classifies other filters as 'narrower scoping options', and clarifies fields parameter behavior ('empty = all fields').
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Excellent specificity: states exact action ('Export'), resource ('content items'), format ('structured JSON array'), and distinguishes from siblings by referencing 'bulk_update_content' as the complementary re-import tool. Clear scope distinction from simple list 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?
Explicit workflow pattern documented: 'export → transform externally → re-import via bulk_update_content'. Names the specific sibling alternative (bulk_update_content) and explains filter selection logic ('template_name: most useful for bulk workflows' vs 'narrower scoping options').
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 provide idempotentHint:true and destructiveHint:false. Description adds valuable behavioral context: confirms idempotency with 'If the page is already in this fork, returns the existing fork copy', mentions output 'Returns the fork page ID', and notes admin requirements for the merge step. Does not contradict 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?
Front-loaded with purpose in first sentence. Efficiently structured with bullet points for parameter options and numbered list for workflow. Every sentence earns its place: purpose, input options, output/workflow, and idempotency edge case. No waste.
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?
No output schema exists, but description documents return value (fork page ID) and complete lifecycle workflow including verification step. Covers edge case (already forked) and authorization note. Adequate for a complex CMS fork operation with 3 input parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 100% coverage (baseline 3). Description adds selection guidance distinguishing path ('preferred when you know the URL') from content_id, and documents their mutual exclusivity via 'Provide either'. Adds semantic value beyond raw schema 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?
Opens with specific action 'Copy a live page into a fork workspace' plus clear benefit 'edit without affecting the public site'. Distinguishes from siblings like create_content (creates new) vs. forking existing, and explicitly references the workflow endpoint merge_fork.
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 4-step workflow (fork_page→update_content→get_content→merge_fork) with tool names. Explains parameter selection logic ('preferred when you know the URL'). Notes authorization constraint 'admin only' for merge step. Handles idempotency case.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true. Description adds valuable context: explains the fork domain concept (batch staging) and documents return payload contents (status, page count, creator) despite lack of output schema. Does not mention pagination or side effects 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 with zero waste: first states action + domain concept, second documents return values, third provides sibling guidance. Information is front-loaded and 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?
Despite no output schema, description fully compensates by detailing what fields are returned. With zero parameters and simple listing behavior, the description is complete covering purpose, usage guidance, and return value structure.
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?
Input schema has zero parameters. Per guidelines, 0 params baseline is 4. Description correctly provides no parameter details since none exist.
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 uses specific verb 'List' with resource 'content fork workspaces' and distinguishes scope from sibling get_fork by noting this lists 'all' workspaces while get_fork is for 'specific pages'. It also defines what forks are conceptually (staging changes before merging).
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 directs users to sibling tool get_fork with 'Use get_fork to see the specific pages in a fork', clearly indicating when to use the alternative instead of this listing 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 declare destructiveHint=true; the description adds critical behavioral context that the modification is 'permanent', specifies the mandatory 3-step workflow (preview, confirm, execute), and clarifies the side effects of auto_republish. Does not mention rollback capabilities or rate limits, but covers primary behavioral concerns.
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?
Front-loaded with the core function, followed by clearly demarcated 'MANDATORY workflow' steps, then specific parameter guidance. Every sentence conveys critical instruction or context; zero waste. Structure prioritizes safety-critical workflow information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the destructive nature (destructiveHint:true) and lack of output schema, the description is complete. It covers the essential safety workflow, distinguishes from all relevant siblings (preview and scoped variants), and explains the primary parameters' interaction (auto_republish). No additional description text is needed for an AI to invoke this 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?
With 100% schema coverage (baseline 3), the description adds significant value by explaining auto_republish's practical effect ('collapsing the execute + publish_multiple flow into one call') and specifying that version_comment should be 'clear' according to the workflow. Elevates beyond raw schema definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool executes a 'site-wide search-and-replace across all content' with the specific verb 'Execute' and resource 'all content'. It effectively distinguishes from siblings by contrasting with scoped_search_replace_execute ('For targeted replacements, use...instead') and implicitly from search_replace_preview by stating this 'Modifies...permanently' vs the preview's 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 Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when/when-not guidance: mandates running search_replace_preview first, getting explicit user confirmation, and suggests scoped_search_replace_execute for targeted replacements. Also explains when to use auto_republish (to collapse execute + publish_multiple into one call).
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 critical side-effect details beyond annotations: header_html/footer_html trigger background regeneration of all published pages while colors/fonts/custom_css do not, and clarifies partial update semantics. Annotations declare idempotent/destructive hints; description adds regeneration timing and scope.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tightly structured paragraphs: partial update semantics upfront, regeneration behavior specifics in middle, workflow recommendation at end. No redundancy with schema or annotations.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Comprehensive for a 15-parameter mutation tool: covers mutation type (partial), side effects (regeneration), sibling interactions (get_theme, pin_theme_version), and safety profile. With 100% schema coverage and annotations present, no output schema needed in description.
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 100% coverage establishing baseline 3. Description adds semantic value by grouping specific parameters (header_html/footer_html vs colors/fonts/custom_css) by their regeneration behavior, explaining operational significance of modifying each group.
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?
Specific verb 'Update' with resource 'theme settings', clearly distinguishes from sibling get_theme by noting 'safe to call without get_theme first', and differentiates from pin_theme_version by explaining this performs the update while that protects milestones.
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 prerequisites ('safe to call without get_theme first'), clear workflow guidance ('Use pin_theme_version to protect important milestones before making major changes'), and behavioral conditions for regeneration provide 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, so the description appropriately focuses on output behavior rather than safety. It adds valuable context about what 'rendered' means (template + theme header/footer) and clarifies the difference between published content and preview states, though it could mention caching or error behaviors.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Four tightly structured sentences that front-load the core purpose, followed by specific parameter guidance, optional flag explanation, and cross-reference. Every clause earns its place 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?
With no output schema provided, the description comprehensively compensates by detailing exactly what fields are returned (title, slug, data fields, published state) and the optional rendered HTML output. It addresses the key sibling relationship with preview_content, leaving no critical gaps for a read operation.
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 adds substantial value with concrete JSON syntax examples ({'path': '/about'}), semantic usage guidance distinguishing URL vs ObjectID scenarios, and detailed explanation of the rendered output behavior beyond the boolean flag 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?
Description clearly states the specific action (get), resource (single content item), and identification methods (ID or path). It distinguishes from sibling tools by explicitly mentioning 'preview_content' as an alternative for unsaved edits and implies singularity versus 'list_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?
Provides explicit guidance on when to use each identifier ('Prefer path when you know the URL', 'Use id when you have the MongoDB ObjectID'). It explicitly states when NOT to use this tool ('use preview_content instead' for unsaved edits), giving clear 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 cover idempotency/destructiveness, but description adds crucial behavioral context: automatic versioning ('Creates a new version automatically'), merge semantics for partial data updates, clear_fields deletion mechanism, dry_run validation mode, and concurrency limits (20 calls). Also documents rich markup features (Wikilinks, includes, hashtags) and template capabilities.
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?
Lengthy but well-structured and front-loaded. Core mechanics (ID-based update, versioning, partial updates) appear first. Specific parameter behaviors follow. Alternatives and limits come next. Advanced content features (markup, templates) appropriately placed at end. Every sentence provides distinct value despite 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?
Comprehensive coverage for a complex 21-parameter destructive operation. Documents versioning behavior, update semantics (merge vs clear), validation mode, concurrency limits, and content format capabilities. No output schema exists, but description sufficiently covers invocation behavior and side effects.
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 100% coverage (baseline 3). Description adds significant usage context: explains merge semantics for 'data' field, demonstrates 'clear_fields' array syntax, clarifies 'dry_run' validation purpose, and provides a concrete JSON example showing parameter interaction.
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?
Opens with specific verb 'Update' + resource 'content item' + identifier 'by ID'. Explicitly distinguishes from sibling 'update_content_by_path' ('To update by URL path instead of ID, use...') and 'bulk_update_content' ('For larger batches...prefer bulk_update_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?
Provides explicit when/when-not guidance: use sibling for path-based updates, use bulk tool for >20 items, use dry_run for validation, and always include version_comment. Clear guidance on partial vs full updates ('Only send fields you want to change').
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:

[![lightcms MCP server](https://glama.ai/mcp/servers/jonradoff/lightcms/badges/card.svg)](https://glama.ai/mcp/servers/jonradoff/lightcms)

Score Badge

Copy to your README.md:

[![lightcms MCP server](https://glama.ai/mcp/servers/jonradoff/lightcms/badges/score.svg)](https://glama.ai/mcp/servers/jonradoff/lightcms)

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/jonradoff/lightcms'

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