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

No annotations provided, so description carries full burden. It discloses overwriting, live validation, invalid not saved, first becomes default, yandexHost normalization, hiddenTags exclusion. This is thorough, though could mention side effects like token rotation.

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

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

Description is efficient, front-loading purpose and key behaviors. However, it's a single dense paragraph; breaking into sentences would improve readability. No wasted words.

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

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

Given 8 parameters and no output schema, description covers validation, default behavior, and param nuances well. But it lacks details on return value or confirmation message, which would be helpful for an agent invoking the tool.

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

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

Schema description coverage is 100%, so baseline is 3. Description adds value by explaining yandexHost accepts URL or host_id, hiddenTags meaning, and token optionality for read-only. This enhances understanding beyond the schema.

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

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

Description clearly states 'Add/update a site in the config', specifies verb and resource, and distinguishes from sibling tools by explaining overwrite, validation, and default behavior. No other sibling tool adds sites.

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

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

Description provides clear context for when to use (to add or update a site), including validation rules and token requirement. However, it does not explicitly mention when not to use or list alternatives, though sibling tools are mostly unrelated.

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

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

With no annotations provided, the description fully discloses behavioral traits: it is heavy, requires 'saveToFile', notes a vulnerability ('PUT-готч') regarding cover images, and explains output format (summary in chat, full list to file). This is comprehensive and goes beyond minimal expectations.

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

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

The description is a single, somewhat dense paragraph that efficiently conveys purpose and details. It is front-loaded with the main action, but could benefit from minor restructuring for clarity.

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

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

Given no output schema and three parameters, the description adequately covers what the tool does and returns (summary and file). It is sufficiently complete for the tool's complexity.

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

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

Schema coverage is low (33%), but the description adds meaning to all parameters: it explains 'minWords' as a threshold for short articles, and 'saveToFile' for output file. 'site' is not detailed but its role is implied. This compensates for the schema gaps.

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

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

The description clearly states that the tool performs a content audit on full article bodies, listing specific checks (FAQ section, length, title, image, internal links). It distinguishes itself from sibling tools like 'audit_orphans' by its specific scope and focus on full content.

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

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

The description provides guidance on when to use the tool by noting that it is heavy and requires the 'saveToFile' parameter. It implies that this is for full content audits, but does not explicitly exclude other scenarios or mention alternatives.

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

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

With no annotations, the description effectively conveys behavioral traits: finds orphans using thematic scoring, excludes hidden articles, and optionally saves results to file for large sites. However, it does not specify whether the tool modifies data or just reports.

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

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

Description is a single paragraph with essential information: purpose, scoring, defaults, and options. No wasted words, but could be more structured for easier reading.

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

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

Covers the main functionality including scoring and hidden article exclusion, but lacks clarity on output format (list of orphans with donor articles) and whether the tool executes link additions or only suggests them. No output schema exacerbates this gap.

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

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

Schema coverage is 33% (only 'count' has a description). The description adds context for 'count' (affects graph) and 'saveToFile' (for large sites), but does not explain the 'site' parameter. This partially compensates for schema gaps.

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

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

Description clearly states tool audits orphan articles (those with no 'Also read' references) and details the scoring method. It distinguishes itself from siblings like 'audit_content' and 'suggest_links' by focusing specifically on orphans and donor suggestions.

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

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

No explicit guidance on when to use this tool versus alternatives like 'suggest_links' or 'audit_content'. Description implies usage for improving internal linking but does not provide context for when to choose this tool.

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

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

Despite no annotations, the description discloses important behavioral traits: the operation is irreversible (confirm), permission checks (403 for non-owner), and that IndexNow is not notified, leaving the URL in the index. This goes beyond basic deletion.

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

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

The description is concise and front-loaded with a warning emoji and verb. It conveys key information in a few sentences without redundancy.

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

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

Given no annotations and no output schema, the description covers the essential aspects: purpose, required parameter (confirm), error handling, and side effect (IndexNow). It lacks return value explanation but that is acceptable without an output schema.

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

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

Schema coverage is only 25% (only confirm has a description). The description explains that slug is used for resolution and that confirm must be true, but does not clarify id or site parameters. This leaves ambiguity.

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

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

The description clearly states the operation ('Удалить статью') and specifies the HTTP method and resolution by slug. It distinguishes from siblings like update_article and publish_article.

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

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

The description includes critical usage conditions: requires confirm:true, error codes for 404 and 403, and notes that admin accounts can delete others' articles. However, it does not explicitly compare to sibling tools for when to use.

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

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

Without annotations, the description carries the full burden. It mentions it's a public GET endpoint and that id is needed for update/delete, but does not discuss rate limits, authentication details, or side effects beyond saving to file. Adequate but not exhaustive.

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

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

The description is a single, information-dense sentence that front-loads the main purpose and lists key fields. It is concise with no wasted words, though it could benefit from slight structuring for readability.

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

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

Given no output schema, the description lists many returned fields but not all. It mentions dates but not their format. The site parameter is missing. The saveToFile hint for large articles adds practical guidance. Overall, moderately complete but with a notable gap.

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

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

The description clarifies the slug parameter (used as identifier) and the saveToFile parameter (path to write JSON, returning summary in chat). However, the site parameter is not explained, and schema description coverage is only 33%. The description partially compensates for low schema coverage but misses one parameter.

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

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

The description clearly states that the tool retrieves the full article by slug, listing the fields returned (title, content, excerpt, etc.) and distinguishing it from sibling tools like delete_article and update_article by mentioning that the returned id is needed for those operations.

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

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

The description implies usage for fetching full article content by slug, but does not explicitly state when not to use it or offer alternatives. Context from sibling tool names like list_articles suggests when to use those, but the description itself lacks direct guidance.

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

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

No annotations provided, so the description must cover all behavioral traits. It discloses that the tool returns a list without content, includes hidden articles marked as hidden:true, and explains client-side filtering and lack of server pagination. However, it does not explicitly state read-only or safety implications.

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

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

The description is a single paragraph that efficiently conveys purpose, filtering, and limitations. It is front-loaded with the main purpose and avoids redundancy, though it could be slightly more structured.

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

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

Given no output schema or annotations, the description adequately covers what the tool returns, how filtering works, pagination behavior, and the saveToFile feature. It lacks discussion of error handling or authentication, but for a simple list tool this is acceptable.

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

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

The schema has 50% description coverage; the description adds value for 'tag' and 'query' by explaining they are case-insensitive filters and substring matching. It also clarifies the behavior of 'saveToFile' (writes full JSON to disk, returns summary in chat). The 'site' parameter is already described in the schema.

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

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

The description clearly identifies the tool as a lightweight list of site articles, specifying the endpoint, returned fields, and distinguishing it from other tools like 'get_article' by noting the exclusion of content and updatedAt.

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

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

The description provides context for when to use filters (tag, query) and recommends using saveToFile for large sites. However, it does not explicitly compare with sibling tools or state when not to use this tool.

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

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

No annotations are provided, so the description carries full burden. It explains the scoring process and output verdicts but does not explicitly state side effects or whether the tool is read-only. The instruction to write a file from another tool's response adds some clarity.

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

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

The description is concise, covering key aspects in a few sentences. No redundant information, though it could be slightly more structured for easier parsing.

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

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

Given no output schema and lack of annotations, the description covers input format, preprocessing, and output logic. However, it omits details on the scoring algorithm, behavior of site and saveToFile parameters, and any prerequisites.

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

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

Schema description coverage is 50%. The description adds context for queries and queriesFile (e.g., field names, source), but ignores site and saveToFile parameters entirely. It partially compensates for the gap.

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

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

The description clearly states it matches search queries with site articles to produce boost or new recommendations. It distinguishes itself from sibling tools like audit_content or list_articles by focusing on query-article matching.

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

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

Provides explicit preprocessing instructions (filter positions 8-30, format queries from another tool). However, it does not mention when not to use this tool or offer comparisons to sibling tools.

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

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

Discloses many behaviors: validation orchestration, slug generation (transliteration + date + collision counter), cover image selection logic, IndexNow fire-and-forget, and contentFile alternative. With no annotations, description carries full burden and does well, though missing potential constraints like rate limits.

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

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

Concise paragraph with bullet-like structure using emoji and line breaks. Front-loaded with the main action. Slightly dense but every sentence adds value.

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

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

Covers all major aspects: validation, title/content relationship, slug generation, cover image, IndexNow, large content. No output schema, but description explains how to get the slug from response. Adequate for the tool's complexity.

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

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

Adds meaning beyond schema for title (optional if content starts with heading), content (Markdown), contentFile (path to .md), skipValidation (bypass errors). 'site' and 'tags' are not elaborated but schema covers tags. Baseline 3 for 50% coverage, description earns extra point.

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

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

The description clearly states the verb 'Опубликовать' (publish) and resource 'НОВУЮ статью' (new article), and includes the HTTP method POST. It distinguishes from siblings like update_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.

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

Provides explicit guidance on running validate_article first, handling errors and warnings, title and content alternatives, slug generation, cover image logic, and IndexNow. Does not explicitly state when not to use it, but context is clear.

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

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

Discloses that it performs a live lightweight GET probe to each site, revealing its non-destructive read-only behavior. No annotations provided, so description fully covers these traits.

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

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

Two sentences with no fluff; first sentence describes the function, second gives usage guidance. Perfectly concise and front-loaded.

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

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

For a zero-parameter tool with no output schema and no annotations, the description fully explains purpose, behavior, and recommended usage context. No gaps.

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

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

No parameters in schema; description adds meaning by explaining the tool's action without needing any input, going beyond the empty schema.

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

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

Description clearly states it checks config/authorization status via live probes and provides connection instructions. Distinguishes from sibling tools like add_site or audit_content by being a diagnostic first-step tool.

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

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

Explicitly says 'Call first on access errors or if user doesn't know where to start', giving clear when-to-use guidance.

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

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

No annotations are provided, so the description carries the full burden. It discloses the scoring formula (score>0, tags×3 + words×1), that the list is symmetric, and that it returns markdown snippets. However, it does not mention whether the tool is read-only, any rate limits, or authentication requirements. The description is adequate but could be more explicit about behavioral aspects.

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

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

The description is concise, consisting of two sentences that pack significant information. It is front-loaded with the main purpose and follows with details on scoring and usage. No redundant information.

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

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

Given the complexity of the tool, no output schema, and 4 parameters with low schema coverage, the description provides a solid understanding of the tool's functionality, scoring, and dual usage. It lacks details on return format and error handling, but overall it is sufficient for an agent to select and invoke the tool.

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

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

Schema description coverage is low (25%), with only topN having a description. The tool description does not add meaning for the parameters slug, site, or saveToFile beyond what is in the schema. It mentions slug in the context of snippet formatting but not as a parameter. The description compensates partially by explaining the overall purpose but not individual parameters.

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

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

The description clearly states the tool's purpose: interlinking for one article, with scoring and markdown snippets. It specifies the verb 'перелинковка' (interlinking), resource 'одна статья' (one article), and distinguishes from siblings like audit_orphans by focusing on thematic closeness.

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

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

The description provides usage context: the tool is used both to find target articles (to link from the current article) and donor articles (to add a link to the current article into their bodies). It also references update_article for adding links. However, it does not explicitly state when not to use it or provide alternative tools.

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

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

With no annotations, the description carries full burden and reveals critical side effects: PUT overwrites excerpt/coverImage/authorName, cover image loss detection blocked unless skipValidation, slug stability, tag behavior, and 403 ambiguity. This is highly transparent.

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

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

The description is efficiently structured with main action first, then key warnings, but is somewhat long. Every sentence adds value, though some could be more concise.

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

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

Given the complexity (8 params, no output schema, no annotations), the description covers error cases, side effects, and parameter behaviors thoroughly, making it complete for an agent to use correctly.

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

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

Schema coverage is low (13%), but the description adds meaning for slug resolution, content field behavior, skipValidation, and tags. However, parameters like site, title, and contentFile are not explained, leaving some gaps.

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

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

The description clearly states the tool updates an article, explains resolution via slug and PUT endpoint, and differentiates from publish_article by noting it is not an upsert. This distinguishes it from sibling tools.

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

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

Explicitly states when not to use (no article exists) and provides an alternative (publish_article). Also describes behavior for tags and error ambiguity.

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

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

With no annotations, the description covers key behaviors: endpoint, multipart upload, format constraints, size limit, return value, and cover insertion procedure. Missing details like authentication or rate limits, but adequate for basic use.

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

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

A single, efficient sentence that front-loads the main action and includes all critical information without redundancy.

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

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

Given no output schema and no annotations, the description covers most relevant aspects: endpoint, constraints, return, and integration note. The optional 'site' parameter is left unaddressed, but overall it's sufficiently complete for this tool's complexity.

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

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

The schema has 50% coverage (only filePath described). The description adds meaning: multipart context, allowed formats, size, and cover instruction—compensating for the schema gap. The 'site' parameter remains unexplained, but overall adds value.

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

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

The description clearly states the action 'upload article image' with the endpoint, allowed formats, and size limit. It distinguishes itself by referencing a gotcha with update_article, indicating integration context.

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

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

The description provides clear instructions on usage, including how to make the image the cover and the gotcha about update_article. However, it does not explicitly state when not to use this tool or alternatives.

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

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

With no annotations, the description carries the full burden. It discloses the tool is a read-only linter (offline, no network) and lists checks and return facts. However, it does not explicitly state that it has no side effects or whether it requires specific permissions, leaving some ambiguity.

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

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

The description is a single dense paragraph that packs many checks into a few sentences. It is not overly long but could be better structured with bullet points or clearer separation of errors/warnings and facts.

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

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

Given the complexity (5 parameters, no annotations, no output schema), the description explains what the tool does and returns. However, it does not guide on parameter usage (e.g., content vs contentFile) or provide enough context for an agent to know how to invoke it correctly without additional knowledge.

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

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

Schema description coverage is only 20% (only 'site' has a description). The tool description does not provide any additional meaning for the parameters (title, content, contentFile, tags) beyond what the schema provides. For a low-coverage schema, the description should compensate but does not.

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

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

The description clearly states it is an offline linter for articles, listing specific errors (empty content, missing title/H1, double H1) and warnings (title length, paragraph length, missing FAQ section, etc.), and that it returns facts. This distinguishes it from siblings like publish_article and update_article which automatically run this validation.

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

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

The description mentions it is used offline and is automatically run within publish_article/update_article, implying it can be used manually for validation before publishing. However, it does not explicitly state when not to use it or compare to alternatives like audit_content, which could be similar.

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