FeedNest

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

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=true), and the description is consistent with them. It adds the exact-match precondition, which is real behavioral context, but says nothing about failure behavior when the text is not found or what the call returns.

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 sentences, zero filler, with the action stated first and the critical constraint immediately after. Nothing wastes the agent's attention.

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 three-parameter mutation with no output schema, the description covers the core action and its key precondition, while annotations carry the safety and idempotency profile. The remaining gap — what happens when the text is absent or which errors surface — is minor.

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, and the description adds meaning beyond the schema by specifying that 'text' must match the article content exactly — a constraint not present in the schema's generic 'text passage to highlight' wording.

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?

States a specific verb ('Highlight') and resource ('a text passage in an article'), which cleanly distinguishes it from siblings like remove_highlight and get_highlights. It does not explicitly name an alternative, but the verb alone makes the intent 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 supplies a hard precondition ('the text must exist exactly in the article content'), which is genuinely useful invocation guidance. However, it offers no when-to-use vs when-not guidance and never references the create/remove/read siblings, so usage is implied rather than 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=false, idempotentHint=true, and destructiveHint=false. The description's 'add or update' wording corroborates the idempotent upsert profile, but it adds nothing about whether an existing note is overwritten, whether auth is required, or how the operation behaves on conflict.

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 front-loaded sentence with zero filler; the core action and its target are stated immediately.

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 two-parameter tool with full schema coverage and no output schema, the description is close to sufficient. The only missing context is what 'update' means for a pre-existing note and how it relates to get_notes/delete_note.

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 both article_id and content are already documented, including that content accepts text or HTML. The description adds no parameter-level meaning beyond what the schema provides, so the 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?

States a specific verb+resource ('add or update a note') and scopes it to an article, which an agent can act on directly. It does not explicitly differentiate itself from siblings like get_notes or delete_note, though the 'add or update' upsert framing implies the boundary.

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 when-to-use guidance, no prerequisites, and no mention of alternatives such as delete_note. The only hint is the implicit upsert ('add or update'), leaving the agent to infer when this beats any sibling 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?

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds essentially nothing beyond that: it does not say whether the call is idempotent for an existing name, whether the new tag's identifier is returned for later use with tag_article, or anything about permission requirements.

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 front-loaded sentence with no waste. It is appropriately sized for a two-parameter create tool, though it is arguably too brief to earn a 5 given the missing behavioral context.

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 two-parameter create tool with full schema coverage, no output schema, and annotations covering safety, the definition is close to sufficient. The main omission is what the agent gets back (the new tag id) and how that feeds into tag_article.

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%, including the hex format example for 'color', so the schema carries the full burden. The description mentions only the conceptual use of the tag and adds no format, length, or uniqueness constraints beyond the schema. 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?

States a specific verb and resource ('Create a new tag') plus its purpose ('for categorizing articles'), so the agent can tell it apart from delete_tag or tag_article. It stops short of any explicit sibling differentiation, but the creation semantics are 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 on when to use this versus tag_article (which presumably attaches an existing tag to an article) or get_tags. No prerequisites, no mention of whether duplicates are permitted or what happens if the tag already exists.

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 annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, covering the safety profile. The description adds no further behavioral context—it does not mention permanence, recovery, or required permissions beyond what the annotations provide.

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 with no wasted words. It is appropriately sized for a simple deletion tool, though it could be slightly more informative 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 the simplicity of the tool, 100% schema coverage, and annotations that convey the destructive and idempotent nature, the description is minimally adequate. It could still benefit from a note on irreversibility or permissions, but the structured fields fill most gaps.

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

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

Schema description coverage is 100% with a single parameter (article_id) fully documented in the schema. The description adds no extra meaning beyond 'from an article,' so the baseline of 3 applies when the schema already carries the parameter semantics.

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

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

The description states a specific verb ('Delete') and resource ('a note from an article'), making the action clear. It does not explicitly differentiate from sibling tools like remove_highlight or delete_tag, but the resource scope is 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?

There is no guidance on when to use this tool versus alternatives, nor any prerequisites or exclusions mentioned. The description merely states what the tool does without helping an agent decide when to invoke it.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so safety and repeat-call behavior are covered. The description adds one piece of context beyond annotations — that only user-created tags are deletable — but says nothing about irreversibility or what happens to articles carrying the tag.

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 front-loaded sentence with no filler; the verb and key come first. It is efficient, though very terse for a destructive mutation, bordering on under-specification.

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 single-parameter delete tool whose annotations already carry the destructive/idempotent profile and with no output schema, this is roughly adequate. It omits any note on side effects (e.g., tag removed from associated articles), leaving a minor gap for a mutation.

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

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

Schema coverage is 100% and the single parameter (tag_id) is documented in the schema as 'The tag ID to delete.' The description adds no format, sourcing, or lookup guidance beyond confirming the ID key, so the 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?

States a specific verb (Delete) and resource (user-created tag) and the identifying key (ID), so an agent can distinguish it from create_tag and get_tags. The 'user-created' qualifier usefully implies system tags are out of scope, but it does not name a sibling or alternative route.

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 when-to-use, prerequisites, or alternatives are given. The 'user-created' phrasing implicitly signals that system/protected tags cannot be targeted, and the destructive nature of the operation is obvious from the verb, but usage is left to inference rather than 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 openWorldHint=true (external fetch) and idempotentHint=true, and the description corroborates the external-source behavior. However, readOnlyHint=false is unusual for a fetch and the description never explains the side effect this implies (e.g. caching/storing the fetched text) or what happens if the publisher page is unreachable.

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?

One sentence, front-loaded with the action and resource, with the motivating condition trailing as a qualifier. 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?

For a one-param fetch with no output schema, the description conveys the essential behavior and return intent ('full text'). Minor gaps remain around failure modes and the non-read-only side effect flagged by annotations.

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

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

The single parameter is fully documented in the schema (article_id: 'The article ID to extract content for'), so the schema does the heavy lifting. The description adds no format, sourcing, or constraint detail beyond what the schema states; 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?

States a specific verb ('Fetch'), resource ('full text of an article'), and source ('publisher's original page'), plus the motivating condition ('feeds that publish only an excerpt'). This clearly distinguishes it from the sibling get_article, which presumably returns stored content.

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

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

Gives a clear trigger condition: use it when the feed only publishes an excerpt. It does not explicitly name get_article as the alternative for when full content is already stored, so the routing is implied rather than spelled out.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: the returned payload includes highlights, notes, and estimated reading time, and some feeds publish only an excerpt, which warns the agent that content may be incomplete. It stops short of stating error behavior for a missing/unfetchable article.

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 tight sentences, front-loaded with the primary action and payload, followed by a single caveat that earns its place by warning about partial content. No filler or restated name/title.

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

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

With no output schema, the description does the work of summarizing return contents (content, highlights, notes, reading time), and the annotations cover the safety profile. The main remaining gap is failure behavior for an invalid or unfetchable article ID.

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?

One parameter with 100% schema description coverage ('The article ID.'), so the schema carries the semantics and the baseline is 3. The description adds no format hints (e.g., where the ID comes from or whether it is a feed item GUID), so it does not exceed baseline.

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

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

States a specific verb+resource (get an article's content) and enumerates what comes back: content, highlights, notes, estimated reading time. That payload list implicitly separates it from list-oriented siblings like get_articles and from extract_article, but it never names or contrasts an alternative, so it falls short of the sibling-differentiation bar for a 5.

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?

Usage is only implied: an agent can infer 'call this with an article ID to read that article.' There is no when-to-use statement, no exclusions, and no routing between this and extract_article or get_articles, which are plausible alternatives for the same intent.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior, so safety is covered. The description adds that results carry a summary preview and that count_only collapses the response to a count, but says nothing about pagination via the before_id/before_published_at cursors or result ordering defaults.

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 behavior; the compact view list is efficient. Slightly list-heavy but no wasted filler for a 13-parameter tool.

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

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

With no output schema, the description usefully names the returned fields, which covers the gap. However, for a 13-parameter list tool it omits pagination behavior and sorting defaults, leaving an agent to guess how to page through results.

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

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

Schema description coverage is 100%, so every parameter is already documented, including count_only's semantics and the required feed_id/tag_id/folder_id conditionals. The description's view enumeration and count_only note largely restate the schema rather than adding new meaning.

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?

States a specific verb and resource ('List articles') and names the fields returned (title, source, date, summary preview), which is more than a restatement of the title. It does not distinguish itself from closely related siblings like get_saved, get_recently_read, or get_article, whose scopes overlap with the listed views.

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 enumerated views ('newsfeed, by-feed, by-folder, by-tag, tagged, highlighted, noted') imply the available scopes, but the description never says when to prefer this tool over get_saved, get_recently_read, or get_article. Usage must be inferred from the view list rather than 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, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds that unread counts are included, which is useful context, but says nothing about pagination behavior despite the keyset cursors in 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?

A single sentence that front-loads the resource and the payload, with the optional filtering clause last. 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?

No output schema exists, but the description discloses the key return element (unread counts). Pagination via before_id/before_name is documented in the schema but not surfaced in the description, which is a minor gap for a list tool with cursors.

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 limit, query, folder_id and both cursors are already documented in the schema. The description only restates the name/folder filtering, adding no syntax or format detail beyond what the schema provides. 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?

Specific verb+resource ('List subscribed feeds') plus the returned payload ('with unread counts') and the filter dimension ('by name or folder'). This clearly separates it from get_folders and get_output_feeds, though it never names those siblings explicitly.

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

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

The phrase 'optionally filtered by name or folder' implies when the query/folder_id parameters are relevant, but there is no explicit when-to-use guidance, no exclusions, and no routing to sibling tools like get_folders or get_articles.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered without the description. The description adds one useful piece of behavior — that results include per-folder feed counts — but says nothing about ordering, nesting, empty folders, or pagination.

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 front-loaded sentence that carries both the scope and the shape of the result with no filler.

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

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

For a zero-parameter read-only listing tool with full annotation coverage and no output schema, the description tells the agent what it gets back (folders plus feed counts). Minor gaps remain around ordering and whether folders are flat or nested.

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 takes zero parameters, so the baseline is 4; there is nothing for the description to disambiguate.

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?

States a specific verb (List) and resource (feed folders) and adds what each entry contains (number of feeds). The resource name distinguishes it from get_feeds/get_output_feeds, though it never explicitly contrasts itself with those 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?

No when-to-use or when-not-to-use guidance, and no mention of alternatives such as get_feeds. Usage is only inferable from the name and resource, which is the definition of implied/absent guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered without the description. The description's only added context is the word 'all' and 'text' (as opposed to notes or other annotation types), which is thin behavioral 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?

A single short sentence with the resource and scope front-loaded; there is no filler or redundancy.

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

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

For a simple single-parameter read tool whose annotations carry the full safety profile, the description is essentially complete and does indicate what is returned (all text highlights). It could note return shape or empty-result behavior, but no output schema exists so 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?

With one parameter at 100% schema description coverage, the schema already documents article_id. The description adds no format, ID syntax, or behavioral detail beyond what the schema provides, so the baseline of 3 applies.

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

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

The description gives a specific verb and resource: retrieve all text highlights belonging to a given article. It implicitly distinguishes itself from get_notes (different resource) and add_highlight/remove_highlight (different operations), but never names or contrasts those siblings explicitly.

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

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

There is no statement of when to use this tool versus alternatives such as get_notes or get_article. Usage is only weakly implied by the phrase 'from an article' and by the required article_id parameter; no prerequisites 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?

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and closed-world, fully covering the safety profile. The description adds no behavioral context beyond that—no note about multiplicity, ordering, or empty results—so it contributes essentially nothing beyond structured fields.

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

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

A single short sentence with no wasted words and the resource front-loaded. It is appropriately sized for a simple getter, though the extreme brevity borders on under-specification.

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 a one-parameter read tool with full schema coverage and complete safety annotations, the description is minimally sufficient. It does not address return shape or note multiplicity, but for this complexity level that is a tolerable gap rather than a fatal one.

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 is a single required parameter with 100% schema description coverage, so the schema already documents article_id. The description's phrase 'on an article' loosely maps to it but adds no format or constraint detail beyond the schema baseline.

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

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

States a clear verb+resource ('Get the note') scoped to an article. It is distinguishable from get_highlights by naming 'note,' though it never explicitly contrasts with sibling note/highlight tools and the singular 'the note' leaves ambiguity about whether multiple notes per article exist.

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

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

The description gives no when-to-use guidance, no prerequisites, and no routing to alternatives such as get_highlights or get_article. The agent is left to infer usage purely from the name.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and closed-world behavior, so the safety profile is covered. The description adds useful scope by specifying 'public RSS output feeds created by the user,' but does not describe return format, pagination, or authentication needs.

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 is front-loaded and contains no wasted words. It is appropriately sized for a simple list operation with no parameters.

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 zero-parameter read operation and rich annotations, the description is nearly complete. It lacks only minor contextual details such as return format or whether pagination applies, but nothing critical for invocation is missing.

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

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

The tool takes zero parameters, so there are no parameter semantics for the description to clarify. The baseline for a zero-parameter tool is 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?

States a specific verb and resource: listing output feeds, scoped to public RSS feeds created by the user. It distinguishes 'output feeds' from general feeds, but does not explicitly differentiate from sibling get_feeds, which is the closest alternative.

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 no guidance on when to use this tool versus get_feeds or other sibling feed-listing tools. The implied context is listing the user's output feeds, but no alternatives or exclusions are 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, idempotentHint=true, destructiveHint=false and a closed-world scope, so the safety profile is fully covered. The description contributes the ordering guarantee and the availability of pagination/date filtering, but says nothing about return shape, page-size caps, or how the two keyset cursors must be paired.

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 tight sentences with the core behavior front-loaded and no filler. The second sentence is somewhat generic boilerplate ('supports pagination and date filtering') but earns its place by flagging cap ability the agent might otherwise miss.

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 read-only list tool with no output schema, the description names the ordering, the filtering dimension and the pagination capability, which matches the schema's surface area. It does not explain the keyset cursor pairing (before_id + before_opened_at) or what fields come back, but annotations carry the safety profile.

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% across all 7 parameters, so the schema already explains sort, limit, query, since/date_to and the two cursors. The description's 'pagination and date filtering' phrasing adds thematic grouping but no syntax or pairing rules 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?

States a specific verb+resource ('Get recently read articles') plus the ordering rule ('ordered by when they were opened'), which cleanly separates it from read-later siblings like get_saved and get_articles. It never names a sibling explicitly, so it stops short of full differentiation.

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 'recently read' scope implies when an agent would reach for this over get_articles or get_saved, but there is no explicit when-to-use statement and no named alternative. Usage is inferable rather than 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, idempotentHint, non-destructive, and openWorld=false, so the safety profile is fully covered. The description adds the feature set (pagination/search/date/sort), which is useful context but stops short of explaining pagination mechanics or result ordering beyond what the schema hints.

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

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

Two tight sentences, front-loaded with the resource and followed by the capability summary. No filler, though the second sentence is essentially a keyword list rather than value-adding guidance.

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

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

With 7 optional parameters, full schema coverage, and annotations covering the safety profile, the definition is serviceable; there is no output schema, so return shape need not be explained. The remaining gap is the lack of sibling differentiation, which matters given many overlapping listing tools.

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 every parameter is already documented. The description's feature list (pagination, search, date filtering, sorting) loosely maps to query, date_from/date_to, sort, and the before_* cursors but adds no syntax, defaults, or format detail 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?

States a clear verb and resource ("List saved articles") and the "saved" qualifier scopes it to saved content. However, it never distinguishes this from close siblings like get_articles, get_recently_read, or get_highlights, so an agent must guess which listing tool applies.

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 second sentence enumerates capabilities (pagination, search, date filtering, sorting) but gives no when-to-use guidance, no exclusions, and no mention of alternative listing tools. Nothing tells the agent when this beats get_articles or get_recently_read.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false and destructiveHint=false, so the safety profile is fully covered structurally. The description earns credit by disclosing what the payload actually contains (the six metric names), which is genuinely useful for a tool with no output schema. It does not state units or freshness (e.g. how 'streak' or 'reading time' is computed), which keeps it short of a 5.

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 front-loaded sentence with the verb first and the payload enumerated in a compact colon list. No filler, no restatement of the title, everything 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?

With no output schema, the description does the work of naming the returned fields, which is exactly what an agent needs here. It is nearly complete, missing only unit/semantic detail for ambiguous metrics like reading time and streak.

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 takes zero parameters, so per the rubric the baseline is 4; there is nothing for the description to disambiguate. It correctly avoids inventing parameters and simply implies a parameterless global call.

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?

States a specific verb ('Get') plus the resource ('reading statistics') and enumerates the exact metrics returned: streak, articles read today, reading time, total feeds, unread count, saved count. This clearly distinguishes it from data-fetching siblings like get_articles, get_feeds, or get_recently_read.

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?

Usage is implied by the aggregation nature of the tool: an agent wanting an overview of reading activity would pick it, and no sibling provides a comparable aggregate. However, there is no explicit when-to-use statement, no mention of when a per-item tool (get_articles, get_saved) would be preferable, and no prerequisites noted.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds modest extra context by specifying that only user-defined tags are returned and that counts accompany them, but it says nothing about ordering, pagination, or whether zero-article tags appear.

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 with no filler, front-loading the verb and resource and appending the return detail in the same clause. 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?

For a no-argument, read-only list tool the description is nearly sufficient: it says what is listed and roughly what comes back. With no output schema, a little more detail on the result shape (count field, ordering, inclusion of unlabeled/zero-count tags) would make it fully 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?

The tool takes zero parameters, which is the baseline-4 case; there is no parameter semantics to explain. The description correctly signals that no filtering input is accepted by framing the result as "all" tags.

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?

States a specific verb+resource ("List all ... tags") and adds two useful qualifiers: the scope is user-defined tags and the payload includes article counts. The list verb inherently separates it from the create_tag/delete_tag/tag_article siblings without needing to name 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?

There is no explicit when-to-use or when-not-to-use statement and no named alternative, so usage is only implied by the verb. For a zero-parameter, side-effect-free listing tool this is tolerable, but guidance about how it relates to get_stats or the tag-mutation tools is absent.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description adds only the scoping behavior; it says nothing about reversibility, permission requirements, or how many articles are affected.

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 front-loaded sentence with no filler; the scope constraint follows immediately after the action, which is exactly the right ordering.

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 no-required-param bulk mutation with annotations carrying the destructive/idempotent flags and no output schema, the description is close to sufficient. The only real gap is whether feed_id and folder_id are mutually exclusive or combinable.

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 both feed_id and folder_id are already documented in the schema. The description merely restates their combined effect ('limited to one feed or folder') without adding format, precedence, or mutual-exclusion 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?

States a specific verb and resource (mark articles as read) plus the scope option (all, or one feed/folder). It is clearly distinguishable from the sibling mark_as_read by the word 'all', though it never explicitly contrasts with that sibling.

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

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

The description implies usage through 'optionally limited to one feed or folder', telling the agent it can scope the bulk operation. It does not state when to prefer this over mark_as_read/mark_as_unread, nor what happens if both feed_id and folder_id are supplied.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety and repeat-call profile is covered externally. The description adds no behavioral context of its own — nothing about effect on unread counts, whether it is reversible, or required auth.

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 short sentence with no filler and the verb front-loaded. It is efficient, though the austerity means it carries no extra routing value.

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

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

For a one-parameter mutation tool whose annotations already cover idempotency and safety, this is minimally sufficient. It stops short of explaining what marking read does downstream or pointing to mark_as_unread as the undo path, which would round out the picture.

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 a single parameter at 100% schema description coverage, the schema fully documents 'article_id'. The description adds no format or sourcing information beyond what the schema already provides, so the 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?

The description states a specific verb ('Mark') and resource ('an article') with the target state ('as read'), so the action is unambiguous. However, it does nothing to distinguish itself from the siblings mark_all_as_read and mark_as_unread, which an agent must choose between.

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?

There is no guidance on when to use this over mark_all_as_read or mark_as_unread, nor any prerequisites (e.g., that the article must already exist or be saved). The agent must infer scope from the name 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?

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false, and openWorldHint=false, covering the safety profile. The description adds nothing beyond that — no mention of what state changes, whether it syncs to a server, or whether it can be reversed.

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 tight sentence with no filler and the action front-loaded. It is efficient, though it is arguably too terse for a state-mutating tool rather than genuinely 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?

For a one-parameter toggle with annotations covering the safety profile and no output schema, the description is minimally sufficient. It still omits any statement of scope (single article only) relative to mark_all_as_read, which is the main 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 description coverage is 100% for the single article_id parameter, so the schema fully documents its meaning. The description adds no format or sourcing details beyond what the schema already provides; 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?

States a specific verb ('Mark') and resource ('an article') with the target state ('unread'), which is unambiguous. However, it does nothing to differentiate itself from the sibling tools mark_as_read and mark_all_as_read beyond the literal name.

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 on when to use this versus mark_as_read, mark_all_as_read, or unsave_article. The usage is only implied by the name itself; there are no prerequisites, conditions, or exclusions 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 destructiveHint=true, idempotentHint=true, readOnlyHint=false, and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds nothing beyond that - no note on irreversibility, permission requirements, or what happens if the highlight_id does not exist.

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 front-loaded sentence with zero filler; the verb and scope land immediately. It is efficient, though the brevity edges toward under-specification rather than tight 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?

For a two-parameter, non-open-world delete with full annotation coverage and no output schema, the description is minimally sufficient. It omits any mention of error behavior or confirmation semantics, which would be the remaining useful additions.

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

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

Schema description coverage is 100%, with both article_id and highlight_id documented in the schema itself, so the baseline is 3. The description adds no syntax, format, or scoping detail beyond what the schema already 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?

States a specific verb (Remove) and resource (a highlight from an article), which is unambiguous and clearly distinguishable from the sibling add_highlight. It does not, however, differentiate itself from other delete-style siblings such as delete_note or delete_tag beyond the resource noun.

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?

There is no guidance on when to use this tool versus alternatives, no prerequisites, and no exclusions. The agent must infer usage purely from the verb 'Remove'.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds only the user-facing effect ("for later reading", i.e., it lands in the saved/reading list), and says nothing about auth needs or whether an unknown article_id errors. A modest but non-zero addition over the structured 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?

A single short sentence with the verb front-loaded and no filler. It is not padded, though it is arguably too terse given the sibling collision.

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 one-parameter toggle tool with annotations covering safety and no output schema, the description is minimally adequate. It leaves unresolved how it relates to save_url, unsave_article, and get_saved — the exact relationships an agent needs in this crowded bookmarking toolset.

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 one parameter and 100% schema description coverage, the schema fully documents article_id. The description adds no format, source, or validity detail (e.g., where the ID comes from), so the baseline of 3 is appropriate.

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

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

The description gives a specific verb+resource ("Save an article") and adds the intent ("for later reading"), so the action is unambiguous. However, it does nothing to distinguish itself from the sibling save_url, which likely saves from a link rather than an existing article ID — the agent must infer the difference.

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?

There is no when-to-use guidance: nothing says this applies to articles already fetched (via get_article/extract_article) versus save_url, and no mention that unsave_article reverses it. With a near-duplicate sibling name, this omission is a real selection hazard.

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

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

Annotations already declare readOnlyHint=false, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds nothing behavioral on top: it doesn't say whether repeat saves are idempotent, what happens to an already-saved URL, or whether authentication is needed for external fetching.

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 short sentence, front-loaded with the verb and resource, with no wasted words. It is appropriately sized for a one-parameter tool.

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

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

For a trivial one-param write tool with annotations and no output schema, the description is minimally viable but leaves real gaps: duplicate-URL handling, what is returned, and how it differs from save_article are all unstated.

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

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

Schema description coverage is 100% and the only parameter is already documented with format=uri. The description adds no syntax or format detail beyond the schema, so the 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?

States a specific verb (Save) and resource (external URL) with the intent ('for later reading'). However, it does not distinguish itself from the close sibling save_article, leaving the agent to guess which of the two applies to a given URL.

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 when-to-use guidance, no prerequisites, and no mention of the obviously competing siblings save_article/unsave_article. The agent gets no help deciding between saving a raw URL versus saving an article.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds only the useful fact that this is a dual-mode operation (add or remove in one call), which matches the action enum and contradicts nothing. It says nothing about auth needs or behavior when the tag is already present/absent, which the idempotent hint partially covers.

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 front-loaded sentence with zero filler; the verb pair and target resource appear immediately. Nothing in it is redundant with the title in a wasteful way.

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 three-parameter mutation with no output schema, the definition covers the core action but leaves open whether remove errors when the tag is not applied, whether the tag must pre-exist, and what the call returns. The idempotentHint annotation absorbs some of this, so the gap is moderate rather than severe.

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% and all three parameters are documented in the schema, including the add/remove enum. The description restates the same add/remove distinction and adds no format or constraint detail beyond the schema, so the 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?

The description gives a specific verb pair plus resource: add or remove a tag on an article. That cleanly separates it from create_tag/delete_tag (which manage tag entities) and save_article/unsave_article (which manage article state), though it never names those siblings explicitly.

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

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

There is no when-to-use guidance, no prerequisites (e.g., the tag presumably must already exist via create_tag), and no mention of the neighboring tools that could be confused with it. Usage is only inferable from the tool name.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=true, so the safety profile is covered. The phrase 'from saved items' adds useful context that the article itself is not deleted, just unlinked from the saved list – a genuine clarification beyond the annotations, but nothing about permissions or response 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?

A single six-word sentence with zero filler, front-loaded with the verb and scope. Nothing is wasted.

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

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

For a one-parameter, non-destructive toggle whose annotations carry the safety profile and whose schema fully documents the argument, the description is nearly sufficient. Routing to save_article as its counterpart is the only notable omission.

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 a single fully documented required parameter (article_id). The description adds no format, source, or lookup detail beyond what the schema already states, 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?

States a specific verb ('Remove') and resource ('article from saved items'), which is directly the inverse of the sibling save_article. However, it never names save_article or any other sibling, so differentiation relies on the agent inferring the pairing from names alone.

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

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

The description gives no when-to-use or when-not-to-use guidance and names no alternative. An agent must infer from the name alone that this is the undo of save_article rather than a delete of the article itself.

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