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

The annotation already provides destructiveHint=true, so the agent knows deletion is destructive. The description adds critical behavioral detail: categories moves feeds to default (no data loss), labels are detached only, the two-step confirmation flow, and the matching order between categories and labels. This goes well beyond the annotation, scoring high.

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, front-loads the core action, and each sentence adds unique value (behavior for category vs label, naming collision, confirmation flow). No wasted words; could be slightly more compact but is well within reasonable length.

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 2 parameters, destructiveHint annotation, and no output schema, the description covers the key behaviors: what happens to associated data, the two-step confirmation, and the naming ambiguity. For complexity level, this is nearly complete; only missing details like error cases or permissions.

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 both parameters (name, confirm_token) are documented in the input schema. The description adds context that 'name' must match exactly from list_categories, and that 'confirm_token' comes from a first call. This adds value beyond schema, but not enough to raise above baseline 3 given good schema already.

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

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

The description clearly states that the tool deletes a category or label, and it distinguishes the behavior between categories (feeds move to default, no articles lost) and labels (detached from articles). However, it does not explicitly differentiate from siblings like rename_category_or_label or other deletion tools, though the scope is specific enough.

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 explains when to use this tool (to delete categories or labels), mentions a naming collision caveat (categories matched first), and describes a two-step process with confirmation token. It does not explicitly state when not to use it or list alternatives, but the two-step guidance helps the agent select and invoke correctly.

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, indicating a safe read operation. The description confirms an export (read-only) but adds no further behavioral details like size limits or response format. It is consistent but does not add substantial context beyond the annotation.

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: first sentence states purpose, second provides a clear alternative. No redundant or extraneous information. Every sentence 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 tool has no parameters, no output schema, and annotations already cover safety, the description is complete. It explains what is exported (all subscriptions) and in what format (OPML), and offers a sibling alternative. No gaps remain for this simple 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 tool has zero parameters (100% schema coverage). With no parameters to describe, the description does not need to add parameter meaning. Per guidelines, 0 parameters yields a baseline score of 4.

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

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

The description clearly states the tool exports all subscriptions as an OPML document, a portable backup format. It distinguishes itself from the sibling list_feeds by directing users to that tool for a readable overview, ensuring no ambiguity.

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

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

Provides explicit guidance: use this tool to export a backup OPML, and for a readable overview use list_feeds instead. This directly addresses when to use and when not to use, naming a specific 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?

Annotations provide readOnlyHint=true, so the description doesn't contradict that. However, the description adds no extra behavioral context beyond the schema (e.g., whether content is truncated, if there's rate limiting, or what happens for invalid/private article IDs). With annotations already indicating safety, the bar is lower, but still minimal added 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 extremely concise at two sentences, with key information front-loaded. The first sentence covers purpose and format, the second adds a crucial constraint. No wasted text, though slightly more structure (e.g., mentioning the optional parameter) could improve readability for an agent.

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 there's no output schema, the description doesn't explain what the returned plain text looks like (e.g., HTML stripped? metadata included?). With 14 sibling tools and moderate complexity (2 params, no nested objects), the description is adequate but could be more self-contained by noting that article IDs come from list_articles or elaborating on the output format.

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

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

Schema description coverage is 100%, so baseline is 3. The description does not add meaning beyond what the schema already documents for 'article_ids' and 'max_content_chars' – it merely restates the id limit from the schema. No additional context about parameter behavior is 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 a specific verb ('Fetches') and resource ('full text of specific articles by id'), and distinguishes itself from sibling tools like 'list_articles' which likely return summaries. The constraint 'as plain text' adds precision, and the 20-id limit is unique to this 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 implies this tool is for retrieving article content after identifying articles via 'list_articles' (referenced in input schema), and the sibling context shows it's one of many article-related tools. However, it doesn't explicitly state when to use this versus 'mark_articles' or 'get_unread_counts', leaving some ambiguity for an agent.

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 provide readOnlyHint=true. Description adds that results are sorted by count and only include entries with unread articles, which are useful behavioral details. No mention of scope (e.g., user-specific) or performance characteristics, but sufficient given the tool's simplicity.

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

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

Two sentences with zero wasted words. The first sentence immediately states the core purpose (returns unread counts) and the second adds ordering and filtering. Perfectly 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?

Given no output schema, the description covers total, per-feed, and per-category breakdowns, sorting, and filtering. It does not specify whether feed/category identifiers are names or IDs, but the information is sufficient for an agent to decide when to call this tool. Sibling context (list_feeds, list_categories) can fill the 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?

No parameters exist, so schema coverage is trivially 100%. The description adds meaning by explaining that the output includes total counts and per-feed/category breakdowns sorted by count, which compensates for the lack of output schema and clarifies the tool's 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?

Description clearly states the tool returns unread article counts in total and per feed/category, sorted by count. It distinguishes from siblings like get_articles (which returns article content) and list_articles (which lists articles) by focusing on counts and aggregations.

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

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

No explicit guidance on when to use this tool versus alternatives. The purpose is clear, but the description does not mention that this tool is best for quick counts before fetching articles, nor does it contrast with list_feeds or list_categories. Usage context is implied but not stated.

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, so the description's additional context about returning account info is consistent but not extensive. It adds value by explaining the purpose but does not reveal new behavioral traits beyond the annotation.

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 action and purpose. Every word earns its place; no unnecessary 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 fully covers what the tool does, why it is useful, and when to use it. It is complete for its 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?

There are no parameters, so schema coverage is trivially 100%. The description adds meaning by explaining what the tool returns, which is useful even with zero parameters. Baseline 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 uses a specific verb ('Returns') and identifies the exact resource ('the FreshRSS account the server is authenticated as'). It clearly distinguishes from sibling tools, none of which concern authentication or account info.

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

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

The description explicitly states it is useful as a connection and credential check before anything else, providing clear context for when to invoke this tool. It does not exclude alternatives, but the guidance is strong enough for an agent.

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 reveals significant behavioral traits beyond the annotations: it refreshes all feeds (potentially minutes), has no bulk undo, and requires a two-step process with a confirmation token. These details are critical for the agent and are not present in the annotations or 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 three concise sentences, each serving a distinct purpose: core action and side effects, warning about undo, and the two-step process. No redundant or unnecessary information.

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

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

Given the tool's complexity (two-step, destructive, no output schema), the description covers the key aspects: what it does, the delay, lack of undo, and the confirmation token flow. It is slightly incomplete in not mentioning the return type of the second call (e.g., success/failure), but this is a minor gap.

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

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

The description adds meaning beyond the input schema: it explains the two-step process and the role of confirm_token. While the schema describes both parameters, the description contextualizes their usage. Baseline 3 because schema coverage is 100%, but the extra context about the two-step justifies a 4.

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

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

The description clearly states the specific verb 'subscribes to every feed' and resource 'OPML document', along with creating categories and refreshing feeds. This distinguishes it from sibling tools like subscribe_feed (single feed) and export_opml (export).

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

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

The description provides clear context: it is for bulk importing an OPML file, warns about the time cost and lack of bulk undo, and explains the two-step confirmation process. However, it does not explicitly contrast with alternatives like subscribe_feed for single feeds, leaving some interpretation to the agent.

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 correctly aligns with the readOnlyHint annotation, being a read operation. It adds value by noting the tool returns only IDs and is efficient, which annotations alone don't convey. It doesn't mention pagination via continuation, but since the parameter is self-explanatory, this is a minor gap.

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 short, front-loaded sentences convey purpose, usage guidance, and efficiency. Every word serves a purpose with no redundancy. 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?

The tool has 10 optional parameters with full schema coverage, no output schema, and annotations confirm read-only. The description effectively covers the core behavioral aspect (only IDs, cheap) and usage context (same filters). A very brief note about the response being just IDs might help, yet the purpose is clear enough.

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 doesn't add parameter semantics beyond what the schema already provides; it merely states that same selectors and filters apply. No additional value over the rich 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 clearly states that the tool lists only IDs of matching articles, explicitly positioning it as a cheap alternative to list_articles. It specifies the purpose and resource precisely, distinguishing it well from its siblings, particularly list_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 explains the tool is a cheap way to collect a set for mark_articles, and states it uses the same selectors and filters as list_articles. This provides clear when-to-use guidance and implicitly indicates when not to use it (when full article details are needed).

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 several behavioral traits beyond the readOnlyHint annotation: default returns excerpts, can return full text with include_content=true, newer-first ordering, pagination via continuation, and critical platform limitation 'FreshRSS has no full-text search over its API.' This provides rich context for safe and effective invocation.

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 carrying distinct and essential information: function, key options, and limitation/strategy. It is front-loaded with the core purpose, with no redundant or extraneous 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 has 12 parameters and no output schema, the description covers the main filtering strategy, default behavior, and a critical limitation (no full-text search). It mentions the alternative get_articles. However, it does not explain the response structure beyond 'short plain-text excerpts' or how multiple filters interact, leaving some ambiguity for complex queries.

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 the overall strategy (narrow with feed_id/category and date range, then filter) and the default response format (short plain-text excerpts). This synthesizes multiple parameters, going beyond individual 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 clearly states 'Lists articles from a feed, category, label or built-in stream, newest first.' This specifies the action (list), resource (articles), and sources (feed, category, label, stream), and distinguishes it from sibling tools like get_articles for fetching single 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 provides guidance by mentioning an alternative ('fetch single articles with get_articles') and advising to narrow results with 'feed_id/category and since/until instead and filter the returned articles yourself.' It implies when to use this tool (listing multiple articles) and when not to (keyword search not possible), but it lacks explicit exclusions or precise when-to-use scenarios.

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 readOnlyHint=true. The description adds that each entry includes an unread count, which is behavioral context beyond the annotation. However, it does not mention ordering, pagination, or any limits, but given zero parameters and simplicity, this level is adequate.

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

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

The description is two sentences, front-loaded with the core action after the verb 'Lists', and every sentence adds distinct value. No redundancy or filler.

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

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

Given no output schema and zero parameters, the description explains what is returned (categories, labels, unread counts) and a practical note about addressing by name. It is complete enough for a simple list tool, though it could mention if there is any default ordering or maximum items.

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 the baseline is 4. The description does not need to add parameter information, and it correctly uses the space to explain the return content rather than inventing param guidance.

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 categories and user labels with unread counts, and clarifies the difference between categories (folders for feeds) and labels (tags for articles). It also notes they are addressed by name in other tools, fully distinguishing its purpose from sibling tools like list_feeds or get_unread_counts.

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 for retrieving category and label names with unread counts, and mentions they are used by name elsewhere, but does not explicitly state when to use this tool versus alternatives such as list_feeds (for feeds) or get_unread_counts (which might focus on aggregate counts). No direct when-not or alternative guidance is provided.

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. The description adds value by specifying the returned data (category and unread count), which is not present in the schema or annotations. No contradictions observed.

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 with the core action, then additional context. Every sentence adds value with no redundancy.

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

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

For a simple read-only list tool with no parameters and no output schema, the description fully explains the purpose, output fields, and usage context. It is complete and actionable.

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?

Tool has zero parameters, so baseline is 4. The description adds no parameter detail because none are needed. Schema coverage is 100% trivially.

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 every subscribed feed with category and unread count. It distinguishes itself from siblings like list_articles by recommending starting here before listing articles, and it explains the feedId's role in other tools.

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

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

Explicitly says 'Start here to find out what is subscribed before listing articles', establishing a clear use case and ordering relative to other tools. This provides strong guidance on when to use this tool.

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

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

Beyond the destructiveHint annotation, the description reveals the critical two-step process (confirmation token required) and irreversibility of the action. This adds significant behavioral context that annotations alone do not provide, such as the recovery impossibility.

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 with no superfluous content. It front-loads the core purpose, then concisely explains the two-step process and the irreversible consequence. Every sentence is essential.

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 main points: purpose, two-step mechanism, and irreversibility. However, it omits the 'older_than' date filter parameter, which modifies the scope of articles marked. Given the tool's complexity (6 parameters, no output schema), this is a minor but notable gap.

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

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

With 100% schema coverage, the baseline is 3. The description does not add new meaning beyond the schema's parameter descriptions; it merely mentions the scope types (feed, category, label, stream) without clarifying exclusivity or the optional 'older_than' 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 marks all articles in a feed, category, label, or built-in stream as read, using specific verbs and resources. It distinguishes itself from the sibling 'mark_articles' tool by indicating bulk operations, and the two-step process is explicitly mentioned.

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 the tool is for bulk marking but does not explicitly state when to use it over alternatives like 'mark_articles'. It lacks clear guidance on when not to use it or which scope parameter to choose, leaving the agent to infer usage 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 claims changes are reversible ('All changes are reversible'), which contradicts the annotation 'destructiveHint: true' that implies irreversible or destructive behavior. This is a serious inconsistency. The description also adds useful context (max 100, batch application) but the contradiction undermines trust.

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 cover the tool's purpose, reversibility, and constraints. Every word contributes value; no fluff. Front-loaded with the core action.

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 5 parameters with 100% schema coverage and no output schema, the description explains the key behavioral aspects (reversibility, batch limit, application to all articles). It is sufficient for a straightforward mutation tool, though it could mention that labels are user-created per the 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 adds that all changes are applied to all given articles and that at most 100 articles are allowed per call, which is already in the schema (maxItems). No additional parameter-level meaning is provided beyond what the schema gives.

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 sets read state, star, and user labels on specific articles. It distinguishes from sibling tools like 'mark_all_as_read' which operates on all articles, while 'mark_articles' targets specific ones.

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 explains that changes are reversible by calling with opposite values, and enforces a 100-article limit per call. It does not explicitly contrast with sibling tools like 'mark_all_as_read' or 'list_articles', but the context is clear enough for typical use.

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

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

With no annotations provided, the description carries the full burden. It discloses that feeds and articles keep their assignment (non-destructive behavior) and the resolution order, which are important behavioral traits beyond the basic purpose. It does not mention permissions, idempotency, or error states, but for a rename tool these are adequate.

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, starting with the primary action and then adding nuance and behavioral assurance. Every sentence adds unique information, and there is no redundancy or fluff. It is front-loaded with the most important 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?

The description covers the main behavioral aspects (resolution, preservation of assignments) but does not mention return values or error cases. Since there is no output schema, the agent is left wondering what the tool returns on success or failure. For a simple mutation tool, this is a moderate gap.

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

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

Schema coverage is 100% with descriptive parameter comments. The description adds value by explaining how the 'name' parameter is resolved against categories and labels, which is not in the schema. This additional context helps the agent understand the lookup behavior beyond the schema's mention of 'exactly as in list_categories'.

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 (rename) and the two resources (category or label). It explicitly covers both types, which is more specific than a vague 'rename something'. The sibling distinction is implicitly handled by covering both categories and labels in one 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 explains the resolution order (categories first, then labels), which helps the agent understand how the tool works. However, it does not explicitly contrast with the sibling 'delete_category_or_label' or provide guidance on when to use this tool over alternatives. It also omits prerequisites like listing categories first, though the schema parameter description hints at that.

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 the auto-discovery and download process, plus duration, which adds value beyond the annotations (idempotentHint=false, destructiveHint=false). However, it does not clarify whether subscribing to an already-subscribed feed creates a duplicate or returns an error, leaving an important behavioral gap.

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 with the primary action, and every phrase contributes essential context. 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 modest complexity (3 params, no output schema, minimal annotations), the description adequately covers the core behaviors and side effects. Missing details like return value or error conditions, but acceptable for a straightforward subscribe 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?

Schema coverage is 100%, so baseline is 3. The description reinforces the schema's meaning (e.g., website-to-feed discovery, category auto-creation) but does not add new semantic information beyond what the param descriptions already provide.

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 the verb 'Subscribes to a feed' and distinguishes the resource. The description adds specificity by noting that the URL can be a feed or website, and contrasts with sibling tools like update_feed and unsubscribe_feed through the distinct action of subscribing.

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?

Implies usage context (add a new feed) and provides helpful notes about URL flexibility and potential delay, but does not explicitly state when to use this tool versus alternatives (e.g., update_feed for modifying existing feeds) or when not to use it.

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

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

Annotations already declare destructiveHint=true, but the description goes beyond by detailing the two-step token mechanism and what is lost (articles, read state, stars). It also notes that re-subscribing starts fresh, adding valuable behavioral context.

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

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

Three short sentences, each adding essential information: what is deleted, the two-step process, and irreversibility. No fluff, front-loaded with core action.

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 sufficiently covers behavior, prerequisites, and consequences. For a destructive two-step operation with good annotations, 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 coverage is 100%, so the description adds minimal value over the schema for parameters. However, it clarifies that feed_id comes from list_feeds and confirm_token is from the first call, which is helpful but not essential given the 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 specific verbs ('Deletes') and resources ('feed', 'stored articles, read state and stars'), clearly distinguishing it from sibling tools like subscribe_feed or update_feed. The purpose is uniquely defined.

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 explains the two-step process (first call for token, second call for deletion) and warns about irreversibility, guiding the agent on correct invocation. It does not explicitly mention when not to use it or alternatives, but the context is clear.

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

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

Annotations already provide idempotentHint=true and destructiveHint=false. The description adds that a non-existent category is created and that omitted fields remain unchanged, which clarifies the partial update behavior beyond what annotations convey.

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

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

The description is two sentences long, front-loaded with the purpose, and includes necessary caveats. Every sentence earns its place with no redundant information.

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

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

For a simple update tool with 3 parameters and no output schema, the description covers the core behavior (rename, move, category creation, partial updates). It does not mention return values or prerequisites (e.g., feed must exist), but these are implied by the required feed_id parameter and the tool's purpose.

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 each parameter has a description. The description adds value by tying the parameters together: 'Renames a feed and/or moves it to another category' explains the two actions, and 'Fields that are not given stay unchanged' clarifies the partial update semantics.

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

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

The description states 'Renames a feed and/or moves it to another category,' which is a specific verb (rename/move) and resource (feed). It clearly distinguishes from sibling tools like subscribe_feed, unsubscribe_feed, and rename_category_or_label.

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 explains that categories are created on the fly and fields not provided stay unchanged, giving some usage context. However, it does not explicitly state when to use this tool versus alternatives (e.g., rename_category_or_label) or when not to use it.

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