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

The description adds value beyond the annotations by disclosing authentication via API key, clarifying that this is an account read (not Twitter data), and stating it is free with no credit cost. These details are not present in the annotations (readOnlyHint, openWorldHint, destructiveHint), enriching the behavioral context.

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

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

The description is two concise sentences, front-loaded with the main purpose and followed by essential caveats. Every sentence earns its place without fluff.

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

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

For a simple, no-parameter read tool with no output schema, the description fully covers the return fields, authentication, and cost implications. It is complete for the agent to correctly select and invoke the tool.

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

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

With zero parameters and 100% schema coverage, the description doesn't need to explain params. It still usefully describes what the tool returns, which is more than sufficient given the baseline for 0 params.

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

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

The description clearly states the action (Get), the resource (YOUR twitterapis.com account details), and enumerates the specific data returned (email, name, credits, etc.). It also distinguishes itself from sibling tools by explicitly noting this is an account read, not Twitter data.

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

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

The description provides clear context: it is for retrieving account details, not Twitter data, and it is free (does not spend credits). This implicitly tells the agent when to use this tool over data-focused siblings, though it does not explicitly name alternatives.

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

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

Annotations already declare readOnlyHint true, and the description reinforces this with 'account read'. It adds operational context by specifying free usage and no credit consumption, which goes beyond the annotations. No contradiction found.

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

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

The description is extremely concise: two sentences. The first states the primary action and result, the second adds critical context (authentication, cost, and scope). No wasted words; front-loaded and efficient.

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

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

For a tool with no parameters and no output schema, the description adequately covers what it returns (payment history), who it's for (your account), and key attributes (free, no credits). It might benefit from mentioning result format or pagination, but these are not essential given the tool's simplicity.

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

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

The tool has zero parameters, so schema coverage is 100% trivially. The description appropriately does not add unnecessary parameter details, though it could mention that the result is scoped to the authenticated user's account, which is implied.

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

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

The description explicitly states it retrieves the user's twitterapis.com payment history, listing top-ups and charges. It clearly distinguishes this from sibling tools that focus on Twitter data by emphasizing 'your account' and 'not Twitter data'.

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

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

The description mentions authentication via API key and explicitly states it is free and does not spend credits, which guides when to use it. It clarifies it's an account read, not Twitter data, helping differentiate from other tools, though it does not explicitly name alternatives (there are none for payments).

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, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description usefully adds that results include tweet text, author info, engagement metrics, and a pagination cursor. It does not mention rate limits or auth needs, so it adds some but not rich behavioral context.

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

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

Front-loads purpose, then operators, return values, mode selection, and examples in a tidy progression. The operator enumeration duplicates the schema's query description, so it is slightly padded rather than tightly minimal.

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 appropriately explains the return shape (tweet text, author, engagement, cursor). Combined with operator support, mode guidance, and examples, an agent has enough to call it correctly, missing only auth/rate-limit context.

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 all four parameters are already documented in-schema, setting a baseline of 3. The description's operator list and product-mode explanation largely restate the schema, though the concrete example queries add marginal construction help.

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 recent tweets using X's advanced-search operators.' The 'recent tweets' scope and operator-based full-text search distinguish it from siblings like twitter_user_search or twitter_bookmark_search, though it never names them 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?

Offers in-tool guidance on product modes ('Latest' for chronological vs 'Top' for engagement-ranked) and gives example queries, which implies usage. However, it never states when to reach for this tool over sibling search tools or any conditions to avoid 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?

With only generic annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=true), the description adds meaningful context: it creates a draft, requires an authenticated session with write capability, and returns an id plus full object. No annotation contradiction exists.

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

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

Three compact sentences front-load the core action, then provide the returned id use and auth prerequisite. There is no filler or repetition; every sentence contributes.

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

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

Without an output schema, the description correctly discloses return values (id + full article object), downstream tool names, and the write-session requirement. This is sufficient for an agent to select and safely invoke a simple no-input create operation.

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

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

All four parameters are already fully documented in the schema, so the high coverage baseline applies. The description adds a useful high-level note that no input is required and that auth/session context is needed, but it does not materially enrich parameter-level semantics 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 opens with a specific action ('Start a new DRAFT article') and identifies the actor ('AS your authenticated account') and artifact type ('Note'). It clearly distinguishes this creation tool from article mutation/publishing tools like twitter_article_update_title, twitter_article_publish, and twitter_article_delete.

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 frames this as the entry point to the article lifecycle by stating no input is required and explaining that the returned id feeds update/publish/delete tools. It does not explicitly contrast with twitter_create_tweet or name when to avoid this tool, so it falls just short of full exclusion 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 destructiveHint=true and readOnlyHint=false, so the description's 'Irreversible' statement adds value by emphasizing permanence. It also discloses the extra round trip when hints are omitted, and the requirement for write capability. While it doesn't detail the exact response format, it states 'Returns ok/deleted and the id you targeted', which is sufficient given 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 a single, dense paragraph that front-loads the core action and then adds necessary nuance. Every sentence earns its place: the draft vs. published distinction, the comparison to unpublish, the irreversibility warning, the fast-path hints, and the auth requirement. No fluff or repetition.

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

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

Given the tool's complexity (two lifecycle paths, optional hints, auth requirements) and the absence of an output schema, the description covers all critical aspects: what happens to drafts vs. published articles, the tweet deletion, the fast-path hints, the auth requirement, and the return value. It's complete for an agent to decide and invoke correctly.

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

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

Schema description coverage is 100%, so the schema already documents all 7 parameters. The description adds value by explaining the fast-path hints (lifecycle, tweet_id) and their performance implications, and clarifies that auth_token/ct0 must be paired. This goes beyond the schema's basic descriptions, though the schema already covers the essentials.

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 deletes an article as the authenticated account, distinguishes between draft (hard-delete) and published (unpublish + delete tweet) behavior, and explicitly contrasts with twitter_article_unpublish. It names the specific resource (article) and the action (delete), making the purpose unambiguous.

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

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

The description explicitly explains when to use this tool (to fully remove a published article's public footprint) and when not to (compare twitter_article_unpublish, which leaves the tweet up). It also provides guidance on optional fast-path hints (lifecycle, tweet_id) and when to omit them, plus the requirement for an authenticated session with write capability.

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 (readOnlyHint: true, destructiveHint: false) already signal a safe read operation. The description adds critical details about the two auth models (API key vs. session), the 404 error handling (returns article: null), and ownership requirements for drafts. This goes beyond the annotations without contradicting them.

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

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

The description is a single comprehensive paragraph covering purpose, forms, auth, and errors. It is information-dense but not verbose; every sentence contributes. While it could be broken into bullets, it's appropriately sized for the complexity.

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

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

The description covers the full API surface: purpose, both forms, authentication requirements, error conditions, and relationships to other article tools. Even without an output schema, it lists returned fields (title, content_state, etc.) and handles edge cases like drafts and 404s. For a tool with this complexity, it is exceptionally complete.

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

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

Schema covers 100% of parameters with descriptions, so baseline is 3. The description adds value by explaining that id, url, and article_id are mutually exclusive and that article_id is the owner-only form. This metacommentary helps an agent choose the correct parameter, exceeding what the schema alone provides.

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

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

The description uses a specific verb+resource ('Read an article's full content') and clearly distinguishes the two invocation forms (PUBLIC via id/url, OWNER-ONLY via article_id). It differentiates this read operation from sibling tools like twitter_article_create/list/delete, which are referenced for context.

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 covers when to use the PUBLIC form (published articles, no session needed, id/url) versus the OWNER-ONLY form (requires authentication, drafts). It also explains the 404 behavior for not found/visible/owned. Although it doesn't explicitly name an alternative tool, the usage contexts are clear and reference sibling tools for article_id sources.

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 include readOnlyHint=true, openWorldHint=true, destructiveHint=false. The description complements by explaining that it's scoped to the authenticated account (not all articles), requires an authenticated session (ct0, auth_token), yields most recent first, and paginates via cursor. It doesn't contradict annotations and adds valuable context about session/auth requirements and the lack of a combined view. Slight deduction for not mentioning rate limits or potential errors, but generally strong.

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

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

The description is compact but information-dense, covering purpose, scoping, lifecycle behavior, authentication, pagination, and return structure. It front-loads the core message of listing your own articles, then adds necessary details without redundancy. Every sentence contributes value, and it stays well under 150 words for a tool with 7 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 no output schema, the description explains return fields (count, next_cursor, article objects). It covers authentication requirements, pagination mechanics, and the lifecycle limitation. For a read-only list tool with comprehensive parameter descriptions and annotations (readOnlyHint, openWorldHint), this description is complete and self-contained. No critical information is missing.

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

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

Schema coverage is 100% and each parameter has a description. The description adds context by stating the default count (20), the behavior of cursor (null/absent means no more pages), and that lifecycle must be explicitly changed to published. It also explains the auth cookie requirement and proxy_url recommendation for writes. While the schema already explains each parameter clearly, the description enriches the semantics with default values and practical usage patterns.

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

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

The description clearly states the tool lists the authenticated user's own articles, with a specific verb ('list'), resource ('articles'), and scope ('YOUR OWN', 'AS your authenticated account'). It distinguishes itself from sibling tools that list articles for other users or manage webhooks/tweets by emphasizing the authenticated account's own articles and the lifecycle filter.

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: for listing one's own published or draft articles, and when not to: when needing a combined view, as X exposes no combined view. It provides clear guidance on using the 'lifecycle' parameter (published vs draft) and explicitly mentions pagination via 'cursor', which is a direct alternative to not using it. No alternatives are needed since this is a unique tool for listing own 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?

While annotations already mark the operation as non-read-only, the description goes far beyond by disclosing that the announcement tweet is REAL and PUBLIC, that the action is hard to fully undo, and that even after deletion the content was already public. It also describes authentication prerequisites and provides high-value context about the exact reversal behaviors of sibling tools, with no contradiction to the annotations.

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

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

The description is front-loaded with the core action and then builds out critical warning and side-effect context. Every sentence serves a distinct purpose: warning about irreversibility, naming alternatives, giving confirmation guidance, and covering defaults and prerequisites. The length is justified given the consequential nature of the operation.

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

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

The tool has 8 parameters, complex state transitions, and no output schema, yet the description succeeds in covering what matters: the outcome, the order of operations, side effects, undo semantics, defaults, return value, and authentication needs. The agent is equipped to decide, confirm, and invoke safely.

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

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

The input schema already covers 100% of parameters with detailed descriptions, so the baseline is 3. The description repeats a few key facts (id must be a draft, audience and reply_control default to 'Everyone', caption max 256 characters) but does not add new parameter semantics 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?

The description clearly states the tool's core action—publish a DRAFT article as the authenticated account—and specifies the resulting state change: transitioning to Published and posting a REAL, PUBLIC announcement tweet. It distinguishes itself from sibling tools by explicitly naming twitter_article_unpublish and twitter_article_delete and their different reversal behaviors.

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

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

Provides explicit when-to-use guidance: publishing a draft article with a public announcement tweet. It also gives exclusionary context by explaining that unpublish only reverts the article but leaves the tweet, and that only delete on a published article removes both. Additionally, it instructs the agent to confirm with the caller unless explicitly authorized, which is clear and actionable usage guidance.

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

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

The description details side effects (tweet left in place), requirements (write capability, authenticated session), error behavior (invalid_lifecycle), and return value (updated Draft article). This goes beyond the annotation (destructiveHint) by specifying exactly what is and isn't affected, without contradicting it.

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 succinct and structured: it states the action, the side effect, the alternative, the error condition, the requirement, and the return value in a few clear sentences without fluff.

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

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

Given the tool's complexity, the description covers all critical aspects: what it does, side effects, when to use an alternative, error scenarios, authentication needs, and the return object. It is complete enough for an agent to use effectively.

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 per-parameter descriptions (e.g., id, auth_token), so the description doesn't need to add parameter details. It does mention authentication and write capability generally, but does not specifically elaborate on individual parameters, keeping it at the baseline for high schema coverage.

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

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

The description clearly states the action (revert a PUBLISHED article to Draft) and distinguishes it from the delete alternative (which also removes the tweet). It specifies the resource (article) and the state transition, making it 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 explicitly explains when to use this tool versus the alternative (twitter_article_delete) when tweet removal is also desired. It also mentions the error condition if the article is not published, providing clear usage context.

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

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

Transparently notes that the tool does not construct or validate content_state, passes it through verbatim, and clarifies authentication and write requirements. Consistent with destructiveHint=false and adds useful behavioral context beyond annotations.

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

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

The description is concise, using two clear sentences without redundancy, and is well-structured with necessary details.

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?

Covers key aspects: target article states (DRAFT or PUBLISHED), authentication/write requirements, pass-through behavior, and return type. Sufficient for the tool's complexity; lacks only explicit mention of alternatives, but not essential.

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 enriches schema by specifying content_state as Draft.js JSON with expected structure and explicitly states that the user builds it and it is passed through verbatim, adding meaning beyond the basic 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?

Description clearly states the action: 'Replace the body content of a DRAFT or PUBLISHED article'. It identifies the resource (article) and the specific operation (content update), distinguishing it from other article operations like title or cover media updates.

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

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

The description implies usage for changing article body content and mentions requirements (authenticated account, write capability), but does not explicitly contrast with alternative tools like update_title or update_cover_media, nor state when not to use it.

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

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

Annotations are minimal (readOnlyHint: false, destructiveHint: false), so the description rightly carries the burden and adds context: acts 'AS your authenticated account,' requires write capability, clarifies it does NOT upload, and discloses the return shape ('updated article object with cover_media populated'). 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?

Four information-dense sentences, front-loaded with the core action in the first clause. Use of ALL-CAPS emphasis ('ALREADY-UPLOADED,' 'NOT') aids scanning. No wasted words; 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 7-param, 2-required tool with no output schema and no enums/nesting, the description covers the key gaps: return shape, auth requirements, and cross-tool dependencies. Adequately complete given the moderate complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds genuine value by cross-referencing which sibling tool produces each identifier (media_id from twitter_media_upload, id from twitter_article_create/list), going beyond what the schema alone 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?

Specific verb+resource: "Attach an ALREADY-UPLOADED image as the cover of a DRAFT or PUBLISHED article." Clearly distinguishes from siblings by explicitly contrasting with twitter_media_upload and naming provenance tools (twitter_article_create/twitter_article_list).

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

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

Explicit workflow guidance: 'call twitter_media_upload first and pass the media_id it returns' gives when-to-use and sequencing, 'This does NOT upload' gives exclusions, and 'Requires an authenticated session with write capability' states preconditions. Names exact sibling tools for ID provenance.

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 readOnlyHint=false and destructiveHint=false, so the description's addition of 'Requires an authenticated session with write capability' and 'Returns the updated article object' adds valuable behavioral context beyond annotations. It also mentions the DRAFT/PUBLISHED state, which is useful.

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 four sentences and under 50 words, front-loading the core action. There is minor redundancy (mentioning 'authenticated account' and later 'authenticated session'), but each sentence serves a purpose: action, required inputs, auth requirement, and return 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 mutation tool with 6 params, 2 required, and no output schema, the description adequately covers the operation, auth prerequisite, input source, and return behavior. It does not discuss error conditions or rate limits, but these are not expected for a tool of this complexity.

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

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

Schema description coverage is 100%, so the baseline is 3. The description restates the need for id and title but adds no new meaning beyond the schema's field descriptions; it does not compensate for optional parameters like proxy_url or auth_token, which are already well-documented in the schema.

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

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

The description opens with 'Set or replace the title of a DRAFT or PUBLISHED article AS your authenticated account,' which uses a specific verb (set/replace) and resource (title of article). It clearly distinguishes from sibling tools like twitter_article_update_content and twitter_article_update_cover_media by focusing solely on the title.

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: the article id comes from twitter_article_create or twitter_article_list, and the tool targets title-only updates. It does not explicitly state 'use update_content for body changes,' but the title-specific wording and sibling differentiation make the intended usage clear.

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

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

Beyond the annotations (readOnly/destructive=false), it discloses auth requirements ("Requires an authenticated session behind your key"), a failure-mode guarantee that an empty users array is a genuine result rather than a silent failure because the endpoint errors instead of returning an empty page, and pagination behavior. That is meaningful operational context the annotations cannot express.

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

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

Four sentences, no filler, and the most important constraint (self-only scope) is front-loaded in the first clause. Each subsequent sentence adds a distinct fact: auth requirement, argument absence, and empty-result semantics.

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 and six optional parameters, the description compensates well: it characterizes the return (full user objects, cursor-paginated), the empty-array case, and the auth requirement. An agent has everything needed to call this correctly on the first attempt.

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, but the description adds semantics the schema does not: it explains the deliberate absence of a user_id argument and frames retrieval as cursor-paginated ("page with the cursor from the previous response"). It does not add per-parameter detail beyond that.

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

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

The description states a specific verb and resource ("List the accounts YOUR authenticated account has BLOCKED") and immediately constrains scope to the caller's own account. The emphasis on "YOUR... BLOCKED" distinguishes it cleanly from sibling read tools such as twitter_muting, twitter_user_followers, and twitter_user_info without requiring a schema 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?

It gives clear selection context: use this for your own block list, and explicitly rules out the alternative case by stating "There is no user_id argument: X provides no way to read another account's block list." It stops short of naming sibling tools (e.g., twitter_muting) as related alternatives, so it is strong but 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 cover read-only (readOnlyHint) and non-destructive (destructiveHint false). The description adds valuable transparency by mentioning the authenticated session requirement and specifying the exact output fields (id, name, cover image), which is not in 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 moderately concise, with four sentences covering purpose, differentiation, auth, output, and alternative usage. Each sentence adds value, though it could be tightened by removing the parenthetical definition of 'collections' without losing meaning.

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 (list folders) and the presence of a full input schema with per-parameter descriptions, the description covers the essential aspects: what it does, auth prerequisite, output fields, and alternatives. It lacks details on error cases or rate limits, but these are not critical for this read-only operation.

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

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

The schema provides descriptions for each optional parameter (ct0, proxy_url, auth_token, user_agent). The description adds semantic clarity by stating 'Takes no arguments' meaning no resource-specific arguments, and implies these parameters are for session/auth context. However, the phrase 'Takes no arguments' could be slightly misleading given the schema parameters, but it is contextually clear.

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

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

The description clearly states the action ('List'), the resource ('YOUR authenticated account's bookmark FOLDERS'), and differentiates from the flat bookmarks list (twitter_bookmarks) and the folder timeline tool. It also explains the internal name 'collections' for clarity.

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

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

It explicitly contrasts with twitter_bookmarks (flat list) and directs users to twitter_bookmark_folder_timeline for reading tweets inside a folder, providing clear when-to-use guidance. It also notes the authentication requirement as a prerequisite.

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

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

Annotations already indicate read-only and non-destructive, and the description adds useful context: requires an authenticated session, and pagination is cursor-based with no count/page-size. This is beyond the annotation metadata and helps the agent understand expectations.

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

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

Two sentences, both dense with actionable info: purpose/scoping, source of folder_id, auth requirement, and pagination. No fluff, each 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 read-only paginated tool with good annotations and full schema coverage, the description adequately covers purpose, auth, and pagination. It doesn't describe the return shape, but without an output schema, that's acceptable. It might mention rate limits, but overall it's complete for this tool type.

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

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

Schema coverage is 100%, so all six parameters are described there. The description adds minimal extra meaning, only reminding that folder_id comes from twitter_bookmark_folders. Since the schema handles parameter details, the description's contribution is marginal but not absent.

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

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

The description clearly states the tool reads tweets from one bookmark folder, specified by folder_id sourced from twitter_bookmark_folders. This specific verb+resource+scope distinguishes it from siblings like twitter_bookmark_folders (listing folders) and twitter_bookmarks (all bookmarks).

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 provides a prerequisite (folder_id from twitter_bookmark_folders) and notes the requirement for an authenticated session. It also explains pagination behavior (cursor-based, no count parameter). While it doesn't explicitly name alternative tools, the 'ONE' qualifier and source hint adequately guide usage.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds real value beyond that: it discloses the authentication requirement, the sort order, and the return shape ('with author and metrics plus a cursor'). It stops short of discussing rate limits or pagination limits, but that is the schema's job here.

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 tight sentences, front-loaded with the core purpose before prerequisites and return format. 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?

With no output schema, the description carries the return-value burden and does so adequately (author, metrics, cursor). Auth and ordering are covered; adding sibling routing 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?

Schema description coverage is 100% and the schema itself explains count, cursor, cookies, proxy and user-agent in detail. The description adds no parameter-level meaning beyond the ordering/cursor mentions, 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 (List) and resource (bookmarked tweets) scoped to the authenticated account, plus ordering ('most recent first'). It clearly differs from bookmark_search and bookmark_folder_timeline by being an unfiltered listing of your own bookmarks, 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 description implies use (retrieve your bookmarks) and states the auth precondition, but gives no explicit when-to-use, when-not-to-use, or pointer to the sibling tools (bookmark_search, bookmark_folder_timeline) that an agent might pick instead.

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, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds real value beyond that: it states an authenticated session behind the key is required and discloses the return shape (matching tweets plus a cursor), which the annotations do not convey.

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

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

Three sentences, the scope constraint and auth requirement front-loaded, and the return shape and use case follow. Every sentence carries distinct information with no redundancy.

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

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

With no output schema, the description compensates by stating the return is matching tweets plus a cursor, and it covers the auth prerequisite. Pagination mechanics live in the cursor parameter's schema description, so what is missing here is minimal, though a brief note on paging would have made it fully self-contained.

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

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

Schema description coverage is 100%, so the schema already documents all seven parameters, including the advisory count cap, the ct0/auth_token pairing, and the proxy recommendation. The description adds no parameter-level detail 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 (full-text search), a precise resource (bookmarks), and crucially scopes it to "YOUR authenticated account's bookmarks," which separates it from twitter_advanced_search and from the plain twitter_bookmarks listing sibling. An agent can identify it without opening the schema.

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?

"Use this to retrieve a previously bookmarked tweet by keyword" gives an explicit use case, so usage is more than implied. However, it names no alternatives (e.g., twitter_bookmarks for listing all bookmarks) and states no conditions under which this tool should not be chosen, leaving the when-not side entirely to inference.

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 flag readOnlyHint=false, so the description adds value by specifying the side-effect scope: the bookmark lands only in the authenticated account's *private* bookmarks, and the operation is reversible via twitter_unbookmark_tweet. It also discloses the auth requirement ('write capability behind your key'). It stops short of 5 because, with no output schema, it doesn't disclose return/error behavior or duplicate-bookmark semantics.

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

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

Four short sentences, front-loaded with the core action, then input form, precondition, and reversal — every sentence earns its place with zero 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?

The description covers action, account scope, privacy, input form (id or url), auth precondition, and reversal, while the schema's property descriptions add proxy/auth pairing nuances. The only gap is that no output schema exists and the description doesn't hint at return values or already-bookmarked behavior; for such a simple write operation this is a minor 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 description coverage is 100%, so the baseline is 3 — the property descriptions already document the id/url mutual exclusion ('Provide exactly one of id or url'), ct0/auth_token pairing, proxy_url recommendation for writes, and header mappings. The top-level description merely restates 'Provide the tweet id or url' and adds no syntax or format 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?

The description opens with a specific verb+resource+scope: 'Bookmark a tweet to YOUR authenticated account's private bookmarks.' It distinguishes from siblings by scoping the action to the caller's own account and explicitly naming the reverse tool (twitter_unbookmark_tweet), while the read-only bookmark siblings (twitter_bookmarks, twitter_bookmark_search) are clearly different operations.

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 this tool applies: it requires 'write capability behind your key' and names twitter_unbookmark_tweet as the explicit reverse/undo path. However, it doesn't explicitly state when NOT to use this versus the read-only bookmark tools (twitter_bookmarks, twitter_bookmark_search), so it falls just short of full exclusion 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 declare readOnly, description adds details on what flags are returned (block/mute). No contradiction and provides extra context 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 sentences front-load purpose and usage, 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 simple read tool with no output schema, description covers input, return value hints, and usage context. Minor gap: no mention of error handling.

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

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

Schema covers both params with descriptions; description rephrases roles ('subject' vs 'object') adding clarity. With 100% schema coverage, additional explanation earns above baseline.

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

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

The description clearly states the tool checks follow relationship between two accounts by numeric user id, including blocking/muting flags. It distinguishes from sibling tools like follow/unfollow.

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

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

Explicitly says both ids required and gives use cases: verify follow before/after or detect mutuals. Lacks explicit when-not but context is clear.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description does not need to restate safety. It adds behavioral context by specifying that it returns 'FULL user profiles' with detailed fields, which goes beyond the schema. It also clarifies the endpoint is about people, not the community object, adding useful nuance beyond what annotations convey. No contradictions 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?

The description is two sentences, tightly written, and front-loaded with the core purpose. Every clause adds value: it states what it returns, contrasts with reduced-row siblings, and directs to the correct alternative for metadata. No fluff or redundancy.

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

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

For a simple single-parameter tool with strong annotations and full schema coverage, the description provides complete context. It describes the output content (full profiles with specific fields), explains the differentiation from related tools, and clarifies the scope (people vs community object). No output schema exists, but the description sufficiently conveys what to expect. The tool's complexity is low, and nothing critical 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 schema description fully covers community_id with an example and URL context (100% coverage). The tool description does not add any extra parameter semantics, but the schema is sufficient. Baseline 3 applies because the parameter is already well-documented; the description does not need to repeat 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 tool's function: returning full user profiles for a community's moderators and a preview of its members. It names the specific fields included and explicitly distinguishes it from sibling tools like twitter_community_members and twitter_community_moderators, which return reduced rows, and twitter_community_info, which covers community metadata. This makes the purpose unambiguous and easily differentiated.

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

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

The description provides explicit when-to-use guidance and names alternatives: it says to use this tool when full profiles are needed versus reduced rows from twitter_community_members/moderators, and directs users to twitter_community_info for community metadata. It also explains that this endpoint answers 'who runs a community' in one call, covering when and why to choose 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 readOnlyHint=true, openWorldHint=true, and destructiveHint=false, but the description goes further by explaining why viewer-relative fields (role, can_join, is_pinned, viewer_relationship_type) are always null due to pooled rotating accounts, and why rules[].description is always null. This prevents misinterpreting expected nulls as errors—valuable behavioral context beyond annotations.

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

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

The description is front-loaded with the core purpose, then lists return fields, clarifies the ID format, highlights important null behavior, and closes with sibling pointers. It is long but every sentence carries essential information; no filler or repetition beyond what aids clarity.

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 and a response containing many heterogeneous fields (banners, rules, profiles, facepile IDs), the description compensates thoroughly by naming the return fields, explaining deliberate nulls, and clarifying ID semantics. It also gives usage boundaries with sibling tools, making it complete for an agent to select and invoke correctly.

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

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

Schema description coverage is 100%, and the schema already provides detailed semantics for community_id, including type, format, example, and exclusions. The description restates the URL pattern and the 'NOT a Space id / NOT a user id' distinction, which reinforces but does not add significant new parameter meaning beyond the schema.

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

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

The description opens with a specific verb and resource: "Get the metadata for one X Community by its numeric id" and then enumerates the exact fields returned. It distinguishes itself from sibling tools by pointing to twitter_community_members and twitter_community_tweets for other concerns, making its scope unmistakable.

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

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

The description explicitly states both the context for use (single community metadata lookup by numeric ID) and directs users to alternatives: "Use twitter_community_members for the roster and twitter_community_tweets for the posts." It also clarifies the ID format with a concrete URL pattern, which guides correct invocation.

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

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

The description goes beyond the readOnlyHint annotation by detailing the reduced user object (no bio, follower counts, created_at), the interleaving of admins/moderators at arbitrary positions, and the pagination behavior (bare next_cursor, no total count, stop when members is empty or has_more is false). This provides critical behavioral context that annotations alone do not convey.

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

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

The description is dense but well-structured, front-loading the core purpose and then providing necessary caveats and usage notes. Every sentence adds value, covering the row structure, reduced user object, role semantics, pagination behavior, and alternatives. It is appropriately sized for the complexity of 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?

Given the tool's complexity (pagination, reduced user object, role semantics, interleaving), the description is complete. It covers the return structure, pagination termination conditions, and when to use alternative tools. The absence of an output schema is compensated by the detailed description of the row structure and user object fields.

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

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

The schema already has 100% coverage with detailed descriptions for all three parameters, including defaults, clamping, and the meaning of cursor absence. The description adds value by explaining the pagination semantics (next_cursor, end-of-list signal) and the reduced user object, but the schema already covers the parameter basics well, so the description's additional contribution is moderate.

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

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

The description clearly states the tool lists the member roster of an X Community with cursor pagination, and specifies the exact row structure (user, role) and the reduced user object fields. It distinguishes itself from sibling tools like twitter_community_moderators and twitter_user_info by explicitly noting what it does not provide and what to use instead.

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

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

The description provides explicit guidance on when to use this tool versus alternatives: it notes that the role on a member row is not caller-relative and is returned in full, unlike the community object's role field, and explicitly warns against deriving a moderator list by filtering the first page, directing to twitter_community_moderators instead. It also explains when to use twitter_user_info for full profiles.

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 declare readOnlyHint=true and destructiveHint=false, but the description goes far beyond that. It reveals that this is a 'pooled read' and that role/can_join/is_pinned/viewer_relationship_type are always null. It also discloses that an empty array is a real success, not an error, and that the result includes the full community object shape. This adds substantial behavioral context that annotations alone do not provide, and it does not contradict them.

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

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

The description is relatively long but every sentence earns its place: it starts with the core purpose, then differentiates from siblings, explains the return shape, warns about the id type, clarifies empty results, and notes pooled-read quirks. It is front-loaded with the primary use case. Though not the shortest, the density of essential information justifies its length.

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

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

Despite having no output schema, the description fully explains what the caller will receive: 'Each row is the FULL community object (the same shape twitter_community_info returns...), so no follow-up call per community is needed.' It also covers pagination via cursor, the empty-array case, and the null fields on pooled reads. For a 3-parameter tool with no output schema, this is highly complete and self-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 description coverage is 100%, so the schema already documents all three parameters clearly. The description adds extra value by emphasizing that user_id is NOT a @handle and NOT a community id, and by recommending resolving a handle with twitter_user_info first to avoid a hidden second call. It also confirms count defaults and clamping, reinforcing the schema. This exceeds the baseline of 3 for high coverage.

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

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

The description clearly states the tool's purpose: 'given a numeric X USER id, list the communities that account belongs to'. It uses a specific verb (list) and resource (communities) and explicitly differentiates from other community tools by calling itself the 'INVERSE community lookup' and noting that every other community tool starts from a community, while this one starts from an account. This fully distinguishes it among siblings.

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

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

The description gives explicit when-to-use guidance: 'makes it the tool for profiling which audiences a person sits inside'. It also provides when-not-to-use details: 'Takes a numeric user id ONLY, not a @handle: resolve a handle with twitter_user_info first' and warns about the cost of resolving a handle here. It also clarifies that an empty array is a successful answer, not a not-found, which prevents misinterpretation. These are strong usage guidelines.

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

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

Annotations already provide readOnlyHint=true and destructiveHint=false, and the description adds extra behavioral context: cursor-paginated output, the 'members' array name, absence of total count, and the presence of admins in results. No contradictions exist between description and 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 efficiently written with a clear front-loaded purpose and every sentence adds meaningful value regarding behavior, correctness, or usage. It avoids redundant phrasing while packing in crucial distinctions.

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 provides the essential return shape and pagination behavior. It covers the row structure, the array name, the absence of a total count, and the mixed roles, giving an agent sufficient information to correctly interpret and paginate 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% for all parameters, so parameters are already well-documented. The description adds context about pagination ('bare next_cursor with no total count') which relates to the cursor parameter, but it doesn't substantially go beyond the schema information for count and community_id.

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

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

The description clearly states the tool lists moderators and admins of an X Community, with a specific verb ('List') and resource. It further distinguishes it from the sibling twitter_community_members by specifying the identical row shape and the fact it is a separate upstream operation.

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 explains when to use this tool over twitter_community_members, detailing that filtering member pages is incorrect due to arbitrary positions of moderators. It also advises reading each row's role because admins are present, which is actionable 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=true, openWorldHint=true, and destructiveHint=false. The description adds valuable behavioral context: cursor-paginated results, compact hit structure with specific fields, and the guarantee that it returns only what X's own search sends. This goes beyond annotations without contradicting them.

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

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

Two sentences, front-loaded with the main action, followed by relationship context and response details. No filler words; every clause contributes meaningful information about usage or behavior.

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

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

Despite no output schema, the description covers purpose, pagination, response shape, and downstream tool usage. Annotations cover safety, and the tool is simple enough that this description is fully sufficient for an agent to select and invoke it correctly.

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

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

Input schema has 100% coverage for both parameters (query and cursor), so the description doesn't need to compensate. The description mentions cursor-paginated but adds no new parameter details 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?

The description clearly states the action ('Find X Communities by keyword') and resource (X Communities). It distinguishes itself from sibling community tools by explicitly positioning itself as the discovery step that produces community IDs, which other endpoints consume.

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

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

Provides explicit guidance on when to use: as the entry point for the community family, and directs users to specific sibling tools once an ID is obtained. It also implies when not to use it (when you already have an ID, use detail endpoints).

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

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

Beyond the readOnlyHint/openWorldHint annotations, the description adds crucial behavioral detail: pinned posts are returned in a separate 'pinned' field, not repeated in 'tweets', so naive iteration silently loses them. It also warns that ranking_mode is an upstream parameter and that 'Relevance' is not confirmed live, which goes far beyond the schema and 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 longer than average, but every sentence carries essential information: response shape, pinned-post pitfall, flat-list construction, ranking_mode semantics, and the alternative tool. The most important answer of 'what does this return and how do I handle it' is front-loaded.

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

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

With no output schema, the description adequately defines the key response structure: the top-level 'pinned' field plus the 'tweets' array, and explains how to combine them without duplication. It also covers pagination, sorting caveats, and the principal alternative, so the agent has enough context to invoke and process results correctly.

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

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

The schema already has rich descriptions for all four parameters, so the description does not need to repeat them. It still adds meaningful parameter context by explaining that ranking_mode is a real upstream request parameter and cautioning that only 'Recency' is confirmed against a live capture, which helps the agent make safer invocation decisions.

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?

Starts by explicitly saying 'Read an X Community's own post timeline', which identifies the action, resource, and scope. It also distinguishes itself from search tools by emphasizing it returns the community's own feed, not cross-community results.

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?

Directly provides the alternative: 'Use twitter_advanced_search instead when the search should span all of X rather than one community.' This gives the agent a clear when-to-use versus when-not-to-use rule and explicitly names the 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?

Adds beyond annotations by stating the tweet is public and 'not silently reversible', and points to an alternative for deletion. This gives the agent important side-effect information not captured in boolean 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?

Three concise sentences cover purpose, usage, prerequisites, side effects, and return value without redundancy. Highly efficient and well-structured.

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?

Covers prerequisites, public nature, non-reversibility, and return value, which is sufficient given no output schema. Does not mention error handling or edge cases, but those are often not expected in tool descriptions.

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

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

The schema already describes all parameters in full detail. The description adds a small clarification on reply_to and quote usage, but does not significantly enhance parameter understanding beyond the schema's own descriptions.

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

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

Clearly states the action: 'Post a new tweet' with the resource being the user's account. It distinguishes from siblings by mentioning reply/quote functionality and points to twitter_delete_tweet for reversal, differentiating it from other tweet actions.

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

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

Provides explicit usage scenarios (post, reply, quote) and prerequisites (authenticated session with write capability). Does not explicitly state when not to use, but the context is clear enough for an agent.

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

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

The description goes beyond annotations: it states cookies are stored server-side, never returned, and that the tool returns ok, resolved username, and validation status. This addresses security (sensitive data handling) and validation behavior, which is highly valuable given the write-capable scope. Annotations only state non-readOnly and non-destructive, so the description adds critical context without contradiction.

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

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

The description is a single paragraph but information-dense, listing tool names and options clearly. It front-loads the primary purpose and security note, though the long list of tool names could be abbreviated for brevity. It is slightly long but each part contributes to usage clarity.

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

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

Given the tool's complexity (authentication setup, side effects), the schema covers all parameters, and the description explains the registration flow, storage, return values, and alternatives. Without an output schema, it still conveys what the agent can expect (ok, username, validation). It is complete for an authentication setup tool with this level of detail.

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

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

The schema has 100% coverage, with each parameter described (auth_token, ct0, proxy_url, user_agent). The description adds context by mentioning that cookies are paired and that proxy_url is for residential proxies, but these details are largely redundant with the schema. Since the schema fully explains the parameters, the description adds minimal extra meaning, matching the baseline of 3.

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

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

The description clearly states the tool registers the user's own X account session via cookies against an API key, distinguishing it from alternatives like twitter_user_login. It explicitly lists the affected authenticated and write tools, making the purpose and resource clear. It loses one point because the main verb 'register' is implied rather than explicitly stated, and the title already conveys similar meaning.

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

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

The description explicitly says when to use this tool ('Register YOUR OWN X account session') and contrasts with twitter_user_login for username/password, and notes per-call cookie alternatives for most tools. This provides clear guidance on alternatives and exclusions, which is exemplary. It also outlines optional parameters like proxy_url and user_agent for advanced use cases.

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

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

Annotations are minimal (readOnlyHint=false, destructiveHint=false, openWorldHint=true). The description adds crucial transparency: idempotency (revoking twice returns ok with deleted=false), zero cost (works even out of balance), self-serve nature, scoping to own API key, and the limitation about not logging out of X. This goes beyond structured fields and does not contradict annotations.

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

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

The description is detailed but every sentence serves a purpose: action, result, side effects, and external behavior. It is well-structured with a clear front-loaded main statement. Slightly verbose due to the need to explain idempotency and external effects, but this is justified for a delete operation. Not overly long for the complexity.

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

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

Given the complexity of a session-deletion tool with side effects on other tools and external X account, the description covers all needed aspects: return behavior, cost, scope, idempotency, and the limitation regarding x.com cookies. The absence of an output schema is compensated by describing what the response looks like (deleted=false). This is complete for an agent to understand the full ramifications.

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 description coverage is 100%. The description explicitly states 'it takes no account identifier of any kind' and explains why, which adds semantic meaning about the absence of parameters beyond the schema. This is valuable for an agent to understand that no input is needed and why.

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 revokes an X account session and deletes stored credentials. It distinguishes from siblings like twitter_customer_session (which creates sessions) by explicitly mentioning it is the reverse operation. The verb 'revoke' is specific and the resource is well-defined.

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

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

Provides explicit when-to-use: after registering with twitter_customer_session. It also tells when not to rely solely on this tool (does not log out of x.com) and suggests additional action. The effect on other authenticated tools is clearly explained, making usage context unambiguous.

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 mark it read-only/non-destructive, and the description goes well beyond that: it enumerates the returned fields, discloses the security posture (never returns auth_token, ct0, or proxy URLs), states cost ('Free'), and explains scoping by construction ('takes no account identifier of any kind, so it cannot read another key's session'). This is exactly the extra behavioral context annotations cannot carry.

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?

Front-loaded with the core action, then return fields, then use cases; every clause carries information. It is dense and delivered as one long run-on paragraph rather than being broken into scannable chunks, which slightly hurts structure but not substance.

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?

There is no output schema, so the description carries the full burden of describing the response — and it does, enumerating every field, the enum-ish values for status and egress.source, and what is deliberately withheld. Nothing an agent needs to call it correctly 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?

Zero parameters, so the baseline is 4. The description earns that by explaining the absence functionally — no account identifier of any kind, scoped to the caller's own API key — which tells the agent the empty schema is intentional rather than an omission.

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 ('Read back the X account session you registered with') and immediately demarcates it from the sibling twitter_customer_session ('without changing it'). An agent can tell this apart from twitter_customer_session, twitter_customer_session_delete, and twitter_account_me without opening any schema.

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 concrete use cases ('am I posting as the account I think I am', 'has my session expired', 'is the proxy I supplied actually being used') and contrasts with the registration sibling, so context is clear. It stops short of an explicit when-not-to-use statement (e.g. use twitter_customer_session to register, this to inspect), leaving that routing to inference.

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

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

The description goes beyond annotations by explicitly stating the tweet is 'permanently removed' (irreversible), reinforcing destructiveHint. It also discloses that only self-authored tweets can be deleted and that write capability is required, which are not present in the annotations. This adds critical context for safe invocation.

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

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

The description is three concise sentences, each adding value: the action, the irreversible consequence, and the author restriction. No fluff or redundant information. It is front-loaded with the primary purpose and gets straight to the point.

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 a simple deletion tool and rich schema annotations, the description covers essential behavioral aspects: irreversibility, author scope, and authentication requirement. It does not explain error cases or post-delete behavior, but given the lack of output schema and the simplicity, it is sufficiently complete. Missing details like proxy usage are already in the schema.

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

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

Schema description coverage is 100%, so each parameter is already well-documented in the schema. The description only reiterates that id or url must be provided ('Provide the tweet id or url'), which matches the schema's mutual-exclusivity note. It adds no new parameter-level semantics beyond what the schema provides.

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

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

The description clearly states the action: 'Delete a tweet AS your authenticated account.' It specifies the verb (delete) and resource (tweet), and distinguishes from siblings like twitter_unfavorite_tweet or twitter_unretweet by focusing on permanent deletion. The irreversibility and author restriction add precision.

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 usage context: you can only delete tweets your own account authored, and it requires write capability. It instructs to provide the tweet id or URL. However, it does not explicitly compare to alternative tools (e.g., unfavorite or unbookmark), though the destructive nature makes it distinct.

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 readOnlyHint=true and destructiveHint=false. The description adds that authentication is required and reinforces the read-only nature, which is consistent and adds context.

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

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

Three sentences with no redundancy. The main action is stated first, followed by requirements and read-only declaration. All sentences contribute essential information.

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

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

Despite lacking an output schema, the description specifies what is returned ('each message with sender id, time, and text'). It covers the key parameter and requirement. It could mention error handling, but is complete enough for a simple read tool.

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

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

Schema coverage is 100% with detailed parameter descriptions. The description adds value by explaining that conversation_id comes from a sibling tool, which aids in selection. Baseline is 3 due to high coverage, but the cross-reference earns a 4.

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

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

The description clearly states the action ('Get the messages') and the resource ('Direct Message conversation'), and references the source of the identifier ('from twitter_dm_list'). This distinguishes it from other tools.

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

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

It specifies a requirement ('Requires an authenticated session') and declares the tool is read-only ('does not send DMs'). However, it does not explicitly state when to use or not use this tool vs. alternatives, though the context is clear.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. Description reinforces with 'Read-only: this does not send DMs' and adds authentication requirement, which is useful 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?

Two sentences, concise and front-loaded. Every sentence adds value: first states purpose and output, second clarifies read-only nature and prerequisite.

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 list tool with annotations, description is complete: states what it returns (participant and conversation_id), usage context, and connection to sibling tool. No output schema needed.

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

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

Schema coverage is 100%, so baseline is 3. Description adds no extra meaning beyond what schema provides for the 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?

Description states it lists your authenticated account's DM conversations (inbox), providing participant and conversation_id. It distinguishes from sibling twitter_dm_conversation by mentioning the conversation_id can be passed to that tool.

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

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

Includes prerequisite: requires an authenticated session behind your key. Does not explicitly state when not to use, but the context is clear for listing DMs.

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

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

The description discloses that it sends a real, non-silently reversible DM, which goes beyond the readOnlyHint=false annotation. It also reveals the need for residential proxy to avoid IP-based blocks, and notes that it returns message_id and conversation_id. No contradictions with annotations; adds actionable behavioral context.

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

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

The description is a single, information-dense sentence that front-loads the primary action. Every clause serves a purpose: action, destination, prerequisite, proxy recommendation, return info, and irreversibility warning. No redundant fluff; well-structured for quick agent comprehension.

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

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

For a write operation with auth and proxy requirements, the description covers all critical aspects: authentication, IP restrictions, parameter handling, and irreversibility. It also specifies the return fields, compensating for the lack of an output schema. Given the tool's complexity, this is complete.

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

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

With 100% schema coverage, the baseline is 3, but the description enriches parameter meaning: it explains the necessity of numeric recipient_id and how to resolve handles, recommends proxy_url for reliability, and clarifies that text must be non-empty. These practical hints are not in the schema, adding significant value.

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

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

The description clearly states the action: send a Direct Message as the authenticated account. It specifies the resource (DM) and distinguishes itself from sibling read tools like twitter_dm_list and twitter_dm_conversation. It also notes this is a real, irreversible action, setting it apart from other write tools.

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

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

Provides explicit directives: resolve recipient_id via twitter_user_info, require authenticated session with write capability, and recommend residential proxy for reliability due to X's soft-blocking of datacenter IPs. It effectively tells the agent when and how to use the tool, including prerequisites and alternatives for handle resolution.

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

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

The description discloses that the action requires write capability and is performed on behalf of the authenticated account, going beyond the annotation (readOnlyHint: false). It does not mention potential failure cases or side effects, but for a simple like operation 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?

The description is succinct, consisting of three short sentences that convey the action, input requirement, permission note, and reverse operation. No redundant information or fluff.

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

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

Given the simplicity of the action and complete schema descriptions, the description adequately covers the core behavior, permission needs, and relationship to the opposite action. It stops short of mentioning error conditions or response format, but that is not critical for a like operation.

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

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

The schema already provides detailed descriptions for all six parameters (100% coverage). The description adds a brief note to 'Provide the tweet id or url,' but this is already embedded in the schema. No significant additional parameter context is given.

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

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

Clearly states the action: 'Like (favorite) a tweet AS your authenticated account.' It distinctly identifies the resource (tweet) and the operation (like), and differentiates from the sibling tool by mentioning the reverse operation (twitter_unfavorite_tweet).

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 instructs to 'Provide the tweet id or url,' and notes the requirement for write capability. It also directs when to use the reverse tool, providing clear context for appropriate usage.

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 cover read-only, open-world, and non-destructive nature. The description adds substantial behavioral detail beyond that: the possible status values (new, triaged, shipped, declined), the presence of a team response text, the semantics of updated_at (moves only when the team acts), the cost (free per call), and the 404 error condition for ids not on the account.

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

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

The description is front-loaded with the core action, then efficiently packs in return fields, cost, and error behavior. Every sentence earns its place, and there is no redundant or filler text.

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

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

With no output schema, the description fully explains what is returned (status, response text, updated_at) and what happens on error. Given the low complexity and existing annotations, nothing an agent needs to call this tool correctly is missing.

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

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

Schema coverage is 100% and the schema already describes the id parameter as the server id from twitter_feedback_send action 'send', not a local draft id. The description repeats this same information without adding further syntax or format details, 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 states a specific verb (Check) and resource (status of a feedback report this account sent earlier), and distinguishes it from sibling feedback tools by referencing the send action. An agent can immediately tell this is for retrieving a single report's status, not sending or listing.

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 clear context: use the server id returned by twitter_feedback_send action 'send' and call it to check status of a previously sent report. It also notes 'Free per call' and a 404 condition. However, it does not explicitly name alternatives like twitter_feedback_list or state when not to use this tool.

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

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

Beyond the annotations (readOnlyHint=true, destructiveHint=false, openWorldHint=true), the description discloses output fields, the deliberate omission of details/evidence, pagination via cursor and next_cursor, and a shared 10-per-minute rate limit. These are important operational traits not captured by the structured metadata.

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 definition is front-loaded with purpose and then efficiently layers usage, sibling distinction, output caveats, pagination, and rate limits. Despite its length, every sentence adds necessary context for this tool, and there is no redundant filler.

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

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

With no output schema, the description compensates by naming the returned fields and explicitly stating what is never returned. It also covers pagination, rate limits, and the alternative read path, making it complete enough for an agent to invoke and interpret the tool.

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

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

Schema description coverage is 100%, so all four parameters (type, limit, cursor, status) are already well documented in the input schema. The description adds little parameter-level meaning beyond restating cursor paging and newest-first ordering; 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 first sentence gives a specific verb (List), resource (feedback reports), scope (this account, already SENT), and ordering (newest first). It further distinguishes the tool from the similarly named twitter_feedback_send local-draft list and points to twitter_feedback_get for report bodies, so an agent can select it correctly.

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

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

It explicitly states when to use it ('when the user asks what they have reported, or to find the server id of an earlier report') and names the contrasting alternative (twitter_feedback_send action 'list' shows local drafts). The routing to twitter_feedback_get for full status makes the boundary complete.

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

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

Annotations only declare readOnlyHint=false, destructiveHint=false, openWorldHint=true. The description adds substantial context beyond that: drafting sends nothing and needs no confirmation, must not be announced mid-task, sending posts each draft to POST /feedback, and returns a server id retrievable via twitter_feedback_get. No contradiction with the annotations.

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

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

Long but information-dense and front-loaded: purpose first, then labelled WHEN TO DRAFT, FORMAT and REVIEW sections. Nearly every sentence carries a rule or constraint, though the volume is near the upper bound for a tool description.

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, and the description compensates by stating what each action returns (queued draft locally, listed draft ids, a server id from POST /feedback). For a 7-parameter, nested-object, 4-action tool this is complete.

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

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

Schema coverage is 100%, so the baseline is 3. The description nonetheless adds real meaning: the four-bullet 'details' format, the facts-only constraint (no secrets/names), the auto-attachment of the last failing call where evidence is left blank, and the requirement that 'ids' match what list showed and the user named.

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: report a product problem or gap in twitterapis.com to its team, from inside the session. It also disambiguates its own multi-action nature (draft/list/send/discard) despite the 'send' name, and distinguishes itself from sibling tools like twitter_feedback_get and twitter_feedback_list by role.

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 enumerates when to draft (failed call not caused by 401/402/409/429, uncovered request, empty/wrong documented field, user frustration), enforces one-draft-per-issue, and defines the review path: list, then send only ids the user named, or discard. This is when/when-not/alternatives in full.

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, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuine behavioral context the annotations do not: it requires an authenticated session behind the key and discloses the return shape (profile data per overlap account plus a cursor).

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: the first front-loads the operation and its precise semantics, the second covers the auth prerequisite and return values. No filler or repetition of the name.

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?

Covers purpose, auth prerequisite, and return payload, which is sufficient given a 100%-covered schema and no output schema. A mention of practical pagination behavior would complete it, but nothing essential for correct 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?

Schema description coverage is 100%, so the schema already fully documents user_id, cursor, count, and the auth/cookie parameters. The description only restates the target user_id and cursor conceptually without adding syntax or format detail, so baseline 3 is appropriate.

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

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

States a specific verb+resource ('List the Followers you know for a target user id') and immediately defines the exact semantic scope: mutual-connection overlap between the target's followers and the caller's own follows. This distinguishes it from the many sibling follower tools such as twitter_user_followers and twitter_user_following.

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 clear context: requires an authenticated session behind your key, and the target user id is the input. It does not name an explicit alternative (e.g. twitter_check_follow_relationship) or state when-not to use it, so it stops short of full routing 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 indicate readOnlyHint=false and destructiveHint=false, so the write nature is known. The description adds important behavioral context beyond those booleans: the action is performed AS the authenticated account and specifically requires write capability. It does not contradict annotations, and mentions the reversible counterpart. Some side-effect detail (e.g., rate limits or failure semantics) is absent, but annotations lower the burden.

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

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

Two concise sentences deliver the core purpose, authentication requirement, and reverse-tool pointer without wasted words. The most critical information is front-loaded in the first sentence.

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 write operation with no output schema, the description covers what it does, how to authenticate, the required format of user_id, and the reverse operation. The schema fully documents all parameters, and annotations cover the safety profile. Minor gaps like expected response or failure behavior are not severe given the tool's simplicity.

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

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

Schema description coverage is 100%, so the baseline is 3. The main description adds meaningful guidance for the key user_id parameter ('Resolve a handle to a user_id first with twitter_user_info') and reinforces the auth-token pairing context visible in the schema. This extra semantic hint justifies a 4.

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

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

The description uses a specific verb ('Follow') plus a clear resource ('a user AS your authenticated account, by numeric user_id'), making the action unambiguous. It also distinguishes itself from the sibling tool twitter_unfollow_user by explicitly naming the reverse operation.

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 states a key prerequisite ('Requires write capability behind your key') and points to the alternative for reversing the action ('Reverse with twitter_unfollow_user'). It does not exhaustively enumerate when to use this vs. relationship-checking tools, but the context is clear enough for an agent.

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

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

Beyond annotations, the description candidly discloses that the tool is stateless, buffered not streamed, requires session auth, and may return a model different from the one requested. It also clarifies that citations are merged/de-duplicated and that full conversation history must be re-sent. This is rich behavioral transparency.

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

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

The description is front-loaded with the purpose and remains information-dense without padding. Each sentence gives genuinely new context: realtime Grok behavior, output shape, statelessness, and auth requirements. The formatting with clear term emphasis helps an agent parse key constraints 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 complex tool with 9 optional parameters and no output schema, this description covers the needed operational context: what returns, how citations are merged, how conversation continuity works, proxy/authentication concerns, and how turns are affected by mode. This is sufficient for an agent to invoke it with reasonable expectations.

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 already well served. The description adds useful semantics not obvious from the schema, such as treating a bare status URL as a first-class message for post summaries and showing that auth_token is never placed in the URL. Those details are not in the parameter names alone.

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

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

The description clearly states a specific action and resource: ask X's own Grok a question AS an authenticated account. It also describes the key output (single JSON reply with answer and citations) and the bare-tweet-URL summary use case, distinguishing it from the many other tweet/user/social-graph tools in the sibling list.

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

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

It explains when this is uniquely useful, namely for questions about what is being said on X in real time, and that a bare status URL produces a structured post summary. It does not name sibling tools as alternatives or state explicit when-not-to-use cases, but the realtime Grok framing gives solid practical guidance.

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

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

The description adds significant behavioral context beyond the annotations. It explains what the tool returns (eligibility, X's verbatim reasons when not eligible, free access status, model options) and explicitly states that eligibility is a property of the X account, not the API key. It also includes the 'Free' note, which is non-obvious. Annotations already declare readOnlyHint=true and destructiveHint=false, so the description does not need to repeat safety traits; it adds valuable return and account-dependency information.

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

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

The description is concise and well-structured. It opens with the primary purpose, then lists what it returns, adds a key caveat about account vs. API key, and ends with 'Free.' Every sentence earns its place, with no superfluous content. It is front-loaded and easy to scan.

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 configuration check with no output schema, the description is sufficiently complete. It covers the purpose, return contents, the account dependency, and cost. It does not mention error handling or authentication details, but the mention of 'authenticated account' and 'Free' implies the necessary context. Given the tool's simplicity and the rich schema annotations, it is adequately complete.

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

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

Schema description coverage is 100%, as each of the four parameters has a detailed description. The tool description itself does not elaborate on parameter usage, but it does hint at the account-based nature (auth_token and ct0) indirectly. With full schema coverage, the description adds minimal extra over the schema, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool checks whether the authenticated account can use Grok and which models are available. It specifies the resource (Grok) and the action (check eligibility and models), and it distinguishes itself from the sibling twitter_grok_chat by focusing on configuration and eligibility rather than chat. The description also clarifies the account-based nature of eligibility, which is a specific and unique purpose.

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 directs usage: 'ask this about the same account you intend to run twitter_grok_chat as.' This provides clear guidance on when to use the tool (before using Grok chat) and ties it to the specific account. It also notes that the tool is 'Free,' which is a practical usage consideration. While it does not list exclusions, the instruction is specific and actionable.

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

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

Annotations already declare readOnly/openWorld/no-destructive, so the safety profile is covered. The description adds value the annotations don't: the authenticated-session requirement and the return shape ('tweets with author and metrics plus a cursor'), which matters since there is no output 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?

Three tight sentences, front-loaded with the scope and output. The closing sentence ('read what your account would see when it opens X') restates the first sentence's intent and could be trimmed without loss.

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?

Covers everything an agent needs for a read-only, no-required-param call: scope, auth prerequisite, ordering ('most recent first'), return contents and pagination signal, with annotations handling 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% and each parameter (ct0, auth_token, count, cursor, proxy_url, user_agent) is fully documented in the schema, so the baseline is 3. The description gestures at the auth requirement but adds no syntax or usage detail beyond what the schema already states.

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 YOUR authenticated account's Home timeline') and scopes it to the caller's own feed, which separates it from lookalikes such as twitter_list_timeline or twitter_user_tweets. The parenthetical frame ('the Following/For you feed') removes ambiguity about which timeline is meant.

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 clear context ('read what your account would see when it opens X') and a prerequisite (an authenticated session behind your key). It does not name an explicit alternative for scenarios such as reading a list's timeline or another user's feed, so exclusions are left to inference.

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?

Exceptionally rich behavioral disclosure beyond the annotations: exact return fields, the member_count null-as-not-applied signal, the 422-with-identical-field-layout behavior for failed writes, and a 'not billed' note for non-applied writes. The description does not contradict readOnlyHint=false or openWorldHint=true; rather, it complements them with operational detail that annotations cannot convey.

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

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

Dense single paragraph with zero filler — every sentence carries meaning (purpose, example, response format, edge-case signal, reversal). It's on the longer side and slightly run-on in the middle sentence, but the information density justifies the length. A touch of formatting (e.g., separating the reversal note) would make it perfect.

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 side-effect-heavy mutation with no output schema, the description is remarkably complete: full return value list, a concrete confirmation pattern (read member_count), explicit failure modes (already a member, not your list), status code (422), and billing implications. No output schema exists, so explaining the return shape in prose is exactly what's needed and it does so thoroughly.

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

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

Schema description coverage is 100%, so baseline is 3; the description adds value by clarifying both IDs are numeric and connecting them to the write action. The schema descriptions themselves are strong (URL format for list_id, cross-reference to twitter_user_info for user_id resolution, proxy recommendation for writes). Slight deduction for the description text not adding much beyond 'numeric' since the schema already documents each parameter thoroughly.

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

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

The description uses a specific verb+resource pair ('Add one account to a Twitter/X List') and clarifies scope with 'that YOUR registered X session owns' and 'by numeric list id and numeric user id'. It clearly differentiates from the sibling twitter_list_remove_member by naming it as the reverse operation, and the ownership constraint distinguishes it from list-reading tools.

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

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

Provides a concrete use case ('adding each speaker at a conference to a List as they are announced') and explicitly names twitter_list_remove_member for reversal. The ownership prerequisite is stated upfront. Loses a point because it doesn't explicitly enumerate when NOT to use it relative to other write tools (e.g., twitter_create_list), though the reverse tool reference helps.

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

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

Beyond the annotations (readOnly=false, destructive=false), the description discloses that the operation creates a resource, returns a list id, and explains the public/private visibility semantics. This adds meaningful behavioral detail not implied by the annotations alone.

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

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

The description is informative but slightly verbose, repeating 'registered X session' and including detailed return values. However, it is well-structured and free of fluff, earning a score above average.

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 purpose, usage flow, return values (list_id, member_count, full list object), and privacy behavior. Given the lack of an output schema, it sufficiently explains what to expect from the call, making the context 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 input schema already provides 100% coverage for all 7 parameters with clear descriptions (e.g., ct0, proxy_url, is_private). The tool description does not add extra parameter guidance, but since schema coverage is high, the baseline of 3 is appropriate.

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

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

The description clearly states the tool creates a new Twitter/X List and distinguishes it from related tools like twitter_list_add_member by positioning it as the initial step. The verb 'create' is specific and the resource 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?

It explicitly instructs when to use it ('starting point for building a List') and how to chain it with twitter_list_add_member using the returned list id. It also clarifies privacy defaults and implications, giving clear usage context.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is known. The description adds valuable behavioral context: it notes cursor-paginated nature and clarifies that a small follower count is normal and not a truncated page. This goes beyond the annotations without contradicting them.

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

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

The description is three sentences, tightly written. It opens with the core action, then adds differentiating clarity and a usage hint. 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 read-only, open-world tool with three well-documented parameters and no output schema, the description covers the essential aspects: what it returns, how pagination works, and a critical distinction from a sibling tool. It could mention the expected response structure, but given the simplicity and the absence of an output schema, it is adequately complete.

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

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

Schema coverage is 100%, so each parameter already has a clear description (count, cursor, list_id). The tool description itself adds little beyond mentioning 'cursor-paginated' and the normality of small counts, which slightly reinforces the count/cursor semantics but does not materially enhance what the schema 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 clearly states the verb 'Fetch' and the resource 'public List's followers' by numeric id, and specifies cursor-pagination. It also explicitly distinguishes from twitter_list_members, which is a sibling tool, ensuring the agent picks the right one.

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

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

The description explicitly says to use twitter_list_members for the member roster instead, and explains the conceptual difference between followers and members. It also preempts confusion about small result counts, providing clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds useful context beyond that: it returns profile data per member and pagination proceeds via cursor. It does not, however, note rate limits or the upstream page-size cap that the schema documents.

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?

Front-loaded with the core action, then returns, pagination, use cases, and id location. Efficient overall, though the trailing sentence about the list_id URL is redundant with the schema's own description.

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 listing tool with no output schema, the description supplies the return content (profile data per member) and pagination approach, which is the information an agent most needs. It is essentially complete, with only rate-limit/paging-depth caveats left to the schema.

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

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

Schema description coverage is 100%, so all three parameters are fully documented in the schema, including the nuanced page-size cap and cursor mechanics. The description's only added detail, the list_id URL location, merely restates the schema, so baseline 3 applies.

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

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

States a specific verb (List) and resource (members of a Twitter/X List) and identifies the keying parameter (numeric list id). It does not explicitly distinguish itself from close siblings such as twitter_list_followers or twitter_list_tweets, so the agent must infer the difference 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?

Provides concrete when-to-use context: 'enumerate curated account sets, including competitor lists, industry watchlists, or media outlet lists.' This orients the agent toward the intended scenario but offers no when-not guidance or explicit routing to alternatives like twitter_list_followers.

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 include readOnlyHint: false and destructiveHint: true, but the description goes further: it details the exact response fields, the meaning of null member_count (not-applied signal), and that non-applied writes return a 422 with a machine-readable reason and are not billed. This is rich behavioral context beyond annotations.

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

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

The description is dense but a bit long (4 sentences) and dives into response details and error semantics. However, it is front-loaded with the core purpose and use case, and every sentence adds value (response interpretation, billing, reversal). Slightly over-specified but still efficient.

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

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

For a mutation tool with no output schemalint, the description thoroughly covers purpose, response fields, success/failure signals, and billing behavior. It also notes proxy recommendation for writes (in schema) and provides a clear reversal path. Complete for the tool's complexity.

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

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

Schema coverage is 100%, with each parameter already described (e.g., list_id and user_id include URL and resolution guidance). The description adds little beyond schema, but the description does mention the dependency on resolving handle to user_id via twitter_user_info, which is implied in schema; baseline 3 is appropriate.

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

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

The description clearly states the action (remove one account from a Twitter/X List), specifies the required identifiers (numeric list id and user id), and scopes the operation to 'YOUR registered X session owns' a list. It explicitly distinguishes from sibling twitter_list_add_member by naming the reverse operation.

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 provides a concrete use case ('prune a curated List, for example dropping accounts that have gone quiet') and explicitly mentions the reverse tool (twitter_list_add_member) for undoing. It also states when the write will not apply (account not a member, list not yours), giving clear guidance on alternative actions.

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

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

Annotations already establish read-only and non-destructive behavior, so the description adds valuable context: native feed semantics, retweet inclusion, inability to honor search operators, and pagination ending when the tweets array is empty. This goes beyond what annotations and schema alone 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?

Every sentence earns its place: purpose, constraint, alternative comparison, and pagination stopping condition are each addressed once. The description is dense but well-organized and free of repetition.

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

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

The description is self-sufficient for this tool: it communicates the data scope, ordering behavior, retweet inclusion, endpoint limitations, pagination signal, and the sibling tool to use for alternate needs. With provided annotations and a fully-documented schema, this is a complete 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?

Schema description coverage is 100%, so the schema already documents list_id, count, and cursor. The description adds helpful high-level information about pagination and the absence of date/reply parameters, but it does not expand on individual parameter syntax, which keeps it at the baseline.

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

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

The description opens with a clear verb and direct object: 'Read a public Twitter/X List's NATIVE feed.' It specifies the exact behavior (same posts and ordering as x.com, including retweets) and differentiates itself from twitter_list_tweets.

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

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

The description provides explicit decision guidance: use twitter_list_tweets when you need a date range or filtered replies, and accept that the alternative drops retweets. It also clearly states what this endpoint cannot do (no date range, no reply filter).

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