Misar.Blog MCP Server

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

Annotations already declare idempotentHint: true, and the description reinforces this with 'Safe to repeat' and clarifies that a duplicate call changes nothing. It adds context beyond annotations by stating that the action is public as the account holder and requires an API key. However, it doesn't detail the exact response format or error handling, though no output schema exists to require that.

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 tightly written, with two short paragraphs that convey all necessary information without redundancy. Each sentence contributes to usage or behavior, and it is front-loaded with the core action. No fluff or repetition of schema details.

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 tool's simplicity (2 params, 100% schema coverage, annotations present, no output schema), the description is fully complete. It covers purpose, when to use, safety (idempotency), requirements (API key), and related tools, leaving no gaps for an agent to make an incorrect call.

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 input schema covers both parameters with 100% descriptive coverage, including enum meanings for 'type' and the article_id source. The description adds value by explaining that only one type can be added per call ('react twice for two types'), which is a practical nuance not present in the schema. This slightly exceeds the baseline for full schema coverage.

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: 'Record one reaction' on an article, specifying the three possible types (like, clap, bookmark) and that it acts from the authenticated account. It distinguishes from siblings by explicitly mentioning remove_reaction and get_reactions as complementary tools, leaving no ambiguity about its role.

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 explicit usage rules: only call when the user has explicitly requested, not proactively. It also explains idempotency (safe to repeat) and offers clear alternatives: use remove_reaction to undo and get_reactions to see totals. This fully answers when and when not to use the tool.

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

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

The description adds significant behavioral context beyond the annotations: it states that adding does not change publication status or URL, that inserting at a position shifts later articles down, and that it requires an API key. The annotations already indicate readOnlyHint=false, idempotentHint=true, and destructiveHint=false, and the description aligns with these. It could mention idempotency explicitly (e.g., what happens if called twice with the same position), but the existing disclosure is strong.

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 well-structured: a clear first sentence stating the action, followed by short paragraphs covering prerequisites, identification method, position behavior, and error conditions. Every sentence adds value, and the information is front-loaded with the core purpose. No fluff or 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 the tool's moderate complexity (3 params, no output schema, no nested objects), the description is complete: it covers prerequisites, identification, position behavior, side effects, and error conditions. The annotations provide safety hints (idempotent, non-destructive). It could mention the return value or success/failure response format, but with no output schema, the description's coverage is strong. A 4 is appropriate.

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 100% description coverage, so the baseline is 3. The description adds value by reinforcing the slug-based identification ('Not its title or id') and explaining the position semantics ('Omit to append at the end. Inserting shifts later articles down.'). It also clarifies the source of each slug (get_series, list_my_articles), which goes beyond the schema. This earns a 4.

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: 'Place an existing article into an existing series, optionally at a specific position.' It specifies the verb (place/add), the resource (article into series), and the key constraint (both must already exist). It distinguishes from siblings like create_series (which creates a series) and update_article (which modifies an article), making the purpose unambiguous.

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

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

The description provides explicit usage guidance: it states when to use (adding an existing article to an existing series), what not to do (it creates neither), and how to identify entities (by slug, not id, with references to get_series and article tools). It also explains the optional position parameter and the error condition for unknown slugs, giving clear context for when this tool is appropriate versus 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?

Adds valuable behavioral details beyond the annotations: non-idempotency ("Each call creates a NEW draft"), auth requirement ("Requires an API key"), visibility guarantee ("Nothing becomes visible to readers"), and return value ("Returns the draft with an editor_url"). 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.

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

The description is well-structured and concise: three short segments covering purpose, usage guidance, and important caveats. Every sentence provides distinct value with no redundancy or filler.

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 simple 3-param tool with no output schema, the description is thorough: it covers purpose, use cases, side effects, auth, return format, and lifecycle. It compensates well for the absence of an output schema by mentioning the editor_url return.

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. The description does not add parameter-specific meaning beyond what the schema already provides; it focuses on tool behavior rather than param details.

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 function: "Save an article as an unpublished draft." It uses a specific verb and resource, and explicitly distinguishes itself from siblings by contrasting with publish_article and mentioning update_article for later edits.

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 when to use: "use this whenever the work still needs review, and publish_article only when it should go live." Also names update_article as the alternative for subsequent editing, giving clear when/when-not and 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?

Beyond annotations, the description discloses non-idempotency ('each call creates a NEW series'), public visibility of the series URL, requirement of an API key, and the return value including the slug needed by add_to_series.

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?

Three sentences, each serving a distinct purpose: core function, usage guidance, and behavioral/return details. No redundancy or filler, with the most important information 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?

Despite no output schema, the description compensates by explaining the return value (slug), side effects (public URL), and the recommended sequence with get_series and add_to_series. This is complete for a simple creation 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%, with both title and description already documented. The description adds little new parameter-level meaning beyond what the schema provides, so baseline 3 is appropriate.

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 'Create a new, empty series' with a specific verb and resource, and clarifies that it does not move articles into the series, distinguishing it from the sibling tool add_to_series.

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 explicitly instructs to call get_series first to avoid duplicates and to follow up with add_to_series for each article, providing clear when-to-use and alternative steps.

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 annotations already declaring idempotentHint=false and openWorldHint=true, the description adds valuable context: each call costs generation credits, takes longer than other tools, requires an API key, the resulting URL is public and cannot be deleted, and results vary between runs. This goes well beyond structured fields.

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

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

The description is front-loaded with the core action and organized into three short paragraphs. Every sentence serves a purpose—no fluff or repetition. Slightly longer than strictly necessary but well-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?

For a tool with moderate complexity (generation, upload, return URL), the description covers the return value, non-idempotence, cost, deletion constraints, and variability. It omits error conditions or rate limits, but those aren't critical given the schema and annotations. Overall, quite complete.

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 the schema fully describes both parameters. The description adds minor extra guidance (e.g., 'avoid asking for text in the image') but does not significantly enhance meaning beyond what's already present. Baseline 3 is appropriate.

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 states a specific verb+resource: 'Generate an image from a text prompt with AI, upload it to the Misar.Blog CDN, and return its public URL for use as cover_image_url when publishing.' It clearly differentiates from siblings by mentioning 'use upload_image for a file the user already has.' No ambiguity.

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 provides when to use and when not: 'Use it when no artwork exists yet; use upload_image for a file the user already has.' Also warns about non-idempotence and cost, which informs decision-making. This is exemplary 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?

Annotations already include readOnlyHint=true and destructiveHint=false)Skip: The description adds meaningful behavioral traits: it's non-deterministic ('repeated calls return different titles'), requires an API key and consumes credits, and explicitly states nothing is saved or created. These go beyond the annotations and inform the agent about cost and side effects. 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.

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

The description is three well-structured paragraphs, front-loaded with the main purpose first, then usage guidance, then behavior/side effects. Each sentence adds value; no filler. Slightly long but justified by the amount of useful 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?

For a generative tool with 2 parameters, 100% schema coverage, and no output schema, this is very complete. It covers side effects (nothing saved/updated), requirements (API key), cost (credits), determinism (non-deterministic), and differentiation from sibling. The agent knows exactly what to expect.

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 100%, so baseline is 3. The description adds extra semantics for 'context' – it clarifies that providing draft text helps titles match the article but does NOT change the keyword focus, which remains driven by prompt. It reinforces the prompt's purpose with an example. This adds value beyond the schema, so a 4 is warranted.

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: 'Generate SEO titles from keywords' is expanded with specifics – it produces article titles from a topic or keyword, includes a strategy hint, and targets AI answer engines and Google. It explicitly differentiates from the sibling tool suggest_titles by explaining when each should be used, which is a strong purpose statement that distinguishes it from siblings.

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 gives explicit guidance: 'use this one when you have a topic or keywords and the article may not be written yet. Use suggest_titles when the draft already exists.' It also states when not to use it ('Nothing is saved... use update_article to apply a title') and that context does not make it equivalent to suggest_titles.

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?

Annotations already declare readOnly, idempotent, and non-destructive. The description adds meaningful context beyond annotations: requires an API key, revenue is returned in cents with a formatted convenience field, and zero views is a real answer not an error. No contradiction.

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

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

Three sentences, each carrying distinct valuable information: purpose/metrics, usage boundaries, and operational details (auth, units, edge case). No filler or 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?

For a simple single-parameter tool with no output schema, the description fully covers what the agent needs: scope, metrics, return format, units, auth, and error semantics. It is complete enough to invoke correctly without additional documentation.

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 sole parameter 'days' is already fully documented in the schema (trailing window, range, default, examples). The description reinforces the trailing-window concept but adds no new semantic detail 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.

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

The description uses a specific verb ('Summarise') with a clear resource ('the account's performance') and lists exact metrics (page views, revenue, subscriber count). It distinguishes itself from sibling tools by making clear this is the only whole-account analytics tool, not per-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?

Explicitly states when to use ('how did I do this month' questions), and provides clear exclusions: cannot break down per article, covers trailing window ending today rather than arbitrary date range. This guides the agent away from inappropriate 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?

Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint false), the description adds useful context: 'Reads only; nothing is created or modified.' It also discloses the API key requirement for unpublished articles, states what is returned (article object with content_markdown populated), and defines error conditions (slug not found or account cannot see it). This supplements the annotation metadata effectively.

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 compact yet comprehensive: it opens with the purpose, then gives usage guidance and invokes the listing tools, and finally covers reads-only nature, auth nuance, return format, and error handling. Every sentence adds value, and it is front-loaded with the primary action. No fluff or repetition.

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 tool with one parameter, rich annotations, and no output schema, the description covers everything needed: what it returns (article object with content_markdown populated), auth requirements (API key for unpublished), and failure modes (non-existent slug or permission issue). The complexity is low, and the description is sufficiently complete to guide correct usage.

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 100% because the only parameter 'slug' is thoroughly described in the schema (e.g., not numeric id, not full URL, with an example). The tool description does not add extra parameter semantics beyond restating 'by slug' in the purpose. Baseline 3 is appropriate because the schema already carries the semantic load, and the description doesn't compensate further (nor need to).

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 ('Fetch a single article by slug') and the resource/scope ('full Markdown body'). It distinguishes itself from sibling tools like list_my_articles and search_articles, which are about listing/searching, while this fetches a specific 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?

Explicitly tells the agent when to use it: after list_my_articles or search_articles has provided a slug, and the actual content is needed. It also explains the deliberate trade-off (listing tools omit bodies for cheapness) and gives use cases (reading, editing, repurposing). This is strong usage guidance with clear sequencing and context.

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?

Beyond the annotations (readOnly, idempotent, non-destructive), the description adds valuable context: it requires an API key, counts against quota, returns follow relationship and follower count, and errors on invalid UUID. This fully discloses behavior without contradicting annotations.

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

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

The description is four sentences, front-loaded with the primary purpose, and each sentence adds essential information (use case, scope, safety, requirements, error behavior). No fluff or repetition.

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?

With one parameter, no output schema, and comprehensive annotations, the description covers usage, limitations, return information, and error handling, making it complete for an agent to correctly invoke and interpret 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?

The schema already provides 100% coverage for user_id, including format and clarification that it is not a username. The description only reinforces that the profile is identified by UUID, adding negligible new meaning. Baseline 3 is appropriate since the schema handles parameter semantics.

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 checks follow status and follower count for a specific profile, using specific verbs and resource. It distinguishes from siblings by noting there's no tool that lists all followed profiles, making its unique scope explicit.

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?

It explicitly advises using this tool before offering to follow someone to avoid redundant actions, and clearly states it answers about one profile only, with no alternative tool for listing follows. This gives clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the base safety profile is covered. The description adds valuable behavior beyond annotations: it requires an API key, takes no parameters, only ever describes the caller, and errors on missing/invalid keys, framing the tool as a quick authentication test.

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?

Four sentences, front-loaded with the core purpose and return payload, then usage context, then constraints and error behavior. No filler or redundant restatement of the tool name; every sentence adds operational 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?

For a parameterless read-only tool with rich annotations and no output schema, the description is complete: it lists return fields, specifies authentication requirements, states invocation constraints (caller only), and explains error semantics. Nothing important is missing.

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?

There are zero parameters and schema coverage is effectively 100%, so the schema carries no burden. The description reinforces this by explicitly saying 'takes no parameters' and explaining the error behavior when a key is missing, which is sufficient for a parameterless tool.

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 opens with a specific verb ('Fetch') and a precise resource ('authenticated account's own creator profile'), then enumerates the exact fields returned (id, username, display name, bio, public profile URL, stripe_connected). It also explicitly distinguishes itself from any hypothetical other-profile lookup, which fully separates 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?

Gives three concrete use cases: confirming which account a key belongs to, retrieving your own profile id for UUID-accepting tools, and checking stripe_connected before discussing paid posts. It also states a clear exclusion ('there is no tool here for looking up someone else's profile'), preventing the agent from selecting it for the wrong task.

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?

Annotations already declare read-only, idempotent, non-destructive, and open-world hints, so the description's claim 'Reads only; no reaction is added or removed' is redundant but not contradictory. It adds valuable context: requires API key, zero counts are a real answer, and it returns both counts and caller's own reactions, which are not in annotations.

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

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

The description is four sentences, each contributing distinct value: purpose, use-case, safety/authorization, and return semantics. No redundancy or fluff.

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 tool's simplicity (one parameter, no output schema), the description covers purpose, usage, safety, and return meaning. No output schema means the agent needs to know what to expect, and the description specifies counts per type and caller's reactions. Completeness is high 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?

The single parameter is fully described in the schema (UUID of article, from article tools' id field). The description adds usage context by explaining the tool works on one article at a time, and confirms the parameter is the article_id. Since schema coverage is 100%, the baseline is 3, but the description enriches the parameter semantics by tying it to the workflow.

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 reads article reactions, specifying both total counts and the authenticated account's reactions. It distinguishes from siblings like add_reaction and remove_reaction by emphasizing it is a read operation.

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?

Explicit guidance: use before add_reaction or remove_reaction to determine current state (e.g., already liked vs. not liked). It also states it covers one article at a time, which sets expectations for batch operations.

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?

Aligns perfectly with annotations (read-only, idempotent, non-destructive) and adds new context: requires API key, no parameters, unfiltered and unpaginated, and empty list is not an error. This enriches the agent's understanding beyond annotations.

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

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

Every sentence serves a purpose: purpose, clarification, usage, behavior, return format, and edge-case handling. The structure flows logically from what → when → how, with no 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?

For a parameterless tool with no output schema, the description covers all necessary context: what it does, when to use, return shape, and error semantics. No gaps remain for an agent to misinfer.

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?

With zero parameters and 100% schema coverage, the baseline is 4; the description goes further by explicitly stating it takes no parameters and explaining the implications (no filtering/pagination). This adds semantic value 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?

The description clearly states the tool lists all series owned by the authenticated account, and explicitly clarifies that despite the name it returns the whole collection, not a single series. This distinguishes it from other series-related tools and eliminates ambiguity.

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 explicit use cases: finding a series slug before add_to_series, or checking existence before create_series to avoid duplicates. It also notes there is no single-series lookup, guiding agents away from misusing it.

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?

Annotations already declare readOnlyHint, idempotentHint, and non-destructive. The description adds valuable behavioral details beyond that: it requires an API key and counts against the plan's request quota, explains pagination behavior with limit and offset, and clarifies that an empty list simply means no comments yet (not an error). This goes beyond what annotations convey.

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

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

The description is concise and front-loaded with the core purpose in the first sentence. It packs essential details (pagination, quota, empty list behavior) into a few sentences without redundancy, and 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?

Given that there is no output schema and the tool is relatively simple, the description covers all necessary context: pagination, default page size, return content (authors and timestamps), empty-list interpretation, quota implications, and read-only nature. This is complete for an agent to invoke it reliably.

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?

Input schema has 100% description coverage for all three parameters, so the baseline is 3. The description reiterates the default limit of 20 and the pagination concept, but does not add semantic meaning beyond what the schema already provides. It mentions 'Page through with limit and offset' but that is usage guidance rather than parameter-specific semantics.

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 a specific verb and resource: 'Read the comment thread on one article, oldest first, paginated.' It distinguishes from sibling tools like add_reaction or get_reactions by focusing on the comment thread, and mentions the use case of reviewing reader feedback or summarising a discussion.

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?

It explicitly says 'Use it to review reader feedback or summarise a discussion' (when to use). It also states 'It reads comments only; there is no tool here for posting or moderating a reply,' which provides a clear exclusion and implies not to use it for those actions. Although it doesn't name an alternative tool, the guidance is unambiguous.

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?

Annotations already convey read-only, idempotent, non-destructive behavior, so the description adds context beyond them: it covers result shape, field omissions (no body), and total-count semantics. It does not contradict annotations and provides meaningful behavioral detail like 'newest first' and 'nothing is created or modified.'

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 compact, front-loaded with the core behavior, and each sentence earns its place. The three paragraphs cleanly separate core listing behavior, usage guidance, and return-value details 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?

Since there is no output schema, the description adequately explains the return envelope ('{ articles, total }'), the fields included, the notable omission (body), and the meaning of total. It also covers ordering, state coverage, and authentication context, making it complete for a read-only list 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 coverage is 100%, so parameters are already fully documented in structured form. The description adds interpretive context for status values (drafts/scheduled included) and response counting, but does not substantially extend the schema's parameter semantics.

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 uses a specific verb ('List'), names the resource ('articles'), and clearly scopes it to 'owned by the authenticated account' with ordering and status coverage. It also distinguishes itself from search_articles, making its purpose unmistakable.

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

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

Explicitly states when to use this tool ('to find your own work'), why it is the right choice ('only listing that sees unpublished content'), and names the alternative for site-wide search ('use search_articles instead'). It also points to get_article for article bodies, giving clear routing 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?

While annotations already declare readOnlyHint=true and destructiveHint=false, the description adds valuable context beyond them: a required API key (auth need), the returned fields (subject, status, send time), and crucially the empty-list-not-an-error semantic that prevents agents from misinterpreting an empty result as a failure. No contradictions with the safe-read annotations; in fact, the description's safety framing aligns with them.

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?

Four sentences, each carrying a distinct, useful purpose: what the tool does, when to use it, what it does NOT do plus auth, and how to interpret empty results. The core purpose is front-loaded in the opening sentence. There is zero redundancy, and 'Requires an API key' plus empty-list semantics earn their place in the description.

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 low-complexity tool with 1 optional parameter, full schema coverage, complete annotations (readOnly, idempotent, openWorld, non-destructive), and no output schema, the description covers all essential aspects: purpose, usage scenarios, side-effect guarantee, auth requirement, returned fields, and error semantics. An agent has everything needed to invoke this 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 description coverage is 100% — the schema fully documents the single 'limit' parameter (integer, 1-50, default 10). Per rubric, this establishes the baseline of 3. The description's 'newest first' adds ordering nuance, but the schema description already includes that same phrase ('newest first'), so the description adds marginal value beyond the schema for this dimension.

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 first sentence uses a specific verb-resource-scope structure ('List newsletter issues the account has sent or scheduled, newest first'), immediately clarifying what is listed and the ordering. The focus on 'issues' (sent/scheduled content) inherently distinguishes it from sibling list tools like list_newsletter_subscribers, which the description also names explicitly.

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 explicit when-to-use scenarios: 'check what went out and when' and 'confirm a scheduled send exists before queueing another.' It also names the precise alternative for a different need ('For WHO receives them, use list_newsletter_subscribers'), giving explicit exclusion criteria that prevents mis-selection.

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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the description's statement 'Reads only — no email is sent and no subscriber is added or removed' reinforces but doesn't add much beyond annotations. However, it adds valuable context about requiring an API key and the confidentiality of personal data, which is not in annotations. The description also mentions pagination behavior (default first 20), which is useful. 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.

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

The description is concise and well-structured, with a clear first sentence stating the purpose, followed by usage guidance, safety/confidentiality notes, and pagination details. Every sentence adds value without redundancy.

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

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

Given the tool's simplicity (2 params, no output schema, no nested objects), the description is quite complete. It covers purpose, usage, safety, confidentiality, and pagination. The only minor gap is not describing the return format (e.g., array of subscriber objects), but since there's no output schema, the description could have mentioned what fields are returned. However, for a list tool with good annotations, this is adequate.

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 the schema already documents both parameters (limit and offset) with defaults and ranges. The description adds minimal extra meaning beyond what the schema provides, only mentioning 'Page with limit and offset; the default returns the first 20.' This is baseline 3 since the schema does the heavy lifting.

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

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

The description clearly states the tool lists newsletter subscribers for the authenticated account, with pagination. It distinguishes itself from the sibling tool list_newsletter_issues by explicitly noting the difference between subscribers and sent issues.

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 explicit guidance on when to use this tool (to size audience or export list) and when not to (for sent content, use list_newsletter_issues). It also mentions the read-only nature and API key requirement, which helps the agent decide when to invoke it.

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?

Annotations already declare readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false. The description goes further: it reveals side effects (world-readable immediately), quota consumption, and a warning mechanism in the response ('response warns when the allowance is nearly spent'). Loses one point for not explicitly stating retry or rate-limit behavior, which would have made it a 5, but this is strong, non-annotation-redundant context.

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?

Three tight paragraphs: what it does, what to watch out for (non-idempotency), and operational specifics (quota, return values). Every sentence carries signal; no filler. Bolded 'PUBLISHES' effectively signals emphasis. Appropriate length for a high-stakes, non-idempotent, resource-consuming operation.

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 6-param tool with no output schema and no nested objects, the description covers the critical behaviors: immediate visibility, scheduling semantics, non-idempotency, quota, and return value fields (public url, editor_url). Slight deduction for not stating whether the quota applies per-request or per-publish (edge case) and not mentioning rate limits, but the description exceeds what a typical tool description offers at this complexity level.

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 100% with detailed per-parameter descriptions already. Description adds meaningful behavioral meaning beyond the schema: context for what 'published' means for schedule_at, the fact that omitting schedule_at publishes immediately, and that a past timestamp publishes immediately. This helps the agent reason about edge cases without re-stating what the schema already documents.

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?

Uses a specific verb+object construction ('Create a new article and make it live immediately, or schedule it') immediately followed by the operational implications. Clearly distinguishes from create_draft (the sibling) by stating what publishing means. The all-caps PUBLISHES reinforces the permanence and visibility semantics without redundancy.

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 provides when-to-use and when-not-to: 'If the piece is not ready, use create_draft instead and publish later.' Names the alternative tool, explains the consequence of misuse (double publish), and points to update_article for modifications. Also warns about non-idempotency, which is a usage red-flag with decision-relevant consequences.

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?

Adds context beyond annotations: clarifies scope (leaves other reactions, doesn't delete article/comments), idempotency ('removing a reaction that is not there succeeds and changes nothing'), and requirement for API key. No contradiction with annotations (readOnlyHint false, destructiveHint true, idempotentHint true).

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

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

Three well-structured paragraphs: first states purpose, second details scope, third covers safety, auth, and recommendation. Each sentence is purposeful, no redundancy, and information is 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 simple 2-parameter tool with annotations, the description covers purpose, scope, behavior, auth, and usage guidance. It does not mention return values, but no output schema exists and it's a removal action; this is acceptable given the context.

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 100% with good descriptions. Description adds value by explaining that 'type' only removes that specific reaction without affecting others, and for article_id points to the 'id' field from article tools. This enriches the schema beyond the basic definitions.

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?

Clearly states 'Withdraw one reaction the authenticated account previously left on an article' with a specific verb and resource. It explicitly distinguishes from siblings by noting it removes exactly the type named and leaves other reactions intact, contrasting with add_reaction.

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 usage context by recommending 'Call get_reactions first if you need to know what is currently set.' It implicitly distinguishes from add_reaction and emphasizes idempotent behavior ('Safe to repeat'). Does not explicitly mention when not to use it, but gives clear practical 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?

The description goes far beyond the annotations by disclosing that nothing is saved, no draft/article/file is created, API key and credits are consumed per call, results are non-deterministic, and it returns prose to read with a warning to verify factual claims. This richly supplements the readOnlyHint, openWorldHint, and idempotentHint annotations without contradiction.

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

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

The description is front-loaded with the core action, then efficiently uses two more paragraphs for usage distinction and behavioral caveats. Every sentence carries meaningful information with no filler, and the structure makes key facts easy to scan.

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 generative research tool with one parameter and no output schema, the description explains the return content (insights, sources, outline), return format (prose, not JSON), runtime characteristics, cost implications, and non-determinism. It is fully sufficient for an agent to understand what to expect and how to act on the results.

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 already provides 100% coverage for the single 'query' parameter, including length constraints and specificity advice ('Specific beats broad'). The description adds little beyond the generic 'topic' wording, so it neither improves nor detracts from the schema's clear parameter documentation.

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 opens with a specific verb and resource: 'Research a topic with AI and return insights, sources, and a suggested content outline.' It clearly distinguishes from siblings by stating it is raw material, not a finished article or title, and explicitly points to generate_title_seo and search_articles for those needs.

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?

It gives explicit when-to-use guidance: 'Use it at the START of a piece, before drafting — it produces raw material to write from, not a finished article and not a title.' It also names alternatives for titles and existing content checks, and warns that it runs longer than a plain read, implying it is not for quick lookups.

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?

Beyond the annotations, the description adds meaningful behavioral details: unauthenticated callers are rate-limited by IP, filters combine with AND, results are summaries without bodies, and an empty array indicates no matches rather than an error. These are not implied by readOnlyHint or openWorldHint and are valuable for correct agent behavior.

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 compact, well-structured, and front-loaded with the core purpose. Every sentence contributes either scope clarification, usage guidance, behavioral context, or return-value semantics, with no filler or repetition.

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 four optional parameters, no output schema, and important edge behavior (draft visibility, rate limits, empty results), the description covers the necessary ground: what is searched, what is excluded, how to retrieve full content, filter combination, and error semantics. This is sufficient for confident tool invocation.

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 input schema already covers 100% of parameters with useful descriptions, so the baseline is 3. The description adds the cross-cutting semantic that 'Filters combine with AND,' which is not stated in the individual schema fields and clarifies how to compose multiple 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 opens with a specific verb and resource: 'Search PUBLISHED articles across all of Misar.Blog, including other creators' work.' It clearly distinguishes this discovery-oriented search from list_my_articles, which returns the caller's unpublished work, and from get_article, which returns full article text.

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 explicitly states when to use the tool ('discovery, research, and competitive reading') and names the alternative for unpublished content ('reach for list_my_articles when you want your unpublished work'). It also directs the agent to get_article for full-text needs, making the decision boundary very 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?

Beyond the annotations (readOnly, destructive=false), the description discloses important behavioral traits: nothing is saved, the article is not retitled, applying a title requires a separate update_article call, an API key is required, credits are consumed per call, and results are non-deterministic across repeated calls. It also mentions the 20-character minimum, which complements the schema.

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

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

The description is concise yet complete, with each sentence earning its place: the first sentence states the core function, the second gives usage guidance, and the third covers side effects, requirements, and non-determinism. It is well-structured 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 tool with a single parameter, strong annotations, and no output schema, the description covers all necessary dimensions: purpose, when to use, safety profile, side effects, prerequisites, and behavior. No critical information is missing.

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 100% and the schema already describes the context parameter in detail (plain or Markdown, 20-8000 characters, more real draft yields better titles). The description repeats the 20-character minimum and adds no new meaning beyond the schema, so the baseline of 3 is appropriate.

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

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

The description clearly states the action ('Generate 5 title options') and the resource ('FROM AN EXISTING DRAFT'), and specifies the input source ('derived from what the article actually says'). It also differentiates from the sibling tool generate_title_seo by noting it takes no keyword input.

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 provides when-to-use guidance: 'use this one when the text exists and should drive the headline' and contrasts with generate_title_seo ('when you are starting from a topic or keyword'). It also states an exclusion: 'this tool takes no keyword input at all.'

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?

Even with annotations present, the description adds substantial behavioral context: partial updates ('omitted fields keep their current values'), tag-list replacement semantics, immediate effect on published articles without unpublishing or re-dating, idempotency ('same call twice leaves the same result'), ownership requirement, and the error case for empty updates. It complements the annotations without contradicting them.

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

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

The description is front-loaded with the core purpose, followed by concise paragraphs on behavior, safety, and requirements. Every sentence earns its place: partial updates, tag replacement, publication behavior, idempotency, permissions, error condition, and return value are all covered without fluff.

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 4-parameter mutation tool with no output schema, the description covers everything an agent needs: what fields can change, how partial updates behave, the special tag-list behavior, side effects on published content, repeatability, authentication/ownership prerequisites, and the returned value. Nothing critical is missing.

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 100%, but the description adds critical parameter semantics beyond the schema: 'Only the fields you pass are touched' clarifies that all parameters are optional once id is provided, and 'Passing tags REPLACES the whole tag list' explains the replacement behavior. It also groups the trivially named title/body/tags into a meaningful list and warns about the 'no updatable field' error condition, fully compensating for any 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 opens with 'Change the title, body, or tags of an article or draft that already exists,' which pairs a specific verb ('Change') with a clear resource ('article or draft') and explicit fields. It clearly distinguishes update_article from siblings like create_draft and publish_article by emphasizing the 'already exists' scoping.

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 context for when to use the tool: to alter specific fields of an existing article/draft, with partial-update semantics. It also gives important usage constraints ('send the full set' for tags, requires API key/ownership, errors if no updatable field). It does not explicitly name alternative tools or say 'use create_draft instead,' so it stops short of a 5.

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

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

The description clarifies that no-arg calls are read-only, while with arguments it can change the account (start trial) or open a browser (checkout). It adds that neither action charges a card, and notes the API key requirement, all beyond the annotations which only indicate not read-only and idempotent.

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 structured in three sentences, front-loaded with the primary purpose and follow-up details. It is slightly verbose with repeated emphasis on 'only on explicit instruction', but remains clear and not overly long.

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?

The description fully covers the tool's dual nature (read vs. act), when to use it, side effects (trial/checkout), and dependencies. It also provides the API key requirement and cross-references the `status` tool, making it complete for practical use.

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 already provides descriptions for all three parameters, including the dependency between `plan` and `open`. The description text does not add substantial information beyond the schema, so it remains at the baseline for high coverage.

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 explicitly states the tool shows the account's plan and quota, and optionally upgrades via trial or checkout. It distinguishes from sibling tools (which are article/title related) by focusing on account billing and plan management.

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?

It clearly says the tool is useful for checking quota anytime and as a follow-up after quota errors, and explicitly instructs to use `start_trial` and `open` only on explicit user instruction. It also points to the `status` tool for authentication, providing an alternative.

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