@writavo/mcp-server

Server Quality Checklist

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

Latest release: v0.1.0
Disambiguation5/5
Each tool targets a distinct resource and action. Articles, categories, tags, authors, media, and pipeline are cleanly separated, and related operations like get/list are clearly differentiated.
Naming Consistency5/5
All tools follow the verb_noun pattern with consistent lowercase_snake_case. Prefixes like get_, list_, create_, update_, delete_, publish_, unpublish_, schedule_ are applied uniformly across resources.
Tool Count2/5
At 38 tools, the server is well above the 25+ threshold for a large tool set. While each tool has a distinct purpose, the sheer number is likely to overwhelm an agent and complicates tool selection.
Completeness5/5
The server provides full CRUD and lifecycle coverage for articles, categories, tags, authors, and media, plus publishing, scheduling, pipeline management, and metadata. No obvious gaps for the stated domain.
Average 4.4/5 across 38 of 38 tools scored. Lowest: 3.8/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 4 commits in the last 12 weeks
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI status not available
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

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

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

How is the quality score calculated?

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

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

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

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

Tool Scores

Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, so the description's 'Read only. Nothing is changed.' is redundant, but it adds valuable context: the required secret key scope ('wv_sk_' with 'media:read') and the default ordering ('newest first'). This exceeds what annotations provide, though it omits details like error behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief and front-loaded with the core purpose. The phrase 'Read only. Nothing is changed.' is redundant with the readOnlyHint annotation, making it slightly less efficient, but overall it's a tightly structured three-sentence description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core action, ordering, auth, and safety, but it omits any mention of the response format or pagination. Since there is no output schema, the description should hint at the return structure (e.g., a list with `next_cursor` for pagination). The cursor parameter's description partially covers this, but the tool-level description remains incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description provides no parameter-level semantics, but the input schema already documents limit (with clamping), cursor (opaque, do not parse), and fields (default projection) in detail. The only undocumented parameter is bucket, but its enum values are provided in the schema. With 75% schema description coverage, the description's silence is acceptable; it adds nothing but also doesn't need to.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'List media assets.' It adds specific context ('The media library, newest first') and distinguishes it from sibling list tools like list_articles or list_categories. The verb+resource combination is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies its use for listing media assets but provides no explicit guidance on when to prefer it over related tools such as get_media (for a specific asset) or upload_media. There are no exclusions or alternative recommendations, so usage guidance is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description adds value by specifying the required OAuth scope 'authors:read' and confirming the singular read operation. It does not contradict annotations and provides additional auth context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, consisting of short phrases that each convey necessary information: purpose, read-only assurance, and required scope. It front-loads the core action and has no filler, making it highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-resource get tool with strong annotations, the description covers the essential details: what it does, its read-only nature, and the auth requirement. It does not describe return values, but the output is obviously an author object, and the lack of an output schema does not create a significant gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema describes 'id' as 'A UUID,' and the description adds little beyond that. Although the tool name and description imply the id refers to the author, the description does not explicitly explain the parameter's role or format beyond the schema, leaving semantics at a baseline level.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with 'Read one author,' using a specific verb and resource that clearly distinguishes this from list_authors, create_author, update_author, and delete_author. The phrase 'Read only. Nothing is changed' reinforces the read-only nature.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for fetching a single author but does not explicitly state when to use this tool over alternatives like list_authors, or when not to use it. There is no exclusionary guidance, so it falls short of a clear usage guideline.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds an auth requirement ('Needs a key carrying the taxonomy:read scope') that is not present in annotations. It also reinforces the read-only and non-destructive nature, consistent with annotations, without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with three short sentences, each adding value: purpose, safety, and auth requirement. It is front-loaded and free of filler, earning a high score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (single parameter, no output schema), the annotations cover safety, and the schema covers parameters, the description is nearly complete. The auth scope adds useful contextual detail. It does not describe return format, but that is not critical for a simple getter.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully covers the only parameter 'id' with a description of 'A UUID', achieving 100% coverage. The description does not add extra meaning beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reads one category, using a specific verb and resource. It distinguishes from sibling tools like list_categories, create_category, update_category, and delete_category by indicating a single read operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for retrieving a specific category by ID but does not explicitly mention alternatives such as list_categories for multiple categories or exclude write operations. The read-only context is clear, but no direct when-not-to-use guidance is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, destructiveHint, idempotentHint, and openWorldHint. The description adds the specific authentication requirement ('key carrying the taxonomy:read scope') and plain-language reassurance ('Nothing is changed'), which go beyond annotations. It does not describe return format, but for a simple read operation this is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief and front-loaded with the purpose. However, 'Read only' and 'Nothing is changed' are somewhat redundant with each other and the readOnlyHint annotation, adding slight unnecessary repetition. Nonetheless, it remains concise and structured effectively.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple tool with one parameter, rich annotations, and no output schema. The description covers purpose, safety, and authentication, making it complete enough for correct use. The sibling tool names provide additional context for when to use it, eliminating ambiguity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% coverage for the single parameter 'id' as 'A UUID'. The description adds no additional meaning beyond the schema, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Read one tag' with a specific verb and resource, distinguishing it from sibling tools like list_tags, create_tag, update_tag, and delete_tag. The 'Read only' phrasing reinforces the read-only nature, making the purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for reading a single tag by ID, supported by the schema and sibling context, but it does not explicitly state when to use this tool over alternatives like list_tags. No exclusions or alternative recommendations are provided, only inferred from 'Read one tag'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavior beyond annotations: it discloses the 404 masking for unauthorized access, the publishable key restriction, the required `articles:read` scope, and the fact that nothing is changed. These are not covered by the readOnlyHint, openWorldHint, or idempotentHint annotations, so it enriches the behavioral profile.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core action and return value. It is mostly concise, but the sentence about 'no disclosure reason that governs cross Site access' is somewhat convoluted, and 'Read only. Nothing is changed.' duplicates annotation info. Still, it remains tight and readable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (read one article by ID), and the description covers the return value, auth requirements, the 404 edge case, and the safety profile. No output schema exists, but the description adequately conveys what the tool returns. The `fields` parameter is documented in the schema, so the description does not need to repeat it.
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%, and both `id` and `fields` already have clear descriptions. The tool description does not add extra meaning to the parameters; it only mentions `content` as part of the return, which is not parameter-specific. Thus, baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with 'Read one article,' which clearly identifies the verb and resource. It further specifies it 'Returns the full article including `content`,' distinguishing it from list_articles, create_article, and other sibling tools that handle multiple articles or mutations.
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: this is for reading a single article by ID. It also notes a specific condition (publishable key can only read published articles, otherwise 404) and required scope. However, it does not explicitly mention alternatives like list_articles for fetching multiple articles, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the description's 'Read only. Nothing is changed.' is redundant. However, it adds the secret key scope requirement (wv_sk_ with media:read), which is not present in annotations. It does not disclose return format or error behavior, but for a simple read tool this is acceptable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, front-loaded with 'Read one media asset.' Every sentence adds necessary info: purpose, read-only safety, and auth requirement. No fluff or repetition beyond what is structurally needed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is very simple: one parameter, no output schema, read-only. The description covers purpose and auth, which is mostly sufficient. It omits any mention of the return value, but the name 'get_media' implies a media asset object is returned. A brief note about response would make it fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter 'id' is described in the schema as 'A UUID,' which is minimal. The description does not add further meaning about what the id refers to or how to obtain it. Since schema coverage is 100%, baseline is 3, and the description contributes nothing extra for the parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Read one media asset' with a specific verb and resource, and reinforces 'Read only. Nothing is changed.' This distinguishes it from mutation tools like update_media or delete_media and from list_media which would fetch multiple assets.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear prerequisite: 'Needs a secret key (wv_sk_) carrying the media:read scope,' which tells the agent when authentication is acceptable. It does not explicitly name alternatives or say 'use list_media for multiple assets,' but the singular 'one' implies the specific use case.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds the authentication requirement ("Needs a secret key (wv_sk_) carrying the pipeline:read scope"), which is useful operational context. It also explains the source enum semantics (manual, content_gap, competitor_seed) and the priority ordering, going beyond what annotations provide. The statement "Read only. Nothing is changed" reinforces but 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three well-structured sentences: purpose, item composition, and auth requirement. No wasted words, and the most important information (what it does) is front-loaded. Each sentence adds distinct value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only list tool with no output schema, the description covers the essential context: what the queue is, the meaning of items, source types, and priority order. It omits any mention of the `status` filter, but the schema enum largely covers that. The schema already documents pagination for limit/cursor, so no redundancy needed. Overall, it is nearly complete, just missing a hint about the optional `status` filter.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50%, and the description adds meaning to the `source` parameter by explaining the enum values (manual, content_gap, competitor_seed), which is absent from the schema. However, it does not explain the `status` enum or add anything to `limit`/`cursor` beyond what their schema descriptions already say. Since it compensates for only one of the two undocumented params, a middle score is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource: "Read the content queue" and defines exactly what the queue contains ("what the engine plans to write, highest priority first"). It clearly distinguishes this from siblings like get_pipeline_status and list_pipeline_runs, which concern pipeline execution rather than the queue content.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context: it is a read-only operation on the content queue, with items ranked by priority. It does not explicitly name alternatives or state when not to use it, but the intended use case is obvious from the purpose and the sibling tool set. No exclusion cases are mentioned, so it earns a 4 rather than 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare it is read-only and idempotent. The description adds behavioral context beyond annotations: it is cursor paginated, ordered by newest updated first, and requires a specific auth scope. This adds useful value without contradicting the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: three short sentences, front-loaded with the main purpose. Every sentence adds useful information (pagination, read-only, scope). No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a list tool with no output schema, the description covers key aspects: read-only nature, pagination, default ordering, and required scope. It relies on the rich parameter schema for filtering details. Some information about the response shape (e.g., a data array with next_cursor) is not explicitly described, but it is implied by 'cursor paginated' and the schema's cursor field.
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 90%, and the schema descriptions are already detailed for most parameters. The description adds little parameter-specific meaning beyond 'Cursor paginated' and 'newest updated first', which slightly clarify the cursor and order parameters. This is a typical baseline for a well-documented schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List articles' with a specific verb and resource, and the resource is unambiguous. It naturally distinguishes from sibling tools like get_article (singular) and create/update/delete_article, and 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 Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context by noting it is read-only and requires articles:read scope, which implies when it should be used. However, it does not explicitly mention alternatives or exclusions, such as using get_article for a single article, though this is inferable from the name and 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 already provide readOnlyHint, idempotentHint, and destructiveHint, and the description reinforces these with 'Read only. Nothing is changed.' It also adds the auth requirement ('Needs a key carrying the authors:read scope'), which is beyond the annotations. This provides useful behavioral context without contradicting annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the core action 'List authors', followed by brief context. Every clause contributes value—scope, side-effect safety, and auth requirement—without redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list tool, the description covers essential context: what it lists, that it is read-only, and the required auth scope. The schema documents parameters comprehensively. It does not explain the return shape, but that is less critical given the tool name and the absence of an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers all parameters with detailed descriptions, so the description adds no additional parameter meaning. Baseline for high schema coverage is 3, and there is no extra value from the description beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with a specific verb ('List') and resource ('authors'), and adds the contextual phrase 'byline roster for the Site' which clarifies the scope. It is easily distinguishable from sibling tools like get_author or list_articles.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool (listing all authors in the site's byline roster) and notes the required auth scope. It does not explicitly name alternatives or exclusion criteria, but the context is sufficient for a simple read-only list operation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds the authentication scope requirement and domain context ('closed taxonomy') beyond the annotations, though it redundantly repeats 'Read only. Nothing is changed.'
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and logically structured: verb, scope, domain context, and auth requirement. It contains slight redundancy ('Read only. Nothing is changed.') but remains appropriately sized and front-loaded with essential info.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list tool with comprehensive schema descriptions and safe-behavior annotations, this description fully covers purpose, scope, auth, and domain nuances. No critical information is missing; pagination is already documented in the schema parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% coverage with descriptive comments for all three parameters (limit, cursor, fields). The description adds no additional parameter-specific meaning beyond what the schema already offers, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists categories, defines the scope as every category on the Site, and specifies alphabetical ordering. It effectively distinguishes itself from sibling tools like get_category, create_category, or list_articles.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool (to list all categories alphabetically) and an explicit authentication scope requirement (taxonomy:read). However, it does not explicitly mention alternatives or when not to use it, which would have warranted 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?
The description adds valuable context beyond the annotations: it reveals that the operation modifies the site's content, that it will not make anything public, and that it requires a specific auth scope. This complements the readOnlyHint=false and destructiveHint=false annotations, providing useful behavioral transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with three sentences that front-load the core purpose ('Update a tag') and then provide essential context. There is no redundancy or wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose, auth requirements, and the non-public nature of the update. While it does not mention return values or error cases, the schema provides useful details for id and if_match. Given the tool's moderate complexity and lack of output schema, the description is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50% (id and if_match are described, name and slug are not). The description does not elaborate on the name or slug parameters beyond implying they are updated. It adds little semantic value over the schema, so a mid-range score is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Update a tag.' It adds scope by saying 'Changes content on the customer's Site' and distinguishes from publishing tools with 'Nothing becomes public: publishing is always a separate call.' This makes it specific and differentiates it from sibling update operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context on when to use the tool: for updating a tag without making it public, and mentions the separate publishing step. It also gives the prerequisite of a secret key with taxonomy:write scope. However, it does not explicitly name alternatives or state when not to use it, so it falls short of full usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds substantial context beyond annotations: it always creates at draft status, the `status` field is rejected with a validation error, the operation mutates the customer's site, and it requires a secret key with articles:write scope. This goes well beyond the raw readOnlyHint/destructiveHint flags and gives the agent critical safety and behavioral information.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the core purpose. Each sentence adds useful information: draft status, validation behavior, mutation, publishing separation, and auth requirements. It is slightly redundant in the opening ('Create an article' / 'Creates an article') but not padded, making it efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's 16 parameters and absence of an output schema, the description covers the most important behavioral aspects: draft status, the impossibility of immediate publication, mutation of the site, and required authentication. It does not describe the response shape, but no output schema exists, and the core purpose and constraints are sufficiently clear for an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers 94% of parameters with descriptions like 'Send null to clear it,' so the schema already carries most parameter semantics. The description does not add parameter-specific details, but it does clarify that there is no field to make the article public, which is relevant to the `status` parameter. Baseline 3 is appropriate given high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (create) and resource (article), and immediately specifies the key behavior: creates at `status: draft`. It distinguishes from siblings by noting that it cannot make content public and that publishing is separate, which sets it apart from publish_article and update_article.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when to use it: creating a new article that starts as a draft. It explicitly states a when-not ('publishing is always a separate call'), implying use another tool for publication. It does not explicitly name alternative tools for updates, but the draft-only behavior makes the boundary clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable context beyond these: explains the meaning of 'status: partial' with 'error_summary', notes what 'items_succeeded' indicates, and explicitly states the auth requirement (secret key with pipeline:read scope). This aligns with and enriches 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?
Description is efficient: four sentences, each adding distinct value. Front-loaded with the primary purpose, then clarifies partial-run behavior, output meaning, and auth. No fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description covers the key output fields (status, error_summary, items_succeeded) and the auth requirement. For a simple single-parameter read tool, this is fully adequate and even includes helpful edge-case 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 for the single 'id' parameter is 100% with a clear description ('A UUID'). The tool description does not add parameter-level detail, but it doesn't need to since the schema fully documents the parameter. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description opens with 'Read one pipeline run', a specific verb+resource pair that clearly differentiates this from sibling tools like list_pipeline_runs (which lists multiple) and trigger_pipeline_run (which creates runs). The additional context about outcome and partial status reinforces the purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'Read one pipeline run' provides clear context for when to use this tool: when you need details of a single run, as opposed to listing runs or triggering new ones. It doesn't name alternatives explicitly or state when not to use it, but the singular scope is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds meaningful behavioral context beyond annotations: it is read-only ('Nothing is changed'), requires a specific secret key with the 'pipeline:read' scope, and explains the multi-row behavior per logical run. This goes well beyond the readOnlyHint and destructiveHint 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?
The description is three concise sentences, each providing distinct value: the core action, result shape, and auth/read-only caveats. No redundant or filler language; the most important details are front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is largely sufficient for a list tool, given the annotations and schema already cover safety and pagination. It explains the row semantics and auth requirements. However, since there is no output schema, a brief note about returned fields or pagination behavior could improve completeness, though not essential.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description does not explain any of the four parameters. The schema covers 'limit' and 'cursor' with descriptions, but 'stage' and 'status' are only enum lists with no text; the description adds no meaning to these filters. With only 50% schema coverage, the description should compensate for the undocumented params but does not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List') and resource ('pipeline runs'), adding scope with 'Recent engine activity for the Site, newest first.' It distinguishes from pipeline siblings like get_pipeline_status and trigger_pipeline_run by focusing on historical activity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context about the result shape (newest first, one row per stage invocation), which helps set expectations. However, it does not explicitly mention alternatives or when not to use this tool, such as using get_pipeline_status for a single run's status.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds auth requirements (meta:read scope) beyond annotations, and confirms read-only behavior. Annotations already cover readOnlyHint and destructiveHint, but the additional auth context is valuable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the core purpose. Each sentence adds meaningful information: what it lists, what that means, and the required scope.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple zero-parameter list tool without an output schema, the description sufficiently covers purpose, semantics, and auth. It does not specify the return format, but the absence of an output schema and simplicity of the tool make this acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline is 4. The description does not need to explain parameters and does not attempt to.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists content types, and elaborates that these are article formats (SEO blueprints) used via format_id. This distinguishes it from sibling list tools like list_articles or list_categories.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool: to discover available article formats that can be assigned to articles via format_id. It provides context but does not explicitly name alternatives or state when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavioral context beyond annotations: the required scope (meta:read) and the timezone interpretation for scheduling. The "Read only. Nothing is changed" line reinforces the readOnlyHint but is somewhat redundant; still, the additional scope and timezone details merit credit.
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 relatively concise and front-loaded with the core purpose. Each sentence adds value except "Read only. Nothing is changed," which repeats annotations. Overall it's well-structured but could be slightly tighter.
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 no-parameter tool with no output schema, the description is complete: it lists the returned fields, explains the context (site the key belongs to, timezone interpretation), and states the security requirement. No significant gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the schema is empty (100% covered). The description appropriately focuses on the returned data and context, which is sufficient. No parameter details are needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states "Read Site information" and enumerates the specific fields returned (display name, domain, locale, timezone), making the tool's purpose unambiguous. It distinguishes from sibling CRUD tools by focusing on public site-level metadata.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when to use this tool: to retrieve public site info, and specifically notes that scheduling times are interpreted against the site's timezone. While it doesn't explicitly name alternative tools, the scope is unique among siblings, so usage is well implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds substantial behavioral context beyond the sparse annotations: it discloses the financial impact (spends credit balance, charged per unit of work), the mandatory user-consent flow, and the specific authentication scope. This goes well beyond what readOnlyHint/idempotentHint/destructiveHint convey and alerts the agent to critical side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is four sentences, each carrying essential information: purpose, cost warning, consent requirement, and authentication scope. It is front-loaded with the core action and contains no filler, making it efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the essential context for a non-trivial billing operation: cost, consent, and key scope. It doesn't describe the post-call flow (e.g., whether it returns a run ID, or how to monitor progress), but given the parameters are fully documented and sibling get_pipeline_status exists for monitoring, it is adequately complete for an agent to act safely.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% description coverage for both parameters, including the confirm parameter's consent behavior and max_articles as an upper bound. The description reinforces confirm's requirement but adds no new technical detail beyond the schema, earning 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with a specific verb+resource ('Request a pipeline run') and differentiates it from sibling pipeline read tools (get_pipeline_status, list_pipeline_runs, get_pipeline_queue) by emphasizing it is the only billable operation. This makes the tool's role unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage instructions: ask the user before calling, pass confirm:true only after agreement, and requires a scoped secret key (wv_sk_ with pipeline:run scope). It doesn't explicitly name alternatives, but the 'only billable operation' warning effectively distinguishes it from read-only siblings, giving clear context for when to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnlyHint: false, destructiveHint: false), the description discloses key behavioral traits: the default byline flag side effects (clearing prior default, leaving none), that nothing becomes public until a separate publish call, and the required secret key scope. This is valuable context that annotations alone do not provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured: one sentence for purpose, two for side effects, one for public visibility, and one for auth. Every sentence earns its place with no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the most critical contextual aspects: side effects, auth scope, default byline behavior, and non-publication. However, it does not specify the return value or error behavior, which would be useful given there is no output schema. Missing parameter explanations for name and is_ai_generated also limit full completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description dives deeply into the is_default parameter, explaining its side effects. However, with schema coverage at 57%, the description does not compensate for unnamed parameters like name and is_ai_generated, which lack schema descriptions and are not mentioned. Some parameter semantics are added, but significant gaps remain.
Input schemas describe structure but not intent. Descriptions should explain non-obvious 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 verb+resource pair: 'Update an author.' It then clarifies scope by noting site content changes and that publishing is a separate call, distinguishing it from publish-related tools. The purpose is unambiguous and well-differentiated.
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 strong context: it changes site content, requires a specific auth scope, and explicitly states publishing is separate, which implies when not to use this tool. However, it does not explicitly name alternatives like create_author or delete_author, so it falls short of a full when/when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate a mutating, non-idempotent, non-destructive operation. The description adds concrete behavioral details: slug conflicts return 409 SLUG_CONFLICT, changes are not public until a separate publish call, and a secret key with taxonomy:write scope is required. These go well 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?
Four concise sentences, each providing a distinct piece of information: action, uniqueness constraint, side effect, and auth requirement. The description is front-loaded with the primary action and contains no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple create tool with two parameters and no output schema, the description covers essential aspects: conflict behavior, publication independence, and credential requirements. It is sufficiently complete for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers slug's derivation but name has no description. The description explains slug uniqueness and conflict behavior but omits details about the 'name' parameter. With 50% schema coverage, the description only partially compensates, leaving name semantics implicit.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb and resource: 'Create a tag.' It adds context that the tag is created on the customer's Site, which is unambiguous and distinguishes it from other create tools by resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides useful context: slug uniqueness, publishing is separate, and auth requirements. It implies when to use the tool (for creating tags) and notes that publishing is a separate call, but it does not explicitly mention alternative tools or exclusions. This is clear context without direct exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes beyond the annotations by revealing critical behavioral details: articles are not deleted but their author_id becomes null, the operation is permanent with no trash or undo, and it requires specific scope permissions. This is exactly the kind of context that helps an agent understand side effects, even though destructiveHint=true is already present.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: it leads with the core action, then explains consequences, permanence, consent requirement, and credentials. Each of the four sentences contributes essential information without redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a deletion tool, the description is remarkably complete. It covers the immediate effect, the cascading impact on articles, the irreversibility, the necessary human consent, and the exact permission scope. No output schema is present, but for a simple destructive operation, the description provides all needed context for selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description reinforces the confirm parameter ('pass confirm: true only once they have agreed') and clarifies that id refers to the author being deleted, but it doesn't add significant new meaning beyond the schema. The schema already explains confirm's behavior and id's type.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Delete an author.' It specifies the exact resource and verb, and further distinguishes itself from sibling tools by detailing the effect on associated articles (they remain published but lose their byline). This makes the purpose unambiguous and differentiates it from list, create, get, and update author tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage preconditions: 'Ask the user before calling this' and 'pass confirm: true only once they have agreed.' It also notes the requirement for a secret key with authors:write scope. While it doesn't explicitly mention alternative tools or when not to use it, the destructive and permanent nature is clearly communicated, giving sufficient context for appropriate use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (destructiveHint=true), the description adds critical context: permanence (no trash/undo), side effects (removed from all articles), authentication requirements (wv_sk_ key with taxonomy:write scope), and the confirm workflow. This is a model of behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized for a destructive tool. Every sentence adds value: action, side effects, permanence, user confirmation, and auth requirement. It is front-loaded with the core action and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description is self-contained: it explains purpose, side effects, permanence, prerequisites (secret key), and the required user confirmation workflow. This fully equips an agent to safely invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% coverage for both parameters (id as UUID, confirm with explanation of behavior when omitted). The description reinforces the confirm parameter's meaning but does not add significant new technical detail beyond the schema, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Delete a tag') and the resource, and explains the cascading effect on articles, which distinguishes it from sibling tools like delete_article. It unambiguously identifies 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?
The description provides essential usage instructions: ask the user before calling, pass confirm only after agreement, and notes the required secret key scope. It also implicitly differentiates from delete_article by stating 'No article is deleted,' but does not explicitly compare with alternatives like update_tag.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds valuable context: "No API key required" and that it is "Generated from the published OpenAPI specification." It does not detail the return format, but for a read-only docs tool with annotations, this is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three well-structured sentences: the first states the core purpose, the second adds authoritative sourcing, and the third lists the sections. It is information-dense with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only documentation tool with one optional parameter fully described by the schema and annotations, the description covers all necessary context. It even mentions that no API key is required, which is relevant for an agent deciding whether to call the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema's parameter description already covers the sole 'section' parameter fully, including default and 'all' value. The description reinforces this by listing all enum values, which is helpful but not entirely new information. Baseline for 100% coverage is 3, and the small addition justifies a 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb+resource combination: "Read the Writavo Content API reference." It clearly distinguishes this from sibling tools, which all operate on specific resources (articles, categories, etc.). It also lists the covered sections, further specifying what content the tool provides.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly explains what the tool does and notes that "No API key required," which is useful context. However, it does not explicitly state when to use it over alternative tools or mention exclusions. The context is clear but lacks explicit guidance about alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds meaningful behavior beyond the annotations: it explains the alphabetical ordering, the cross-cutting relationship between tags and articles, the read-only guarantee, and the required auth scope. These are non-obvious details that are not conveyed by readOnlyHint or destructiveHint alone. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core verb and resource, then adds ordering, a domain note, safety, and auth in a compact way. It is short and every sentence contributes value, despite a minor redundancy between 'Read only' and 'Nothing is changed.' Overall, it is concise and well-structured.
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 listing tool, the description is complete: it gives the scope, ordering, auth requirement, and semantic context. Pagination and fields are fully covered by the input schema. There is no output schema, but the description plus schema provide sufficient information for an agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema descriptions cover 100% of the parameters, so the baseline is 3. The description does not add per-parameter semantics, though the 'alphabetically' note informs the default ordering relevant to pagination. It does not compensate beyond the schema, so a baseline score is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists tags, with the specific scope 'Every tag on the Site' and the order 'alphabetically'. It distinguishes from sibling list tools by resource category and explicitly states the read-only nature, making the purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool: whenever you need to list all tags. It adds a prerequisite ('Needs a key carrying the taxonomy:read scope') but does not explicitly mention alternatives or exclusions, e.g., that to get a single tag you should use get_tag. This is slightly below the highest standard because the tool name and scope make alternatives obvious but not explicitly stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes beyond annotations by disclosing concrete behavioral details: the status change, cron timing, public visibility on the live site, and the confirmation requirement. It also clarifies independence from the AI pipeline. This provides substantial context that annotations alone do not 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?
The description is concise and front-loaded with the primary action. Each sentence adds necessary information: action, status change, cron behavior, public warning, confirmation guard, and auth requirement. No fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is complete for a scheduling tool: it covers the action, timing, visibility consequence, user consent, and auth prerequisites. With no output schema or additional complexities, the description provides all essential context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description does not add much beyond the schema for parameters; it reiterates the confirm requirement but does not explain id or scheduled_publish_at beyond what the schema already describes. The auth scope note is not a parameter semantic.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: scheduling an article by moving it to 'status: scheduled' and recording the go-live time. It distinguishes the deferred publication via cron from immediate publishing by explicitly noting the cron behavior and the public visibility implication.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use the tool (for scheduling future publication) and includes a strong prerequisite: asking the user and passing confirm: true only after agreement. It also states the required auth scope. However, it does not explicitly mention alternatives like publish_article or cancel_article_schedule, so it falls short of a full 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds substantial behavioral context beyond the annotations: the article returns to 'status: draft', the URL returns 404 after cache purge, changes content on the customer's site, and requires a specific secret key scope. This aligns with readOnlyHint=false and destructiveHint=false, and provides operational details that annotations do not disclose.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded: it starts with the core action, then expands on the state change, external effects, and auth. Each of the five sentences adds distinct value, with no redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and no output schema, the description covers all necessary context: the action, the resulting draft state, the URL 404 behavior, the external site impact, the separation from publishing, and the required auth scope. It is complete for an agent to understand and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema describes the only parameter 'id' as 'A UUID', which is minimal. The description does not explicitly explain that 'id' is the article ID, though it is implied by the tool name and description. Since schema_description_coverage is 100% (the parameter has a description), the baseline is 3; the description adds no further parameter-specific semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Unpublish an article. Takes the article off the web and returns it to `status: draft`.' This uses a specific verb and resource, and explicitly distinguishes it from publishing ('Nothing becomes public: publishing is always a separate call') and deletion ('returns it to draft' implies not deleting). It is easily differentiated from sibling tools like publish_article and delete_article.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool: to take an article off the web and revert it to draft. It also clarifies that making it public again is a separate call (publish_article). However, it does not explicitly contrast with delete_article for permanent removal, which would make the guidance more complete. The auth requirement ('Needs a secret key...') further guides usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses several behavioral traits beyond annotations: side effects on the customer's Site, slug collision returning 409 rather than silently appending, and the auth scope requirement. These details are not evident from the structural annotations and add significant value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Each of the five sentences adds a distinct, non-redundant fact: purpose, slug behavior, content mutation, publishing separation, and auth. The description is front-loaded with the core purpose and stays compact.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple 2-parameter create operation, the description covers purpose, side effects, error behavior, auth, and publication boundary. It lacks an explicit return-value description, but given no output schema and standard API conventions, this is a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description enriches slug semantics by explaining uniqueness and conflict behavior, complementing the schema's note that slug is derived from name. It does not, however, describe the `name` parameter beyond what the tool name implies, so while it compensates for the 50% schema coverage, it doesn't fully cover both parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Create a category,' which is a specific verb plus resource. It clearly distinguishes from sibling tools like create_article or create_tag by naming the resource, and from update_category/delete_category by the action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: it states that publishing is a separate call ('Nothing becomes public: publishing is always a separate call') and that a secret key with taxonomy:write scope is required. However, it does not explicitly name alternative tools or when to use them, so it stops short of full when/when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses auth requirements ('Needs a secret key (wv_sk_) carrying the articles:write scope'), clarifies side effects ('Changes content on the customer's Site'), and states non-publishing behavior ('Nothing becomes public'). It adds nuance about null vs omission, which is beyond annotations. No contradiction with annotations (readOnly=false, openWorld=true, idempotent=true, destructive=false).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Five short sentences, each carrying distinct information: operation, partial-update semantics, null handling, site impact, publishing separation, and auth. No redundant phrases; front-loaded with the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 18 parameters, the schema handles individual param documentation. The description covers the high-level contract: partial update, auth, non-publication, and site-side effects. It does not mention return value or error cases, but no output schema exists and these are not critical for an update tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema coverage, each parameter is already documented. The description adds a global rule: 'Send null to clear a nullable field; omit it to leave it alone,' which applies to all nullable fields and clarifies the schema's repetitive 'Send null to clear it.' This is meaningful added context that simplifies parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Update an article' (specific verb+resource), and clarifies 'partial update' to distinguish from full replacement. It also states 'Nothing becomes public: publishing is always a separate call,' which differentiates from sibling publish_article.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It doesn't explicitly name alternatives, but the phrase 'publishing is always a separate call' tells the agent when not to use this tool (i.e., for publishing, use publish_article). The partial update semantics imply use for modifications rather than creation or deletion. It also specifies the required auth scope, giving a precondition.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds rich context beyond annotations: explains status change to draft, clears scheduled_publish_at, content untouched, no-op behavior, and auth requirements. No contradiction with annotations, which only indicate false read-only and destructive 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?
Four sentences, each adding essential information: action, state changes, no-op behavior, and auth. No filler or redundancy; front-loaded with the primary purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and no output schema, the description covers all critical aspects: behavior, side effects, prerequisites, and edge cases. Sufficient for an agent to correctly invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has full coverage (id is 'A UUID'), but description adds clarity that the id refers to an article and is used to target the scheduled publish. This goes beyond the schema's minimal description, providing useful semantic context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool cancels a scheduled publish, with specific actions on article status and scheduled timestamp. It distinguishes from siblings by noting publishing is a separate call, differentiating from publish_article and schedule_article.
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 context of when to use (on scheduled articles) and no-op for non-scheduled. Mentions publishing is a separate call, implying alternatives, but does not explicitly name sibling tools or list when-not-to-use scenarios beyond the no-op case.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds substantial behavioral detail beyond annotations: is_ai_generated defaults to true and drives disclosure copy, changes are not public until a separate publish step, and a specific secret key scope is required. These details align with the annotations (readOnlyHint false, openWorldHint true) without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise yet information-dense. Every sentence serves a clear purpose: stating the operation, explaining the key flag, clarifying the mutation and non-publication behavior, and specifying the auth requirement. No redundant content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a create operation with no output schema, the description covers all critical operational aspects: purpose, the most nuanced parameter (is_ai_generated), side effects on the customer's Site, the separation of publishing, and required credentials. An agent has enough to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has only 40% parameter description coverage. The description compensates by deeply explaining is_ai_generated (persona vs real person, default true, disclosure implications). Bio and avatar_url already have schema descriptions, and name/is_default are self-explanatory, so the description adds value where needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear, specific verb+resource: 'Create an author.' It also differentiates from sibling create tools (e.g., create_article, create_category) by naming the resource and noting it changes content on the customer's Site, confirming it is a write operation for authors.
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 context for when to set is_ai_generated, states that publishing is a separate call, and specifies the required auth scope (wv_sk_ with authors:write). However, it does not explicitly contrast with update_author or delete_author to say 'use this when creating, not updating.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already indicate destructive=true and readOnly=false, but the description adds substantial behavioral context beyond these flags. It discloses that there is no trash or undo, that articles remain published with a null category_id, and that a secret key with taxonomy:write scope is required. It also explains the confirm parameter's role in preventing accidental deletion, which is critical behavioral information.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise yet comprehensive. Every sentence contributes unique information: the action, the effect on articles, the permanence, the confirmation requirement, and the permission scope. There is no redundant or filler text, and the most critical warning (permanent, no undo) is placed prominently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is exceptionally complete for a destructive tool given its annotations and schema. It covers all necessary context: impact on related content, permanence, confirmation flow, and security requirements. Although there is no output schema, the description explains the behavior when called without confirmation, which provides sufficient return-value context for a delete 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_description_coverage, the schema already documents both parameters. The description adds value by explaining that calling without confirm=true returns a description of what would happen and changes nothing, which clarifies the parameter's purpose and the tool's dry-run behavior. This goes beyond the schema alone, justifying a score above the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Delete a category' with a specific verb and resource. It goes beyond a repitition of the title by explaining the distinct impact on articles: they are not deleted, their category_id becomes null, and they remain published. This effectively distinguishes it from similar deletion tools for articles, tags, or authors.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context by stating that the action is permanent, requires user confirmation, and that removing a category never removes content. It does not explicitly name alternative tools, but it clearly defines when this tool should be used (final deletion after user agreement) versus a non-destructive operation. The explicit instruction to ask the user before calling is a strong usage guideline.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the destructiveHint annotation, the description emphasizes PERMANENT deletion, no trash/undo, and the requirement of a secret key with media:write scope. This adds critical behavioral context about irreversibility and authentication that annotations alone do not 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 sentences deliver the core action, permanence warning, and consent requirement without redundancy. Every sentence earns its place, front-loading the purpose and critical safety 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?
The description covers the destructive nature, user-consent workflow, required key/scope, and fallback behavior without confirmation. Given the simple two-parameter schema and no output schema, this is fully sufficient for an agent to invoke the tool correctly and safely.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Both parameters are fully documented in the schema, including the confirm parameter's conditional behavior. The description's mention of 'confirm: true' reinforces the schema but does not add new semantic information beyond what the schema already provides. Schema coverage is 100%, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource ('Delete a media asset') and clarifies exactly what deletion entails: removing the catalog row and stored bytes. This clearly distinguishes it from sibling delete tools for other entities (e.g., delete_article, delete_category).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly instructs to ask the user before calling and to pass confirm:true only after agreement, and describes what happens if confirm is omitted. This gives unambiguous, actionable usage guidance. There are no competing media-deletion tools among siblings, so no alternative is needed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, destructiveHint=false, and idempotent, but the description adds valuable context: it states 'Read only. Nothing is changed' (reinforcing but slightly redundant) and reveals an authentication requirement: 'Needs a secret key (wv_sk_) carrying the meta:read scope.' It also hints at response semantics by explaining the balance will 'move' after a run. This exceeds the annotation baseline.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured: purpose (first sentence), clarification (second), usage guidance (third), safety note and auth (final sentences). Every sentence carries meaningful information, and the overall length is appropriate for the tool's simplicity. No filler or repetition beyond the minor 'Read only' / 'Nothing is changed' 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?
The description fully covers the tool's purpose, usage timing, safety (read-only), and auth scope. Since there is no output schema, the description compensates by summarizing what the response contains ('what your plan allows... what you can still spend'). For a parameterless read-only tool, this is complete and actionable context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the schema shows no properties, so schema coverage is trivially 100%. With no parameters to document, the description cannot add parameter-level detail, but it does convey the data scope (plan limits, usage, balances) which is what the tool returns. The baseline for 0 params is 4, and the description meets it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Read plan limits, usage and balances.' It further clarifies the meaning with 'What your plan allows, what you have used in the current period, and what you can still spend,' which clearly differentiates it from sibling tools like get_site_info or list_articles. The purpose is explicit and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage context: 'Read this before a pipeline run if you want to fail fast rather than handle a 402, and read it after a run to see the balance move.' This tells the agent when to invoke the tool and why, offering clear scenario-based guidance. Although no alternative tool is named, the unique purpose makes the usage direction highly actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, it discloses the real-world impact: 'publicly visible on the customer's own live site, where search engines and readers will see it' and the confirm parameter's dry-run behavior. It also states the required secret key scope, adding meaningful context about auth.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Every sentence carries essential information: the action, the immediate effect, the public visibility warning, the user-confirmation requirement, and the auth scope. It is front-loaded with the main verb and efficiently expanded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose, effect, safety confirmation, auth prerequisites, and the dry-run behavior, making it self-contained. Given the simple 2-param schema and no output schema, this is fully complete for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides full coverage for id and confirm. The description adds extra meaning by explaining that omitting confirm 'returns a description of what would happen and changes nothing', which clarifies the parameter's gatekeeping role.
Input schemas describe structure but not intent. Descriptions should explain non-obvious 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 'Publish an article' and immediately specifies 'Makes the article public immediately, at `status: published`', giving a specific verb, resource, and outcome. This clearly distinguishes it from siblings like unpublish_article and schedule_article.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It states when to use (for immediate public visibility) and provides a critical safety guideline: 'Ask the user before calling this, and pass confirm: true only once they have agreed.' However, it does not explicitly mention alternatives like schedule_article for delayed publishing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds significant behavioral context beyond annotations: it warns that slug changes break links with no redirect, states that content changes on the customer's site but nothing becomes public until publishing, and requires a secret key with taxonomy:write scope. These disclosures go beyond the simple annotation flags and inform the agent of important side effects and prerequisites.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is four sentences with no fluff. It front-loads the core purpose and then packs critical warnings into compact, meaningful statements. 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 lacking an output schema, the description covers essential context: the tool updates categories, has link-breaking consequences, does not publish, and requires auth credentials. Combined with the annotations and schema, it provides a complete picture for an agent to select and execute the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers id and if_match with descriptions but leaves name and slug undocumented (50% coverage). The description explains that renaming is safe and that changing slug affects the URL, providing meaning for otherwise opaque fields. While it doesn't discuss if_match, the schema already covers that, so the description compensates for the coverage gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update a category' and elaborates on specific category behaviors like renaming and slug changes affecting the archive URL, distinguishing it from sibling update tools for other resources. The verb and resource are explicit and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides contextual guidance by warning about slug changes and broken links, and noting that publishing is a separate call. It does not explicitly list alternatives, but the context clearly indicates when to use this tool versus other category operations like create or delete.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds meaningful behavioral context beyond annotations: changing site content, non-publication, immutable bytes, and required secret key with media:write scope. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise, front-loaded single paragraph with each sentence adding distinct information: editability, immutability, publishing separation, and auth requirements.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description covers purpose, constraints, auth, and alternatives, making the tool's behavior fully understandable for selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers all parameters (id, alt_text, if_match) with detailed descriptions, so description adds little beyond reinforcing that only alt_text is editable. Baseline 3 applies due to high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool updates a media asset and specifically limits editing to alt_text. This distinguishes it from siblings like upload_media (for creating/replacing) and delete_media (for removal).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says bytes are immutable and to replace an image, upload a new one and repoint references, pointing to a different workflow. Also states publishing is a separate call, guiding when not to use this tool for publication.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a write operation (readOnlyHint=false). The description adds value by explicitly stating it 'Changes content on the customer's Site', discloses the multi-step process (reserve, transfer, register), visibility behavior (nothing becomes public until attached), and auth requirements (secret key with media:write scope). No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact: four sentences, each providing distinct value—purpose, input options, multi-step behavior, and auth/visibility notes. It is front-loaded with the core action and avoids redundant fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has moderate complexity (3-step process, 6 optional params, no output schema). The description covers the essential operational flow, auth, return value, and a key caveat (visibility). Given the annotations, it is sufficiently complete for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds meaningful context beyond the schema by clarifying the either/or relationship between file_path and source_url, and by framing the output as a usable URL for featured_image_url. This helps the agent understand parameter choices.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb and resource ('Upload an image to the Site's media library'), the outcome (returns an asset with a usable URL), and how it fits into a larger workflow (featured_image_url). It is distinct from siblings like list_media or update_media, which handle other media operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives context on when to use (to obtain a URL for an article's featured image) and how to specify input (local file path or public source_url). It doesn't explicitly mention alternatives or exclusions, but the absence of other upload tools and the clear use case make the guidance effective.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behaviors beyond the annotations: it is 'exempt from the write rate limit', 'touches no content', and returns the key kind and scopes. It also explicitly states 'Read only. Nothing is changed', reinforcing the readOnly and non-destructive hints without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the core purpose, followed by efficiently worded details on return value, use cases, and rate-limit implications. Every sentence contributes meaningful information 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?
For a parameterless tool with no output schema, the description fully covers what the tool does, what it returns, when to use it, and its side-effect-free nature. No additional context is needed for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With zero parameters and 100% schema coverage (vacuously), the baseline is 4. The description appropriately focuses on behavior rather than parameter details since none exist, making this score fitting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious 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 'Verify a key', a specific verb+resource pairing, and elaborates that it returns the key type and scopes. This distinguishes it clearly from sibling content-management tools, leaving no ambiguity about 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?
The description gives explicit use cases: 'confirm credentials during setup' and 'as a liveness probe', plus notes it is the cheapest authenticated call. It does not name alternatives or state when not to use it, but the context is clear enough to guide an agent effectively.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds substantial behavioral context beyond the annotations: permanent deletion, removal of tag assignments, 404 impact after cache purge, no trash/undo, and the confirm flag's dry-run behavior. It also explains the if_match concurrency control's effect. Annotations already indicate destructive=True, but the description enriches this with specific scenarios and consequences.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Every sentence carries critical information: the action, permanence, side effects, irreversibility, consent requirement, and authentication. It is direct and front-loaded with the most important warning 'Permanent', followed by concrete consequences. No redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive tool with no output schema, the description covers all necessary invocation context: what gets deleted, downstream effects, irreversibility, user consent workflow, authentication scope, and concurrency handling. It fully prepares the agent to use the tool correctly and safely.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions cover all three parameters, so baseline is 3. The description adds extra meaning for 'confirm' by explaining that omitting it results in a preview instead of deletion, and for 'if_match' by describing optimistic concurrency. This goes beyond the schema's basic descriptions, earning a 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Delete') and resource ('article'), clearly distinguishing from sibling tools like update_article or publish_article. It immediately states the destructive nature, leaving no ambiguity about 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 Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs to ask the user before calling and to pass confirm:true only after agreement. Also specifies the required API key scope (articles:write), providing clear operational prerequisites. This goes beyond simple context and gives actionable 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.

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:

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

Score Badge

Copy to your README.md:

[![writavo-mcp-server MCP server](https://glama.ai/mcp/servers/SparkleOfficial/writavo-mcp-server/badges/score.svg)](https://glama.ai/mcp/servers/SparkleOfficial/writavo-mcp-server)

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/SparkleOfficial/writavo-mcp-server'

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