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

Annotations already declare idempotentHint=true, and the description reinforces this by stating the call is safe to repeat and won't double-count. It adds context about acting publicly as the account holder and requiring an API key, which goes beyond annotations. However, it doesn't detail the response format or any rate limits, but with annotations covering idempotency and non-destructiveness, the description adds sufficient value.

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, with three short paragraphs that are front-loaded with the core action. Every sentence adds value: the first states the action, the second provides usage guidance, and the third covers idempotency and related tools. 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 the tool's simplicity (2 params, no output schema, no nested objects), the description is complete. It covers the action, usage constraints, idempotency, and related tools. The only minor gap is not describing the response format, but since there's no output schema, the description could have mentioned it, but it's not critical for a simple mutation 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 the schema already documents both parameters well. The description adds minimal extra meaning beyond the schema, but it does clarify the 'type' enum values in the schema itself. The description doesn't add new parameter semantics 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 the tool records a reaction (like, clap, or bookmark) from the authenticated account on an article. It distinguishes from siblings by explicitly naming remove_reaction and get_reactions, and the verb 'record' plus resource 'reaction' is specific.

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 guidance: only call when the user has actually asked to react, not on their behalf. It also explains the single-type-per-call behavior and names alternatives (remove_reaction, get_reactions) for related actions.

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 meaningful behavioral details beyond the annotations: it notes API key requirements, that adding does not change publication status or URL, that insertion shifts later articles down, and that unknown slugs cause errors. These are important operational traits not captured by the annotations alone.

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 operation, and every sentence carries useful information. It covers prerequisites, identifier sourcing, optional positioning, side effects, and error behavior without redundant 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 mutating relationship-assignment tool with three parameters and no output schema, this description is complete: it covers prerequisites, authentication, how to get inputs, insertion semantics, side effects, and error conditions. Nothing essential 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 provides detailed descriptions for series_slug, article_slug, and position, including the append behavior and shifting semantics. The description reinforces the same information but adds little new parameter-specific meaning 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 uses a specific verb ('Place an existing article into an existing series') that clearly identifies the operation and its resources. It also distinguishes itself from creation tools by explicitly stating 'this creates neither'.

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 when-to-use context: both the series and article must already exist. It also directs the agent to get_series and article tools for slugs, and explains the optional position behavior ('Omit position to append at the end').

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 behavioral details beyond annotations: it spells out the non-idempotence consequence ('calling twice leaves two drafts'), assures that 'nothing becomes visible to readers,' requires an API key, and mentions the return value with an editor_url. These go beyond the flags in annotations and provide meaningful context.

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

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

The description is three tightly written sentences: first sentence states purpose, second provides usage guidance, third discloses behavior. It is front-loaded, free of fluff, and every sentence carries meaningful content.

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 create operation, the description covers purpose, usage, non-idempotence, auth, and return value. It does not specify the full response shape or error behaviors, but with no output schema and simple parameters, this is nearly complete. A brief note on the returned draft object would earn a 5.

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 has 100% parameter coverage with detailed descriptions (e.g., 'Working headline. Can be changed before publishing.'). The description adds no additional parameter-level information, so the baseline score of 3 is appropriate.

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

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

The description opens with 'Save an article as an unpublished draft,' a specific verb+resource+state combination. It explicitly distinguishes itself from sibling tools by mentioning publish_article and update_article, making it clear this is for the draft stage only.

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 guidance: 'use this whenever the work still needs review, and publish_article only when it should go live.' It also states that the draft can be edited with update_article, clearly delineating the tool's role among 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?

Discloses required API key, the public URL side effect, and that the series remains empty until articles are added. Also mentions the return value includes the slug needed by add_to_series, covering side effects and return behavior beyond annotations.

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

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

The description is three sentences, each serving a distinct purpose: definition, usage guidance, and side effects/return. No redundant information 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 schema covers parameter definitions, the description augments with usage preconditions, side effects, and return value expectations, providing a complete context for using 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 complete descriptions for both parameters (title and description), including that the slug is derived from title. The tool description adds no extra parameter-specific details, so it remains at 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 tool creates a new, empty series, which is a named collection for articles. It distinguishes itself from sibling tools like add_to_series and get_series by focusing on the creation aspect.

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 advises calling get_series first to avoid duplicate series, and notes that each call creates a new series without deduplication. 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?

The description goes well beyond annotations by disclosing: generation costs credits, is not idempotent, takes longer than other tools, requires an API key, produces a public non-deletable URL, and yields varying results. This adds critical context for a state-changing tool with financial 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 concise yet information-dense. Each sentence adds value: purpose, usage, side effects, and limitations. No redundant phrases or filler—perfectly structured for quick comprehension.

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, cost-incurring tool with no output schema, the description covers all essential context: output (public URL), prerequisites (API key), side effects (cost, non-deletion, variability), and performance expectations. Very complete for agent decision-making.

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 descriptions for both parameters (prompt and size). The description adds no parameter-specific information beyond what the schema already provides, 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 tool's function: '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 names specific verbs and the resource, and explicitly contrasts with upload_image, distinguishing 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?

Provides explicit when-to-use guidance: 'Use it when no artwork exists yet; use upload_image for a file the user already has.' It also notes cost implications and non-idempotency, helping the agent decide based on 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?

The description adds valuable behavioral context beyond the annotations: it states nothing is saved, no article is created or retitled, requires an API key and consumes credits, and notes the generative nature (repeated calls return different titles), which aligns with idempotentHint=false and openWorldHint=true. No contradictions found.

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

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

The description is well-structured in three clear paragraphs: function, usage distinction, and side effects. Every sentence earns its place, and it is appropriately concise for the information conveyed.

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 two parameters and no output schema, the description provides complete guidance: what it generates, how it differs from a sibling, prerequisites, side effects, and the fact it's generative. It fully covers the agent's needs for correct invocation and expectation setting.

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% for both parameters, so the baseline is 3. The description adds extra nuance by clarifying that passing context does not make the tool equivalent to suggest_titles—titles still optimize for the supplied keywords. This goes beyond the schema's description of context, providing semantic 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 tool generates 5 search-optimised article titles from a topic/keyword, each with a keyword-strategy hint. It explicitly distinguishes this from suggest_titles by noting it works from topics/keywords rather than existing drafts, making the purpose unambiguous and differentiated from its sibling.

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 guidance: 'use this one when you have a topic or keywords and the article may not be written yet' and contrasts it with suggest_titles for existing drafts. It also clarifies that passing context does not make it equivalent and notes prerequisites (API key, credits) and the need to call update_article to apply a title.

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 and destructiveHint=false. Beyond this, the description adds important context: requires an API key, revenue is in cents with a formatted USD convenience field, and zero views is a real answer not an error. These go well beyond the annotation baseline.

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

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

The description is organized into three short paragraphs with each sentence earning its place: purpose, usage, then caveats. It is front-loaded with the main function and avoids redundancy, even while covering edge cases like units and zero views.

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 no output schema, the description must explain return values, and it does: page views, gross/net revenue in cents, a formatted USD field, and active subscriber count. It also covers prerequisites (API key) and edge-case semantics (zero views). For a one-parameter read-only tool, this is 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% for the only parameter (days), which already specifies the trailing window, range, default, and usage examples. The description mentions the trailing window but does not add new parameter semantics beyond what the schema provides, 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 opens with a specific verb and resource: 'Summarise the account's performance over a trailing window: page views, gross and net revenue, and active subscriber count.' It clearly distinguishes from siblings by noting these are whole-account totals and cannot be broken down per article, contrasting with tools like get_article or search_articles.

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 usage guidance is provided: 'Use it for 'how did I do this month' style questions.' It also states exclusions: cannot break results down per article and only covers a trailing window ending today rather than an arbitrary date range, ruling out 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?

Despite readOnlyHint already being provided, the description adds valuable context: API key requirement for unpublished articles, published ones readable without, and error conditions. This goes beyond annotations and matches the tool's actual 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?

Though slightly verbose with four sentences, each sentence contributes context: purpose, usage, behavior, auth, errors. It is front-loaded with the core action and not redundant given the added info beyond annotations.

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 tool with one parameter and no output schema, the description covers all critical aspects: what it does, when to use it, read-only nature, auth requirements, return content, and failure modes. It is essentially complete for an agent to invoke correctly.

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

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

The schema already fully describes 'slug' with explanation and example, and the description adds no new parameter-level detail. Baseline of 3 is appropriate given 100% 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 ('Fetch a single article by slug') and distinguishes it from listing tools that omit bodies, making it unambiguous and aligned with its 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?

It explicitly tells when to use the tool ('after list_my_articles or search_articles has given you a slug') and explains the rationale for fetching one at a time, clearly contrasting with 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?

The description discloses that the tool is read-only, does not change follow state, counts against quota, and errors on invalid UUID. These details go beyond the annotations to set accurate 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 multi-sentence and provides necessary context without excessive verbosity. It is well-structured with clear statements, though slightly longer than strictly needed for a simple tool.

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 tool with one parameter and no output schema, the description covers the returned information (follow relationship and follower count) and error conditions, making it complete for typical 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 parameter schema already includes a detailed description for 'user_id'. The tool description reinforces that it identifies a single profile and clarifies the UUID format, adding contextual usage. This slightly exceeds the schema alone.

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 single profile, distinguishing it from sibling tools that list or manage follows. It uses specific verbs and identifies the resource.

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 advises using the tool before offering to follow someone to avoid redundant actions, and clarifies it handles one profile rather than listing all followed profiles. This differentiates it from 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description doesn't need to restate safety. It adds value by mentioning it requires an API key, takes no parameters, and errors on missing/invalid key, which are behavioral details beyond annotations. Not a full 5—could mention response format or exactly when stripe_connected is present.

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 reasonably concise, front-loaded with the core action and output fields. It includes necessary usage context and a parenthetical limitation, but the second half could be trimmed slightly; still, every sentence contributes.

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, the description is complete: it specifies the exact purpose, the fields returned, use cases, limitations, and authentication behavior. With no output schema, the description fully conveys what the agent gets back. Sibling context shows it fits well among a broader set.

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 has zero parameters, so the description needn't explain parameters. However, it effectively communicates that no parameters are needed and explains the output fields, providing semantic value for what the tool returns. A baseline of 4 is appropriate since params are 0.

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 fetches the authenticated account's own creator profile, listing specific fields (id, username, display name, bio, public profile URL, stripe_connected). It distinguishes itself from siblings by explicitly noting there is no tool for looking up others' profiles, making its scope 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?

Provides explicit use cases: confirming which account a key belongs to, getting own profile id for tools requiring UUID, checking stripe_connected before discussing paid posts. Also clarifies when not to use it (for others' profiles) and states it can be used to test authentication via errors.

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 states it is read-only, reinforcing the annotations (readOnlyHint, idempotentHint, destructiveHint: false). It adds context that no reaction is added or removed, requires an API key, returns counts per type, and clarifies that zero counts are valid answers. It goes beyond annotations by mentioning API key requirement and response semantics.

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 and front-loaded, opening with the core function. It uses bullet-like sentences with no filler, and every sentence adds value—usage guidance, read-only reassurance, and zero-count clarification. 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 the low parameter count, high schema coverage, and robust annotations, the description is quite complete. It provides usage context, response expectations, and authentication note, but doesn't explain the output schema (though none exists). The only minor gap is not detailing exact response format, but that is not required given the tool's simplicity.

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 has 100% coverage with a description for article_id (UUID from article tools). The description adds the context that the tool returns the caller's own reactions and counts, but does not add much parameter-specific info beyond what's in the schema. Since schema coverage is high and the parameter is simple, the baseline of 3 gets a slight bump for confirming usage context.

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 reaction totals on one article and which reactions the authenticated account has left, specifying the scope ('one article at a time'). It distinguishes itself from sibling tools like add_reaction and remove_reaction by focusing on reading current state rather than mutating it.

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 add_reaction or remove_reaction to determine current state ('not yet liked' vs 'already liked'), and notes it covers one article at a time. This gives clear guidance on when to use it and how it fits with 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds rich behavioral context: it requires an API key, is unfiltered and unpaginated, returns a specific structure `{ series, total }` with detailed per-entry fields, and defines empty-list semantics ('not an error'). This goes well beyond the annotations and fully discloses 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 concise despite containing multiple pieces of information. Each sentence serves a purpose: purpose, clarification of name, use cases, behavioral details, and return format. It is front-loaded with the main action and flows logically. 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?

Given the tool has zero parameters and no output schema, the description goes beyond the minimum by defining the exact return shape and edge-case behavior (empty list). It also covers authentication, rendering it fully self-contained. The agent has everything needed to select and invoke the tool without ambiguity.

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 zero parameters (100% coverage). Baseline for zero params is 4, but the description adds valuable context by stating 'takes no parameters — it is unfiltered and unpaginated.' This explicitly prevents the agent from attempting to pass filters or pagination, which is meaningful for correct invocation. Thus it exceeds the baseline.

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: 'List every series the authenticated account owns.' It further distinguishes itself from a single-series lookup by explicitly noting that despite the name, it returns the whole collection and that there is no single-series lookup. This clearly differentiates from sibling tools like create_series and 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 provides explicit when-to-use guidance: 'Use it to find a series slug before calling add_to_series, or to check whether a series already exists before create_series makes a duplicate.' It also clarifies the read-only nature, telling the agent it can be safely used for lookups without side effects. No exclusions are needed, making this highly actionable.

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 readOnlyHint=true and destructiveHint=false, the description adds significant value: API key requirement, quota consumption, pagination behavior, response shape, and the useful disambiguation that an empty list is not an error. These behavioral details go well beyond what the annotations communicate.

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 earning its place: purpose, use case, and error semantics. Front-loaded with the most important information first. 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?

For a simple read-only tool with 3 params and no output schema, the description is thorough: it covers ordering, pagination, auth, quota, response contents, and error handling. The context is fully provided within the description and annotations.

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 marginal value by framing limit/offset as a pagination workflow ('Page through with limit and offset') and reiterating the default of 20, which reinforces the conceptual model even though the schema documents the parameters thoroughly.

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 opening sentence 'Read the comment thread on one article, oldest first, paginated' uses a specific verb (read), specific resource (comment thread on one article), and adds scope (one article) plus ordering (oldest first). This clearly distinguishes it from sibling tools like get_reactions or get_article, and the explicit 'It reads comments only; there is no tool here for posting or moderating' further differentiates it.

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 it ('Use it to review reader feedback or summarise a discussion') and when not to ('reads comments only; there is no tool here for posting or moderating a reply'). This gives clear when/when-not guidance without 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds valuable context beyond annotations: requires an API key, returns a specific shape with fields, notably excludes the article body, and clarifies that 'total' counts all matches, not just the returned page. This goes beyond the structured hints.

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

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

Four sentences, each earning its place: purpose+scope, when to use, read-only reassurance/auth, and return shape with a key exclusion. Information-dense without 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?

Though no output schema exists, the description fully covers the return structure, field list, the notable absence of body content, and pagination/authentication details. For a list tool with two optional parameters and strong annotations, this is complete enough for an agent to select and invoke 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 covers both parameters fully with descriptions, giving a baseline of 3. The description adds meaning by clarifying default status behavior ('including drafts and scheduled posts' when status omitted) and pagination semantics ('total counts all matches, not just the page returned'). This compensates 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 uses specific verb 'List' with a clear resource: 'articles owned by the authenticated account'. It immediately distinguishes from siblings by noting it is 'the only listing that sees unpublished content' and explicitly contrasts with search_articles, 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?

Provides explicit when-to-use guidance: 'Use this to find your own work' and names the alternative: 'To search across the whole site, including other creators, use search_articles instead.' Also directs users to get_article for body content, covering exclusions and alternatives clearly.

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, but the description adds valuable context: it states this neither sends nor cancels an issue, requires an API key, returns subject/status/send time, and clarifies that an empty list is not an error. This goes well beyond the structured 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 tightly structured: main purpose first, then use cases, alternative tool, read-only note, auth requirement, return contents, and empty-list clarification. Every sentence contributes meaningful information without 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?

For a simple read-only list tool with one optional parameter, the description is complete: it covers what is returned, when to use it, the alternative tool, auth needs, and edge-case behavior. The absence of an output schema is compensated by the explicit mention of returned fields.

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 fully documents the single 'limit' parameter with range, default, and ordering semantics, so schema coverage is 100%. The description does not add parameter-specific detail, but the schema already carries the full burden, earning the baseline score.

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') with a clear resource ('newsletter issues') and scope ('sent or scheduled, newest first'). It also distinguishes itself from the sibling tool list_newsletter_subscribers by explicitly stating it covers issues, not recipients.

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 concrete use cases: checking what went out and when, and confirming a scheduled send before queueing another. It also explicitly names the alternative tool for recipient-related queries, providing clear when-to-use guidance.

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

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

The description adds behavioral context beyond the annotations: it states that no email is sent, no subscriber is added/removed, and that it returns personal data requiring confidentiality. The annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the description reinforces and adds the privacy warning, which is valuable. It doesn't contradict annotations.

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

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/privacy notes, and pagination details. Every sentence adds value, and it's appropriately sized for the tool's complexity.

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

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

Given the tool's simplicity (2 optional params, no output schema, no nested objects), the description covers all necessary aspects: purpose, usage, safety, privacy, and pagination. It's complete for an agent to use correctly without further clarification.

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 provides full descriptions for both parameters (limit and offset) with defaults and ranges. The description mentions pagination with limit and offset and the default of 20, but doesn't add much beyond the schema. Since schema coverage is 100%, a 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 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 issues, use list_newsletter_issues). It also mentions the requirement of an API key and the read-only nature, 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?

The description goes well beyond the annotations by disclosing that the tool BLOCKS until human action, that force=true ROTATES and invalidates existing keys, that an existing valid session returns immediately without changes, and that it listens on a short-lived local port. These are critical behavioral traits. There is no contradiction with the annotations.

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

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

The description is front-loaded with a clear one-sentence purpose, then usage conditions, then critical warnings. Each paragraph earns its place, and nothing is redundant with the schema. The entry is moderately long but all pieces are necessary for safe invocation.

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 success flow, key storage location, blocking behavior, force semantics, port selection, and base_url handling. It does not explicitly state what happens if the user cancels or fails to respond, nor the exact return value format, but the absence of an output schema makes this a minor gap. Overall the agent has enough context to invoke the tool appropriately.

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?

Even though the schema already provides 100% parameter coverage, the description adds behavioral nuance: force=false does not change anything if already authenticated, the port is where the short-lived callback listener runs, and base_url should be omitted for the hosted service. This enriches the schema's semantic values rather than just repeating parameter names.

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: 'Connect a Misar.Blog account by browser consent', specifying the verb, resource, and unique method. This distinguishes it from all sibling tools, which are post-reading/publishing/analytics operations, not authentication.

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 conditions: 'Use it when status reports no key, or when a tool fails as unauthenticated.' It also gives strong when-not-to-use guidance: 'never call it speculatively or in a retry loop.' No alternatives are named, but no other sibling provides this function, so the guidance is sufficiently 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?

The description discloses key behavioral traits beyond annotations: it publishes immediately (world-readable), is not idempotent (calling twice publishes twice), requires an API key, consumes quota, and warns when allowance is nearly spent. It also mentions the return value includes public url and editor_url. This adds significant context beyond the annotations (readOnlyHint=false, idempotentHint=false) and does not contradict 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 concise and well-structured: it opens with the core action, then explains key behaviors in a clear paragraph, and ends with return value. Every sentence adds value, and it is front-loaded with the most important information. 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?

Given the tool's complexity (6 params, scheduling, visibility, non-idempotency, quota), the description is complete. It covers the main use cases, side effects, prerequisites (API key), and return value. The schema covers parameter details, and the description adds the behavioral context needed for correct invocation. No output schema exists, but the description mentions the return fields, so the agent knows 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?

The schema already covers all parameters with descriptions (100% coverage), so the baseline is 3. The description adds value by explaining the effect of schedule_at (omit to publish immediately, past timestamp publishes immediately) and the visibility options, which are not fully detailed in the schema. It also mentions cover_image_url can come from generate_cover_image, linking to a sibling tool. This goes beyond the schema, so a 4 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 tool creates a new article and makes it live immediately or schedules it, with a specific verb ('Create') and resource ('article'). It distinguishes from siblings by explicitly contrasting with create_draft and update_article, and notes the non-idempotent behavior.

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 guidance: use create_draft if the piece is not ready, use update_article to change an existing article. It also explains the scheduling option and the immediate publication effect, giving clear context for choosing this tool over alternatives.

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

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

Beyond the annotations (destructiveHint, idempotentHint), the description adds crucial behavioral details: it specifies that only the named reaction type is removed, other reactions remain intact, nothing else is deleted, and calling with a non-existent reaction is a no-op. This enriches the annotation-provided hints 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 concise and well-structured, using three clear sentences. It fronts the core action, then elaborates on scope and side effects, and ends with practical guidance. 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 only two parameters, no output schema, and strong annotations, this description fully covers the necessary context: it explains the tool's purpose, safety, idempotency, authentication requirement, and a recommended precondition (get_reactions). It is complete for a tool of this 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 covers all parameters (100%), so the baseline is 3. The description adds value by clarifying that the 'type' parameter is specific to the exact reaction being removed, and that removing one type does not affect others. It also reinforces the purpose of article_id in context, though it doesn't add new syntax or format 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: withdrawing a specific reaction from an article. It specifies the resource (reaction) and the action (withdraw/remove), and explicitly differentiates from sibling tools like add_reaction and get_reactions by focusing on removal semantics.

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: it notes the need for an API key, advises calling get_reactions first when unsure of current reactions, and highlights the safe-to-repeat nature. This gives the agent clear context on when to use this tool and what prerequisites exist.

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 and destructiveHint=false, but the description adds substantial behavioral detail: nothing is saved, it consumes AI credits and costs per call, runs noticeably longer than a plain read, produces non-deterministic results, and returns prose rather than structured JSON. This goes well beyond the annotations without contradicting them.

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

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

The description is front-loaded with the core purpose, then each subsequent sentence adds a distinct practical point: when to use, alternatives, side effects, cost, runtime, non-determinism, output format, and verification caveat. No sentence is wasted.

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, non-deterministic tool with no output schema, the description is remarkably complete. It covers return shape, side effects, cost, timing, determinism, and how to verify output, plus differentiates from sibling tools. This is more than sufficient for an agent to select and invoke the tool correctly.

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

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

The single parameter `query` is fully documented in the schema, including length constraints and a concrete example of specificity. The description does not need to add much parameter-level detail, so the baseline of 3 applies.

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 action verb and resource: 'Research a topic with AI and return insights, sources, and a suggested content outline.' It clearly distinguishes itself from siblings by stating it is not a finished article, not for titles (use generate_title_seo), and not for checking existing content (use search_articles).

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 when-to-use guidance: 'Use it at the START of a piece, before drafting.' It also names direct alternatives for related tasks and states that the tool produces raw material, not a finished article or title.

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 readOnly annotation, the description details behavior: it is read-only, requires no API key (with IP rate-limit), filters combine with AND, returns summaries without bodies (directing to get_article for full text), and states that an empty array means no matches (not an error). This thoroughly discloses behavior and edge cases.

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 but information-dense, structured with a clear purpose statement, usage guidance, and behavioral details. Every sentence adds value without redundancy, making it well-organized and easy to parse.

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 nature (read-only search), the description covers essential context: what it returns (summaries without bodies), how to get full text (via get_article), authentication requirements, rate limiting, and error semantics (empty array). It also points to the appropriate alternative for unpublished content, making it fully self-contained.

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?

Each parameter has a clear schema description (e.g., q matches title and body with min 2 chars, tag is exact, limit defaults to 10 and ranges 1-20, author is by username). The tool description adds the crucial interaction that filters combine with AND, enhancing semantic understanding beyond the schema alone.

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 searches published articles across all of Misar.Blog, including other creators' work, and clearly distinguishes it from list_my_articles by specifying it does not return drafts, scheduled, or private posts. This makes the purpose unambiguous and differentiates 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 provides direct usage guidance ('Use this for discovery, research, and competitive reading'), explains when not to use it (for unpublished work, pointing to list_my_articles), and mentions rate-limiting for unauthenticated callers, giving clear context on when and how to invoke 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 valuable behavioral context beyond annotations: it states the tool is read-only ('Reads only; it never creates or rotates a key'), clarifies that 'not authenticated' is a successful response rather than an error, and describes the three distinct states it distinguishes. This is rich detail beyond the readOnlyHint and idempotentHint 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 sentences, each earning its place: purpose, usage trigger with alternative, and behavioral disclosure. It is front-loaded with the core purpose and contains zero fluff. Every clause contributes actionable 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 tool with no parameters and no output schema, the description is remarkably complete. It covers purpose, when to use, failure semantics (no-key state and login fallback), what it does not do (create/rotate keys), and how it differs from sibling tools (upgrade, get_profile). This fully equips an agent to invoke it correctly.

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

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

The tool has zero parameters, which sets a baseline of 4. The description appropriately focuses on what the tool inspects (the stored key state) rather than parameters, and there is no schema detail to repeat. The description adds no parameter-specific meaning, but none is needed.

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: 'Report whether this client holds a working Misar.Blog API key, and which account it belongs to.' It uses a specific verb ('report') and resource ('Misar.Blog API key') and distinguishes it from siblings by explicitly referencing login, upgrade, and get_profile as alternatives for other actions.

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 guidance: 'Run it first when anything is failing with an auth error, and before a run of write operations.' It also gives a conditional action: 'If it reports no key, run `login`.' This clearly differentiates it from write operations and other auth-related 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?

Beyond annotations (readOnlyHint true, destructiveHint false), the description explicitly states that nothing is saved, the article is not retitled, and requires an API key with credit consumption. It also discloses the generative (non-deterministic) nature of the tool and the 20-character minimum, providing critical behavioral context that annotations alone do not convey.

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

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

The description is concise and well-structured: it leads with the core purpose, then explains usage differentiation, followed by side effects and constraints. Each sentence adds unique value, and no redundant or filler content exists.

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 (single parameter, no output schema) and strong annotations, the description fully covers what an agent needs to know: when to use it, what it returns (5 titles), that it is read-only and doesn't persist changes, cost implications, and the non-deterministic output. It also mentions the specific update_article tool to apply a title, covering the follow-up action.

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 description already fully explains the 'context' parameter (plain/Markdown, 20-8000 chars, and advice to use the full draft for better titles). The tool description repeats these points but adds no new parameter-level information that isn't already in the schema, so it meets the baseline without exceeding it.

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 'Generate 5 title options FROM AN EXISTING DRAFT, derived from what the article actually says.' It specifies the exact deliverable (5 titles) and the input (existing draft). It also distinguishes itself from the sibling tool generate_title_seo by explaining when each should be used, making the tool's 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?

The description provides explicit when-to-use guidance: 'use this one when the text exists and should drive the headline' and contrasts with generate_title_seo for keyword-driven scenarios. It also notes the tool 'takes no keyword input at all,' reinforcing the selection criteria.

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 provide idempotentHint=true, readOnlyHint=false, and destructiveHint=false. The description adds rich detail: partial update semantics, tags replacement behavior, immediate effect on published articles, API key/ownership requirements, and an error condition. This goes well beyond the annotations without contradicting them.

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

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

The description is appropriately sized with a front-loaded purpose statement, followed by behavioral details, then security/error/return info. Every sentence provides necessary information without 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?

The tool has no output schema, but the description states it 'Returns the updated article.' It also covers partial update behavior, tags replacement, published-article effects, idempotency, auth requirements, ownership, and an error condition. This is very complete for a mutation 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 the baseline is 3. The description adds value by explaining that only passed fields are touched (partial update) and that an error occurs if no updatable field is supplied. It reinforces the tags replacement meaning already in the schema but adds the partial-update context.

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 'Change the title, body, or tags of an article or draft that already exists.' This uses a specific verb (change) and resource (existing article/draft), clearly distinguishing it from creation or publication tools in the sibling list.

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

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

The description implies usage by specifying 'article or draft that already exists' and discusses effects on published articles, but it never explicitly names alternative tools (e.g., create_draft, publish_article) or states when NOT to use it. Context is clear but exclusions/alternatives are absent.

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 only declare readOnlyHint=false, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds materially richer behavioral context: start_trial is a real account change, open launches a checkout page in the user's browser, neither charges a card by itself, an API key is required, and the returned quota snapshot already reflects a same-call trial. No contradiction with annotations exists.

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 purpose, then explains usage, then covers safety and authentication. It is slightly longer than strictly necessary, with minor overlap between 'No billing state changes unless you pass start_trial' and 'Neither charges a card by itself,' but the length is justified given the tool's dual read/action nature.

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 complexity, three optional parameters, and no output schema, the description is remarkably complete. It covers default read behavior, what the read mode returns, when to use it, the side effects of both action arguments, API key requirements, trial behavior, and how it relates to the `status` sibling. An agent can safely decide when and how to invoke this 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?

Since the input schema has 100% description coverage, the baseline is 3. The description adds value by clarifying that passing either argument shifts the tool from reporting to acting, that these arguments should only be passed on explicit user instruction, and that plan defaults to the recommended plan. It reinforces safety-critical semantics without merely repeating 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 opens with a specific purpose: 'Show the account's current plan, how much of each quota remains, and what a higher plan unlocks.' It clearly differentiates the no-argument read mode from the two-argument action mode, and the title reinforces this dual behavior. This distinguishes it from siblings like status, which is about authentication rather than plan/quota information.

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 usage guidance: called with no arguments it only reads and is 'useful any time, not just after hitting a limit,' and it is 'the natural follow-up when a write tool reports a quota error.' It explicitly warns that arguments should be passed 'only on explicit instruction from the user' and directs authentication questions to the sibling tool `status`, providing both 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?

Beyond the annotations (readOnlyHint=false, idempotentHint=false, destructiveHint=false), the description discloses that each call creates a new CDN object, the URL is public and undeletable, and nothing on the filesystem is modified. It also warns against uploading private content. This is rich, annotation-complementing behavioral detail.

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 earns its place: main action, usage guideline, behavioral warnings, and format constraints. The description is compact yet comprehensive, front-loaded with the primary purpose and followed by increasingly specific caveats.

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 only one parameter and no output schema, the description covers all essential context: return value (public URL), idempotency behavior, filesystem side effects (none), access restrictions (local only, API key), and format support. Nothing important is left unstated.

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?

Although the schema already fully documents 'file_path' with an example, the description adds semantics: absolute path required, accepted formats (JPEG, PNG, WebP, GIF), and that type is inferred from extension. This goes beyond the schema to make parameter usage foolproof.

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+resource+outcome: 'Upload an image file from the local filesystem to the Misar.Blog CDN and return its public URL.' It also distinguishes the tool from its sibling 'generate_cover_image' by explicitly naming it, making the purpose unmistakable.

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

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

Provides explicit when-to-use guidance: 'Use it for images the user already has on disk; use generate_cover_image when the image does not exist yet.' It additionally covers environmental constraints (local stdio only) and prerequisites (API key), leaving no ambiguity about when this tool is appropriate.

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