Misar.Blog MCP Server

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses the idempotent behavior ('No-ops if already reacted') and an authorization requirement ('Requires API key'). This provides useful behavioral traits beyond what the schema alone offers, avoiding contradictions.

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 very concise with only two sentences that front-load the main purpose and then add the idempotent behavior and requirement. Every sentence provides distinct 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 is simple (2 params, no output schema, no nested objects), the description adequately covers the core behavior. The addition of idempotency and auth requirement fills gaps beyond the schema. Minor improvement would be to mention return value (e.g., success/error response) since there is no output schema.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add any parameter-specific meaning beyond what the schema already provides (e.g., the enum values for 'type' are already documented in the schema). No additional semantics like format constraints or validation rules are provided.

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 ('Add a reaction to an article'), identifies the resource ('reaction' and 'article'), and distinguishes the idempotent nature ('No-ops if already reacted'). However, it does not explicitly differentiate from the sibling tool 'remove_reaction', which would help clarify that this tool is for adding 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 mentions 'Requires API key' as a prerequisite, but does not provide guidance on when to use this tool versus alternatives like remove_reaction or when not to use it. The context of adding a reaction is implied but no explicit usage context or exclusions are given.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It does not mention whether the tool is idempotent, what happens if the article is already in the series, if the position parameter is overwritten, or what side effects occur (e.g., updating timestamps). The brief sentence only names the action, leaving critical behavioral traits undocumented.

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

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

The description is a single concise sentence with no wasted words. However, it lacks structure (no leading summary, no logical breakdown) and is too brief to cover essential information. It earns its place by stating the purpose, but could be improved with a brief expansion.

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 3 parameters, no output schema, and no annotations, the description is incomplete. It does not explain the return value, error cases, or the effect of the optional position parameter. For a tool that modifies a series, more context (e.g., confirmation of success, what happens on failure) is necessary.

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 input schema already documents all three parameters (series_slug, article_slug, position). The tool description adds no additional meaning or context beyond the schema. Baseline of 3 is appropriate as 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 'Add an existing article to a series' uses a specific verb ('Add') and resource ('existing article to a series'), clearly stating the action. Among sibling tools like create_series, get_series, and update_article, it is distinct and 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?

No guidance is provided on when to use this tool versus alternatives (e.g., update_article could also modify series membership). There is no mention of prerequisites (the series and article must exist) or when not to use it (e.g., if the article is already in the series). The description gives no context for appropriate invocation.

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

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

With no annotations provided, the description carries the full burden. It indicates a write operation ('Save') but lacks details on authentication requirements, idempotency, whether it overwrites existing drafts, or what happens on failure. This is insufficient for a creation tool.

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

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

A single, efficient sentence that front-loads the verb and resource. Every word earns its place, with no fluff or repetition. Excellent conciseness.

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 creation tool with three parameters and no output schema, the description omits crucial context: return value (e.g., draft ID), error states, and whether the operation can update an existing draft. The single sentence is insufficient to guide an agent confidently.

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 has 100% coverage with descriptions for each parameter (title, body_markdown, tags). The description adds the contextual framing ('draft'), but does not enrich parameter meaning beyond what the schema already provides. 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 ('Save an article as a draft') and the platform ('Misar.Blog'), with the added purpose ('for review before publishing'). It distinguishes from sibling tools like publish_article and update_article, though it does not explicitly say 'create new' vs 'update existing'—the name implies creation.

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 phrase 'for review before publishing' implies this tool is a pre-publish step, contrasting with publish_article. However, no explicit when-not or alternative tools are mentioned, leaving the agent to infer usage from context alone.

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

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

No annotations are provided, so the description must fully disclose behavior. It only states the basic creation action but omits side effects, authorization needs, rate limits, scope (e.g., user context), and whether the operation is idempotent. Minimal transparency for a mutation tool.

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

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

A single sentence that directly conveys the tool's purpose with no redundancy or wasted words. The structure is front-loaded and efficient.

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 two simple parameters but no output schema and no annotations. A complete description for a creation tool should indicate what the tool returns (e.g., series ID or confirmation) or any post-creation state. The current description leaves the agent without enough context to fully understand the tool's behavior.

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 parameters are fully documented in the input schema. The description adds no extra meaning beyond what the schema already provides (title and description fields). 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 action ('Create') and the resource ('a new series') with the grouping context ('to group related articles'). It distinguishes from the sibling 'add_to_series', which adds articles to an existing series, 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 no guidance on when to use this tool, when not to, or how it relates to alternatives like 'add_to_series'. An agent receives no contextual cues for decision-making.

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

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

No annotations are provided, so the description must carry the burden of disclosing side effects. It only states that it uploads to a CDN, but it doesn't clarify whether the upload is permanent, whether it triggers costs, or if there are rate limits. It also doesn't mention that the generated image is AI-based, which could have implications.

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

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

The description is a single sentence that is concise and front-loaded with the core action. It has no waste, making it highly efficient.

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 moderate complexity (2 params, no output schema), the description is adequate but lacks details on return values (e.g., URL of uploaded image) and any potential side effects like CDN caching. It's minimal but functional, and the absence of an output schema means the description could have clarified what the agent should expect as a result.

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 describes both parameters. The description adds no extra meaning beyond providing the tool's overall purpose. Since coverage is high, baseline 3 is appropriate, but it could have explained the default size context or prompt best practices.

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 a cover image) and the resource (cover image), and specifies that it uploads to the Misar.Blog CDN. This distinguishes it from other tools like generate_title_seo or suggest_titles, which are about text, though it doesn't explicitly name alternatives.

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

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

The description implies usage for generating cover images for articles, but it doesn't explicitly state when to use it versus alternatives like generate_title_seo. It lacks guidance on contextual triggers, such as when creating a draft or updating an article, and doesn't mention any prerequisites.

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?

As there are no annotations, the description must carry the full weight of behavioral transparency. It clearly states it generates titles, not articles, and controls expectations by mentioning 'keyword strategy hint' for each title. This level of detail is needed for a generation tool.

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 remarkably concise and well-structured. It front-loads the core purpose and number of titles, then provides critical context about optimization targets, and ends with the output format. Every sentence is informative and earns its place.

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 the moderate tool complexity (2 parameters, 100% schema coverage), the description is entirely self-sufficient. It fully explains the tool's purpose and output without requiring a return value schema, as the value proposition is in the generated content itself.

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 already at 100%, so the baseline is 3. The description adds value by explaining the *why* behind the `prompt` parameter (providing examples and desired specificity), which goes beyond the simple `description` in the schema. It does not add context to the `context` parameter, preventing a 5.

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 purpose is exceptionally clear. It specifies the exact number of titles generated (5), the types of optimization (SEO/AEO/GEO), and the target engines (Google, AI answer engines). This clearly distinguishes it from the sibling 'suggest_titles' tool.

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

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

The description explicitly details the optimization targets and output format (keyword strategy hint). It implies a use case for content marketing and SEO strategy. However, it could improve by explicitly stating when *not* to use it (e.g., for simple, non-SEO title generation).

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

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

No annotations are provided, so the description carries full burden for behavioral disclosure. The description only says it 'gets' data but doesn't state whether this is a read-only operation, whether it requires specific permissions (e.g., owner, editor), whether the data is cached or live, or any side effects. For a tool returning analytics which could be sensitive or computationally expensive, this is a meaningful omission.

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

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

The description is a single short phrase of 11 words, which is extremely concise, but it is so short that it lacks structural detail. It front-loads the purpose but omits behavioral transparency, usage guidelines, and any detail about the parenthetical items (what are 'views'? pageviews or unique?). It is not wasted text, but it is underspecified for the required completeness.

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 1 parameter (handled by schema), no output schema, and no annotations, the description should compensate for the missing behavioral and return-value context. The description does not describe the output format, pagination, or whether the returned data is for all analytics or filtered by user/scope. This is a critical gap for a summary tool that likely returns a structured object without an output schema to define it.

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 single parameter 'days', which already documents the default, min, and max. The description adds no additional semantic value beyond what the schema provides (e.g., no mention of date format, timezone handling, or how days boundary affects data). Baseline 3 is appropriate when schema handles the parameter 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 verb 'Get', the resource 'analytics summary', and specifies key data points returned (views, revenue, subscribers) with a scope constraint 'for a time period'. It is sufficiently specific to distinguish it from sibling tools, which are about articles, reactions, series, drafts, etc., none of which are analytics-summary 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?

The description provides no guidance on when to use this tool versus any alternative. It does not mention when not to use it, list prerequisites, or compare with similar tools like 'search_articles' or 'list_my_articles'. The agent has no context to decide between this and other analytics-adjacent tools.

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

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

With no annotations provided, the description carries the full burden. It correctly indicates a non-destructive, read operation ('Get') and promises 'full markdown content,' which is useful behavioral information. However, it lacks details like whether the article's full history is returned, if there are visibility restrictions (e.g., draft vs. published), or any rate-limiting information. It is adequate but not comprehensive for a tool that presumably returns substantial data.

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

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

The description is a single, front-loaded sentence that effectively communicates the core purpose and key output details. It is concise with no wasted words. While it could benefit from an additional sentence clarifying usage boundaries (e.g., if the article must be published), it earns its place in the current form.

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 (1 parameter, no output schema, no nested objects), the description is partially complete. It covers the 'what' and 'how' (by slug, includes content) but is incomplete for an agent that might need to know if the tool retrieves published, draft, or both types of articles. With no output schema, more details on the return structure (e.g., does it include metadata like published date?) would improve completeness. The presence of sibling tools like 'update_article' and 'publish_article' suggests versioning or state management that the description does not address.

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, with the 'slug' parameter already well-documented in the schema as 'The article slug'. The description adds only the context that the slug identifies the specific article to retrieve, which provides minimal additional value beyond the schema. Following the guidelines, 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 verb ('Get'), the resource ('a single article'), and the key identifier ('by slug'). It also specifies what is included in the output ('full markdown content'), which helps differentiate it from other article retrieval tools (e.g., search_articles, list_my_articles) by emphasizing the comprehensive content returned. A score of 5 is not given because it does not explicitly mention that it is a read-only operation or explicitly distinguish 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?

The description implies use when you need a specific article identified by its slug and require its full content. It is clear enough when this tool is appropriate. However, it provides no guidance on when not to use it or what alternatives exist (e.g., search_articles for multiple articles, list_my_articles for personal articles), leaving the agent to infer these distinctions from context and tool names.

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?

Description clearly indicates read-only public operation with no authentication required, but lacks details on return format, error cases, or preconditions (e.g., profile must be public). Given no annotations, some transparency is provided but not comprehensive.

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

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

Two sentences, front-loaded, zero waste. Efficiently conveys purpose and a key constraint.

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?

Provides essential purpose and usage condition, but lacks details on return structure or error handling. Without an output schema, the agent must infer the response format, leaving incomplete guidance.

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?

Parameter user_id is fully documented in the input schema (format, description). The tool description does not add any additional meaning beyond the schema, so baseline 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?

Clearly states it retrieves public follow status and follower count for a user by UUID. Differentiates from get_profile by focusing on follow relationship rather than full profile, but does not explicitly mention when to use one over the other.

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

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

No explicit usage guidance. Only mentions that no API key is required, which hints at public accessibility but does not help agent decide when to use this tool over get_profile or other sibling tools.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. The description only states the action without revealing any side effects, authentication requirements, or return characteristics. It fails to add behavioral context beyond the bare action.

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

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

The description is a single, front-loaded sentence that conveys the tool's purpose with no wasted words. It is appropriately sized for the tool's simplicity.

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

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

For a zero-parameter tool with no output schema, the description is sufficiently complete. It names the resource and implies ownership ('your'), which is adequate for a simple retrieval operation.

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 does not add parameter-specific meaning, but none is needed as there are no parameters to document.

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 ('Get') and resource ('your Misar.Blog creator profile'), clearly indicating what the tool retrieves. Among sibling tools like get_article, get_analytics_summary, etc., it is uniquely identified as the one for the creator's own profile, differentiating it effectively.

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 no guidance on when to use this tool versus alternatives. There is no mention of context, prerequisites, or exclusions, leaving the agent without explicit direction on when to invoke this tool over others.

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 are not provided, so the description carries the full burden. It discloses the API key requirement, which is a behavioral trait (authentication). It also implies a read-only operation by using 'Get', but does not explicitly state that it has no side effects. Given that annotations are absent, stating the API key requirement adds valuable context beyond 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, consisting of one sentence that clearly states the purpose and the authentication requirement. There is no wasted information, and it is front-loaded with the core functionality.

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 is simple with one parameter, no output schema, and no annotations. The description is sufficient for an agent to understand what to expect: reaction counts and user reactions. It doesn't describe the output structure, but since there is no output schema, a brief mention could be helpful, but the simplicity of the data (reaction counts) makes it acceptable. The description covers the essential points.

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 only one parameter (article_id) with a description, and schema description coverage is 100%. The description does not add additional parameter semantics beyond what the schema provides. However, with 100% coverage, the baseline is 3, and the description is adequate without needing to elaborate on the parameter.

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

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

The description clearly states the tool's purpose: 'Get reaction counts and your reactions for an article.' It specifies a verb ('Get'), a resource ('article'), and the exact data returned (counts and user reactions). This distinguishes it from siblings like 'add_reaction' and 'remove_reaction', which are about modifying reactions, while this one is about retrieving them.

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

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

The description implies usage for retrieving reaction data but does not provide explicit guidance on when to use this tool versus alternatives. However, the purpose is clear enough that an agent can infer this is the retrieval counterpart to add/remove_reaction. There are no explicit exclusions or alternative mentions, but the context signals (single parameter, sibling tools) make it adequate.

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

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

No annotations are provided, so the description carries full burden for behavioral disclosure. It only says 'List all your series' but does not mention whether this is a read-only operation, if any authentication is needed, or what the response format looks like. For a tool with zero annotations, more transparency about behavior (e.g., 'Returns an array of series objects with id, title, and article count') is needed.

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

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

The description is a single sentence of 7 words, which is efficient and front-loaded. It earns its place by stating the verb, resource, and scope. 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 has no parameters, no output schema, and no annotations, the description is too sparse. It does not mention what information is returned (e.g., series titles, URLs, creation dates), whether results are paginated, or any ordering. For a list tool, this is a significant completeness gap.

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

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

There are no parameters, so schema description coverage is 100%. The description adds no extra parameter meaning because there are none to describe. Baseline 4 is appropriate for a zero-parameter 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?

The description clearly states it lists all your series on Misar.Blog, with a specific verb ('List') and resource ('series'). It distinguishes from siblings like 'create_series' (creation) and 'add_to_series' (modification) by omission, but lacks explicit distinction from other list tools like 'list_my_articles' or 'list_comments'.

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 when you need to see your series, but provides no guidance on when to use this tool versus alternatives like 'get_article' or 'list_my_articles'. No explicit when-not-to-use or prerequisites are mentioned.

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?

Since no annotations are provided, the description carries the full burden. It indicates rate-limiting behavior (an important operational trait) and that the endpoint is public. However, it does not disclose whether comments are sorted by recency, whether deleted or hidden comments are included, or what the return format looks like. The description provides some behavioral insight but leaves significant gaps.

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 very short (one sentence with two clauses). Each part serves a purpose: stating what it does and adding a rate-limit warning. There is no wasted text. It could be slightly improved by front-loading the main action, but it is sufficiently concise.

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

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

Considering the schema has 3 parameters (one required), no output schema, and no annotations, the description provides basic functionality and a key constraint (rate-limit). However, it lacks details on pagination, sorting, comment ordering, and what constitutes a 'public comment' (e.g., does it include replies?). It is minimally complete but leaves questions for the agent.

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

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

The description does not elaborate on the parameters beyond what the schema provides. With schema description coverage at 33% (only `article_id` has a description), the description could have added clarity for `limit` and `offset` (e.g., pagination semantics, whether results are sorted by time). It adds no additional meaning, so the score stays at baseline 3.

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 ('get public comments') and the target resource ('an article'). It includes a specific verb-resource pair. However, it only partially distinguishes itself from sibling tools; tools like 'get_reactions' or 'get_article' have different purposes, but the description could explicitly note it is for fetching paginated comments, not reactions or full 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 mentions that the tool is rate-limited by IP and requires no API key, which gives some usage context. However, it does not provide explicit guidance on when to use this tool versus alternatives (e.g., 'get_reactions' for reactions, 'get_article' for full text), nor does it mention when not to use it or any prerequisites.

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

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

With no annotations, the description carries full burden for behavioral transparency. It only states 'List your articles', implying a read operation, but does not disclose key behaviors like pagination, ordering, rate limits, or that results are limited to the authenticated user's own articles.

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 extremely concise at 5 words, front-loaded, and contains no fluff. However, it is arguably too terse for a tool with multiple parameters and siblings, missing some context that could be added without verbosity.

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

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

Given no output schema, the description should explain what is returned (e.g., article list, metadata, pagination). It does not. The two parameters are covered by the schema, but the overall tool behavior is under-described for a list operation with filtering and pagination.

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%—both parameters ('limit' and 'status') have descriptions in the schema. The description adds no additional meaning beyond what the schema provides, meeting the baseline of 3.

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 ('List') and the resource ('your articles on Misar.Blog'). It is specific enough to differentiate from sibling tools like 'get_article' (single article) or 'search_articles' (search), though it does not explicitly name alternatives.

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

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

No guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites, contexts, or exclusions, leaving the agent without decision support for tool 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?

With no annotations provided, the description carries the full burden. It discloses the authentication requirement (API key), which is useful context. However, it does not explain pagination behavior, how sent and scheduled issues are combined, or the response structure, leaving some behavioral gaps.

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

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

The description is a single, efficient sentence that gets straight to the point. It front-loads the main action and includes the auth note without unnecessary verbosity.

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?

This is a simple list tool with one optional parameter and no output schema. The description conveys the core purpose but does not explain the return format, how the limit parameter affects results, or whether sent and scheduled issues are returned together. Basic completeness is there, but details are 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?

The schema has one parameter (limit) with no description (0% coverage). The tool description does not mention this parameter at all, so it adds no meaning beyond the schema's type and constraints. The parameter is simple, but the description should have compensated for the lack of schema descriptions.

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 ('Get') and a clear resource ('your sent and scheduled newsletter issues'), which clearly distinguishes it from sibling tools like list_newsletter_subscribers. It precisely indicates the scope (sent and scheduled) and the resource type (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 implies when to use this tool (to fetch your newsletter issues) but does not explicitly mention alternatives or when not to use it. The auth requirement is a prerequisite, not a usage guideline. Sibling tools like list_newsletter_subscribers exist but are not contrasted, so guidance is only implicit.

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

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

No annotations exist, so the description must fully disclose behavioral traits. It only states the operation is a read-like 'Get' and mentions auth, but omits details like pagination behavior, rate limits, what data is returned, or any side effects (e.g., whether it counts against quotas).

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 extremely concise (one sentence). While it avoids fluff, it is under-specified and omits important information, so it does not earn the highest score for conciseness because efficiency should not come at the cost of adequacy.

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 only two parameters, the description should explain the list contents, pagination behavior, and how limit/offset work. It provides none of this. The tool is simple but the description is incomplete.

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 0%, so the description must add meaning. It fails to mention the two parameters (limit and offset), their defaults, constraints, or purpose. The schema provides minimal info (type, defaults, ranges) but the description adds zero value beyond that.

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

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

The description clearly states the verb ('Get') and the resource ('your newsletter subscriber list'), distinguishing it from siblings like 'list_newsletter_issues' which concerns issues, not subscribers. However, it does not explicitly differentiate it from other list tools.

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

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

The description mentions 'Requires API key authentication' as a prerequisite but offers no guidance on when to use this tool versus alternatives like list_comments or list_my_articles. There are no when/not-to-use conditions or context about typical use cases.

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

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

No annotations are provided, so the description carries the full burden of disclosing behavioral traits. It only states the action ('publish or schedule') without revealing any side effects, irreversibility, permission requirements, or whether publishing overwrites an existing draft. This leaves the AI agent with significant uncertainty about the tool's 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 a single, front-loaded sentence that efficiently communicates the core purpose. However, given the six parameters and the scheduling nuance, it is slightly too terse; a brief mention of optional fields or the scheduling mechanism would improve completeness without losing conciseness.

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?

Without an output schema and with no annotations, the description fails to explain the return value, side effects, or how scheduling affects behavior. For a tool with six parameters and a nontrivial action (publishing vs. scheduling), the description is insufficient to fully inform the agent about what happens after 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?

Schema description coverage is 100%, so each parameter is already documented in the schema. The tool's description adds no extra meaning beyond the schema's parameter descriptions; the mention of scheduling merely mirrors the 'schedule_at' field. Thus, it meets the baseline for high coverage but does not provide additional 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 uses a specific verb ('Publish') and resource ('new article'), and explicitly mentions scheduling as an option. This clearly distinguishes it from sibling tools like 'create_draft' (which creates but doesn't publish) and 'update_article' (which modifies an existing article).

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

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

The description implicitly indicates the tool is for making an article live or scheduling it, which differentiates it from alternative tools like 'create_draft'. However, it does not provide explicit guidance on when to use this vs. other tools, nor does it mention prerequisites or conditions (e.g., whether the user must be logged in or have publish permissions).

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

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

No annotations are provided, so the description carries the full burden. It mentions requiring an API key but does not disclose other behavioral traits such as whether the reaction must exist before removal, what happens if it doesn't, whether the removal is permanent or reversible, or any rate limits or side effects. This is insufficient for a mutation tool.

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 extremely concise with one sentence that front-loads the primary action. However, it could be slightly longer to include essential behavioral details without becoming verbose.

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 the tool is simple with 2 required parameters and no output schema, the description is minimally adequate. It covers the core action and one prerequisite but lacks context about idempotency, error handling, or relation to the 'add_reaction' sibling, leaving gaps in completeness.

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 with their types and constraints. The description adds no additional meaning beyond the prerequisite mention. Baseline 3 is appropriate as the description does not improve or detract from what the schema provides.

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 ('remove'), the target resource ('specific reaction from an article'), and a prerequisite ('Requires API key'). It distinguishes this tool from siblings like 'add_reaction' and 'get_reactions' by specifying removal.

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 use when you need to undo a reaction, but it does not explicitly state when to use this tool versus others (e.g., 'add_reaction' for adding, 'get_reactions' for viewing). No exclusion criteria or alternatives are provided, only a single prerequisite.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions 'AI-generated' but does not reveal limitations such as potential latency, API costs, output reliability, or whether results are cached. This leaves significant behavioral ambiguity.

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

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

The description is two sentences, front-loaded with the core purpose, and contains no extraneous information. Every word earns its place.

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 simple single-parameter input and no output schema, the description covers the basic function and use-case. However, it lacks details about the output format (e.g., structure of insights, source citations) and any usage constraints. With no annotations, a bit more context would improve completeness.

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% (one parameter with description). The description builds on it with the phrase 'Be specific for best results', adding practical usage advice beyond the schema's basic description. This adds meaningful 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 verb 'Research' and the resource 'a topic', and specifies the outputs: AI-generated insights, sources, and a content outline. This sufficiently distinguishes it from sibling tools like 'suggest_titles' or 'create_draft'.

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 phrase 'Useful before writing an article' provides clear context for when to use the tool. However, it does not explicitly mention when not to use it or point to alternative tools, slightly limiting 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?

With no annotations provided, the description carries the transparency burden. It explicitly states the tool searches only PUBLISHED articles and includes other creators' work, which is a key behavioral constraint. However, it doesn't mention response ordering, pagination, or authentication, though these are less critical for a search tool.

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 (two sentences), front-loaded with the action and filters, and the second sentence provides a concise usage alternative. Every sentence earns its place with no waste.

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 covers the search scope, available filters, and explicitly contrasts with list_my_articles. Given the tool's simplicity and full schema coverage, the description is complete enough; it doesn't need to elaborate on output since no output schema is present here.

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 parameter meaning is fully available in the schema. The tool description adds the grouping 'keyword, tag, or author' but doesn't add new semantics beyond the schema. Thus 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 action (search), the resource (published articles across Misar.Blog), and the available filters (keyword, tag, author). It explicitly contrasts with list_my_articles, making the purpose unambiguous and distinguishing 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 explicit guidance by directing users to use list_my_articles for drafts and unpublished posts, establishing clear boundaries for when this tool should be used versus the alternative.

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

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

With no annotations provided, the description carries the full burden. It discloses the number of titles (5), the style (SEO-friendly), and that it works from existing content. It does not mention potential side effects or permissions, but for a read-only generation tool, this is sufficient.

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

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

Two sentences: one states the action with key specifics, the other provides an alternative. No unnecessary words 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?

The tool is simple with one parameter and no output schema. The description covers what it does, how many outputs, the style, and usage context. It could mention the output format (e.g., a list), but the core information is present.

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 adds context that the content should be from an existing article, but the schema already describes 'context' as article content. The description does not add new constraints or format details 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 generates 5 SEO-friendly title options from existing article content. It distinguishes itself from the sibling tool generate_title_seo by specifying when to use each.

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 says when to use this tool versus generate_title_seo: use suggest_titles when you have existing content, and use generate_title_seo for targeting keywords or without content. This provides clear decision guidance.

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

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

No annotations are provided, so the description carries the full burden. It discloses the partial update behavior but does not mention authorization needs, rate limits, side effects, or response format. It is adequate but not rich.

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

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

Two concise sentences, each earning its place. The first sentence states purpose and scope, the second explains partial update behavior. No superfluous text.

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 (mutation, 4 parameters, no output schema), the description covers the key behavioral aspect (partial update). It does not explain what happens on success/failure, but the context is adequate for an agent.

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 each parameter well. The description adds important semantics like 'omitted fields keep their current values', which explains why fields are optional. This adds 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 verb 'update' and the resource 'existing article or draft', and lists the specific fields (title, body, tags). This distinguishes it from sibling tools like create_draft (create) and publish_article (publish).

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 specifies that only passed fields are changed and omitted fields keep their values, which is helpful partial update guidance. However, it does not explicitly state when not to use this tool (e.g., use create_draft for new articles) but the context implies 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 discloses that setting 'open=true' opens the checkout page, revealing a browser action. Since annotations are absent, it fairly covers the tool's behavior, though it doesn't detail if a browser will always open or if credentials are required.

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 sentences, each serving a distinct purpose: stating core function, encouraging usage, and explaining key parameter behavior. No unnecessary words, and critical info 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?

Given the absence of annotations and output schema, the description fairly explains input parameters and when to call. However, it lacks details on return value format (e.g., what 'capabilities upgraded' looks like) and doesn't clarify if 'start_trial' requires prior eligibility conditions.

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 100% of parameters with descriptions, so the baseline is 3. The description adds value by explaining that 'open' opens the checkout page and 'plan' defaults to recommended, which is meaningful context beyond the schema's basic descriptions.

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: showing plan status, quota usage, and upgrade info. It specifies a verb ('Show') and resource ('Misrar.Blog plan'), and differentiates from siblings that perform actions like adding reactions or creating drafts.

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 says to call it any time, not only after hitting a limit, giving clear usage context. However, it doesn't specify when not to use it or mention alternatives among siblings, like tools that might handle billing differently.

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