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

Annotations already declare readOnlyHint=true, and the description adds behavioral context by stating it checks whether the session is 'still valid' and which account it belongs to, implying session expiry and account association. It does not contradict annotations and adds detail about the membership check, which is useful beyond the read-only flag.

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, well-structured sentence that front-loads the verb 'Check' and packs all relevant checks into a compact list with a parenthetical clarification ('needed for member-only posts'). Every phrase adds value, with no redundant or filler 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 zero-parameter status tool, the description covers the essential decision factors: configuration, validity, account identity, and membership. It does not specify the return format, but the absence of an output schema and the simple status-check nature make this acceptable; the agent can infer the result from the described checks.

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

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

The input schema has zero parameters and schema description coverage is trivially 100%. With no parameters to document, the baseline is 4; the description appropriately focuses on the tool's outcome rather than inputs, and there is nothing further it needs to clarify about parameters.

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

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

The description uses the specific verb 'Check' and names the exact resource (Medium session/account) and the four things it verifies: configuration, validity, account identity, and membership. This clearly distinguishes it from sibling tools like read_post or follow, which perform actions rather than report status.

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 by explaining that membership is needed for member-only posts, implicitly telling the agent when this check is useful. It does not explicitly name when-not scenarios or alternative tools, but no sibling tool competes with this status check, so the guidance is adequate though not exhaustive.

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 indicate this is a mutating, non-idempotent operation. The description adds genuinely useful behavioral context beyond the annotations: the 50-clap per-reader limit and that the tool 'refuses to go past that.' This helps set expectations for side effects and edge cases without contradicting any 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?

Three sentences with no filler. The core action is front-loaded, the key behavioral constraint (50 claps) is stated succinctly, and the alternative tool is mentioned in one short phrase. 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?

For a simple two-parameter tool with no output schema, the description covers the essential action, a behavioral limitation, and the reverse operation. It doesn't discuss error cases or authentication, but annotations and the schema already provide the safety profile and parameter constraints. It is complete enough for correct invocation.

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

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

Schema description coverage is 50% (only 'post' is described in the schema), so the description should compensate for the undocumented 'count' parameter. It mentions the 50-clap ceiling, which relates to count's maximum, but it doesn't explicitly state that 'count' is the number of claps to give. The description adds partial value but doesn't fully clarify parameter semantics.

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

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

The description clearly states the action ('Clap for a post') and the resource (a post), plus a notable consequence (visible to its author). It also explicitly distinguishes itself from the sibling undo_clap, making the tool's purpose and scope immediately 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?

It gives an explicit activation condition ('Only use when the user asks') and names the alternative for reversing the action ('undo_clap takes them back'). This is direct, practical guidance that tells an agent exactly when to invoke this tool versus the sibling.

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, so 'Does nothing if already following' reinforces but adds specific side-effect behavior. The description also discloses that ambiguous names return candidates, which is valuable because no output schema exists. It adds context beyond the structured hints without contradicting them.

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

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

Four short sentences, each earning its place: the core action, idempotence, usage restriction, and ambiguity handling. No filler or repetition.

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

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

For a single-parameter, low-complexity tool, the description covers the key agent needs: what to do, when to do it, and how to handle ambiguity. It does not state the success response format, but the absence of an output schema makes this a minor gap rather than a blocking 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?

The input schema provides 100% description coverage for the target parameter, including formats for authors and publications. The tool description itself adds no additional parameter meaning, 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 states a specific verb and resource: 'Follow an author or publication.' This clearly distinguishes the tool from siblings like unfollow and save_to_list, and clarifies what 'follow' means.

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

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

The description gives explicit guidance: 'Only use when the user explicitly asks' — a clear when-to-use condition. It also explains what to do in the ambiguous-name case. It does not name alternatives, but the restriction to explicit user intent effectively excludes auto-following.

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 readOnlyHint and openWorldHint annotations already cover the safety and dynamic nature of the operation. The description adds value beyond those by explaining the two feed modes and the pagination contract ('Pass nextCursor back as cursor'), which are behavioral details an agent needs to use the tool correctly.

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 no filler: the first defines the resource, the second explains the input variants and pagination. It is front-loaded with the main concept and 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?

The description covers the core purpose, feed variants, and pagination, but with no output schema it does not describe the shape of feed items or how to identify a post for subsequent operations. The resource and parameters are clear enough for invocation, but an agent may need more context about the response.

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 50% (since and cursor are documented). The description adds meaning to the 'feed' enum and restates cursor usage, which is helpful. However, it does not add anything for 'limit' or expand on the 'since' format, leaving the agent to rely solely on the schema for those.

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 this returns the user's home feed and defines the two feed variants, which makes the resource specific. It does not explicitly contrast with siblings like get_recent_posts or search_posts, 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 description explains that 'following' returns posts from followed authors/publications and 'for_you' returns recommendations, which implies how to choose between them. However, it gives no guidance on when to use get_feed versus sibling tools such as get_recent_posts or search_posts, so the tool-selection guidance is only implicit.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the description doesn't need to cover those. It does add the ordering (most recently added first), which is useful, but it omits details like pagination behavior via cursor or error handling when a list is not found. The added context is minimal but not contradictory.

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, focused sentence that states the primary action and ordering. It's efficient with no redundancy and front-loads the core purpose.

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 retrieval tool with open-world semantics and no output schema, the description is minimally sufficient but lacks usage guidance and pagination details. The schema covers parameters well, so the main gap is absence of when-to-use context, which would round out completeness.

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

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

Schema description coverage is 67% (list and cursor have descriptions, limit does not). The description adds no parameter-specific information beyond what's already in the schema. Since coverage is above 50%, the baseline of 3 is appropriate; the description doesn't compensate for the undocumented limit 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 retrieves posts from a reading list or named lists, ordered by most recent first. This distinguishes it from siblings like get_feed, get_recent_posts, and search_posts by identifying the specific resource (lists) and the ordering behavior.

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

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

The description provides no guidance on when to choose this tool over alternatives. It doesn't compare with get_feed or get_recent_posts, nor does it mention prerequisites like needing a list name from list_reading_lists. Usage context is entirely implied, not explicit.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, covering safety and world-scope. The description adds useful behavioral context beyond annotations: it establishes the 'latest posts' ordering and discloses pagination behavior via 'Pass nextCursor back as `cursor` to page back.' This meaningfully enriches the agent's understanding of call behavior without repeating annotation 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?

Two sentences carry all essential information: the first declares the tool's purpose, the second gives the pagination contract. There is zero filler or redundancy. The most important information is front-loaded, making it easy for an agent to parse quickly.

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 3-parameter, read-only list tool with no output schema, the description covers the core invocation requirements: source scope and pagination. It doesn't describe the shape of returned posts, but the name and title 'Get recent posts' make that implicit. Given annotations cover the safety profile and schema covers parameter details, the description is sufficiently complete for correct calling.

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 67%: `source` and `cursor` already have detailed descriptions, while `limit` has none. The description adds only marginal value to parameter meaning—mostly restating cursor and pagination semantics. It does not clarify the `limit` parameter, which remains undocumented beyond its type/default/max/min, so a baseline 3 is appropriate.

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

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

The description states a specific verb+resource: 'Latest posts from one author or publication.' This clearly identifies what the tool does and narrows scope to a single source, which helps distinguish it from broader tools like get_feed or search_posts. However, it doesn't explicitly name sibling tools or contrast its behavior, so it falls short of 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?

The phrase 'from one author or publication' provides clear context for when to use this tool – when you need posts from a known, specific source. It does not explicitly mention alternatives or exclusions, but the scope is unambiguous. The pagination instruction adds a clear usage note about handling result sets, so the intended use case is well implied.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the description's job is lighter. It adds useful behavioral context by scoping results to the logged-in user and mentioning the total count in the response. It does not contradict the annotations, though it does not disclose pagination behavior beyond what the schema's cursor description already provides.

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 primary choice (authors vs publications), states the scope (logged-in user), and includes the notable response detail (total count). There is no filler or redundant wording.

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 endpoint with no required parameters, the description plus annotations and schema-provided cursor/limit constraints are largely sufficient. The lack of an output schema is partly mitigated by mentioning the total count, though item-level response fields are not described.

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 clarifies the key enum parameter by mapping 'users' to 'Authors' and noting the default. However, schema description coverage is only 33%, and the description does not add meaning for limit or further explain cursor beyond the schema's 'nextCursor from a previous call' note, so compensation is only partial.

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

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

The description uses a specific verb ('list') and a precise resource scope: authors or publications followed by the logged-in user. It also adds the total-count detail, making the tool's purpose unmistakable and distinguishing it from siblings like get_feed or list_reading_lists.

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 guidance or mention of alternatives such as get_feed or get_list. Usage is implied by the description's phrasing but not spelled out, so an agent must infer when this tool is appropriate.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safe read-only nature is covered. The description adds useful context by specifying both the default reading list and named lists, plus item counts, which helps set expectations for the output. It does not mention ordering, pagination, or whether empty lists are included, but for a simple read-only listing this is acceptable.

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, focused sentence that conveys the scope and key output detail without wasted words. It is front-loaded with the main object ('the user's reading list') and ends with the distinguishing count detail.

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 no output schema, the description adequately explains what the agent will receive: the saved-posts reading list and named lists with item counts. It could be more explicit about the exact return shape or whether the default list is included separately, but the essential information is present.

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

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

The tool has zero parameters and schema coverage is 100%, so there is no parameter information burden on the description. The description appropriately avoids inventing parameter details and instead communicates what the result contains, which is the relevant semantic information here.

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 identifies the resource—the user's reading list and named lists—and specifies that item counts are included. It stops short of an explicit verb like 'returns' or 'lists', but the meaning is unambiguous. It also implicitly distinguishes itself from get_list by focusing on list overviews with counts rather than list contents.

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

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

No guidance is given about when to use this tool versus alternatives such as get_list or get_feed. The description implies it is for viewing a summary of saved posts and named lists, but it provides no exclusions, prerequisites, or explicit routing to sibling tools.

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

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

Annotations already establish read-only/open-world behavior; the description adds meaningful behavioral context: member-only posts are fully returned only for members, custom domains work, and long posts are paged with start. It does not cover non-member behavior or max_chars effects, but the provided disclosures go beyond annotations.

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

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

Three concise, front-loaded sentences: the core purpose comes first, then membership and domain caveats, then the paging mechanism. Every sentence contributes without redundancy.

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

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

Without an output schema, the description does explain the return form (Markdown) and paging contract, which is helpful. But it omits the behavior of max_chars and the text format option, leaving important gaps for a four-parameter tool.

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

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

Schema description coverage is 50%, and the description adds meaning for start by explaining pagination and notes Markdown as the output format. However, max_chars is left completely unexplained and the format='text' option is not mentioned, so the description does not fully compensate for the schema gaps.

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

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

The description clearly states the action ('Read a Medium post') and output format ('as Markdown'), which distinguishes it from feed/list tools like get_feed or get_recent_posts. The additional scope notes about custom domains and member-only posts sharpen the purpose further.

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

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

The description implies usage by URL and adds useful context about custom domains and membership, but it never names alternatives or says when not to use this tool versus siblings like search_posts or get_recent_posts. No explicit when/when-not routing 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 destructiveHint=true and idempotentHint=true, so the description doesn't need to restate those. It adds context about the default list and named lists, plus the user-intent condition. However, it doesn't describe side effects like behavior on missing posts or idempotency details, which are partially covered by annotations. With annotations present, this is moderate 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 two sentences with zero fluff. The core action is front-loaded ('Remove a post...'), and the usage condition is a separate concise sentence. Every word contributes to understanding when and how to use the tool.

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

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

For a simple mutation tool with only two parameters and no output schema, the description covers the essential action, default scope, and user-intent condition. Annotations handle the destructive and idempotent profile, and the schema references list_reading_lists for list names. It doesn't explain edge cases, but nothing critical is missing for correct invocation.

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

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

Schema description coverage is 100% – both parameters have detailed descriptions (post URL/hex id, list default and reference to list_reading_lists). The tool description adds no additional meaning to the parameters beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description states a clear, specific action: 'Remove a post from the reading list (default) or one of the user's named lists.' It distinguishes from sibling tools like save_to_list (opposite) and list_reading_lists (list names) by focusing on removal and specifying the default list. No ambiguity about what the tool does.

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

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

The description explicitly says 'Only use when the user asks,' which sets a clear usage boundary. It does not explicitly name alternatives or when-not to use, but the schema references list_reading_lists for list names, and the purpose itself implies when it's appropriate. This is clear context but lacks explicit exclusions.

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 indicate the tool is mutating and idempotent. The description adds concrete behavioral detail with 'Does nothing if it's already there' and the default-list behavior, which helps the agent predict outcomes without contradicting the annotations.

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

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

The description is three short sentences with no filler. The key action, default behavior, idempotency, and usage guardrail are all front-loaded and each sentence adds value.

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

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

For a simple two-parameter tool with annotations and full schema coverage, the description is adequately complete. It covers the action, default, duplicate behavior, and the condition to invoke it; no critical operational details are missing.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description mainly restates the default list behavior and does not add material parameter-level 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?

The description uses a specific verb ('Save') and a clearly defined resource (a post to a list). It also distinguishes itself from sibling tools like remove_from_list and list_reading_lists by explicitly stating the default reading list and named-list behavior.

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

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

The description provides clear context for when to use the tool ('Only use when the user asks') and explains the default and named-list targets. It does not explicitly name alternatives or when-not-to-use conditions, but the purpose is distinct enough among siblings.

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 establish read-only and open-world behavior. The description adds a non-obvious pagination contract: nextCursor must be passed back as page for subsequent results. This is useful behavioral context 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?

Two sentences, front-loaded with purpose and followed by actionable pagination guidance. Every sentence earns its place 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?

Invocation-critical details are covered: read-only scope, keyword search, and pagination. Since there is no output schema, the description could say a bit more about what the response contains beyond nextCursor, but for a search tool this is largely sufficient.

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 0%, so the description must compensate. It adds meaning for query (keyword) and page (pagination via nextCursor), but limit is never mentioned. The parameter names and defaults are somewhat self-explanatory, but coverage is only partial.

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: 'Search all of Medium for posts by keyword.' This clearly distinguishes it from sibling tools like get_feed and get_recent_posts, which are scoped or personalized rather than a global keyword search.

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 clear context for when to use the tool: when the user wants a global Medium keyword search. It does not explicitly name alternatives or exclusions, but the 'all of Medium' scope makes the intended use distinct from feed/list/reading-list tools.

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

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

The annotations already indicate destructiveHint and readOnlyHint=false, so the description's 'Remove all' is consistent with those. It adds context that it affects the user's claps, which is useful, but it doesn't mention any side effects like irreversibility or permission requirements beyond what annotations imply. It adds some value but does not go beyond the annotation's baseline significantly.

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

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

The description is extremely concise, one sentence long, and front-loads the action. Every word is meaningful. It loses a point because it lacks any structural organization, but for its brevity it is well-formed.

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

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

The tool is simple with one parameter, no output schema, and annotations cover safety (destructive hint). The description tells the agent when to use it. It is adequate but could mention that it only removes claps made by the current user and any potential need for authentication, though that is likely implied by 'the user's claps'.

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

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

The schema covers the parameter 'post' with a clear description (URL or hex id), so the description adds no additional parameter semantics. With 100% schema coverage, the baseline is 3, and the description does not enhance it.

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

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

The description clearly states the action (remove claps) and the resource (a post), and specifies it applies to 'the user's claps'. It is distinct from its sibling 'clap', which adds claps, and from other read/list tools. However, it does not explicitly name the sibling it contrasts with, so it misses the top score.

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

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

It says 'Only use when the user asks', which gives a clear trigger condition. However, it does not specify when NOT to use it or mention any alternatives, such as 'clap' for adding claps. The instruction is useful but lacks exclusionary guidance, making it adequate but not comprehensive.

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 and destructiveHint=true, covering the mutation and destructive nature. The description adds valuable context: the ambiguity handling (candidates returned) and the explicit user request requirement. No contradiction with annotations.

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

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

Three concise sentences with zero redundancy. The core action is front-loaded, followed by critical usage and ambiguity guidance. 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?

For a single-parameter tool with no output schema and annotations covering the safety profile, the description is complete. It covers what, when, and how to handle ambiguity, leaving no critical gap for correct invocation.

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

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

Schema description coverage is 100%, so the parameter is fully documented. The description adds behavioral meaning beyond the schema by explaining that ambiguous names return candidates for user disambiguation, which enriches the parameter's 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 and resource ('Unfollow an author or publication') and clearly distinguishes the action from siblings like 'follow' and 'list_following'. The 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?

Explicitly states when to use ('Only use when the user explicitly asks') and handles ambiguity by instructing to ask the user. It does not explicitly list alternatives or exclusion criteria, but the condition is clear and actionable.

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