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?

The description discloses what the tool returns (tweet text, author info, engagement metrics, pagination cursor) and explains pagination via cursor. Annotations already declare readOnlyHint and destructiveHint, so the behavioral burden is partially met. The description adds value without contradicting 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 paragraph of four sentences, each serving a purpose: stating the use case, listing operators, describing output, and giving examples. No wasted words, front-loaded with the main purpose.

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

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

For a tool with 4 parameters and no output schema, the description covers the return values, pagination, and parameter usage well. It could mention authentication or rate limits, but annotations already signal read-only safety. Overall, it is reasonably 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% with parameter descriptions, but the tool description adds significant context: it explains the operators supported (from:, since:, min_faves:), provides example queries, clarifies default for count, and describes product values beyond the enum names.

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 searches recent tweets using X's advanced-search operators. It specifies the verb 'search' and the resource 'recent tweets', and distinguishes itself from siblings like twitter_home_timeline and twitter_user_tweets by focusing on advanced operators.

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 on when to use product values ('Latest' for chronological, 'Top' for engagement-ranked) and includes example queries. However, it does not explicitly exclude alternatives like twitter_user_search 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?

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 annotations, the description explains authentication requirements, the absence of a user_id parameter, and crucial error semantics—an empty users array is a valid result meaning no blocks, not a failure, because the endpoint returns an error instead. This is rich behavioral context beyond readOnlyHint and destructiveHint.

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

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

The description is three sentences, front-loaded with the primary action, and every sentence adds value—scope clarification, auth note, and error interpretation. 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?

Despite no output schema, the description covers key operational aspects: pagination via cursor, auth requirement, no user_id limitation, and empty-array semantics. It is fully complete for an agent to call 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 coverage is 100%, so the baseline is 3. The description adds some context around pagination and authentication but does not significantly deepen parameter understanding beyond the schema's field descriptions.

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

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

The description clearly states the tool lists blocked accounts for the authenticated user, with specific verb 'List' and resource 'accounts YOUR authenticated account has BLOCKED'. It distinguishes itself from siblings by emphasizing no user_id argument and reading only your own block list, unlike user-specific tools.

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

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

The description provides clear context: it is for viewing your own block list, and explicitly notes that X provides no way to read another account's block list. It does not name alternative tools, but the scope and limitations are clear enough for an agent to decide when to use it.

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

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

Annotations already 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 provide readOnlyHint=true and destructiveHint=false. Description adds value by detailing return format: 'Returns each bookmarked tweet with author and metrics plus a cursor.' No contradictions; openWorldHint=true is not contradicted. Missing details on side effects 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 efficient sentences, front-loaded with purpose and requirements. Every sentence serves a purpose; 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 read-only list tool with 6 parameters fully documented, the description covers purpose, authentication necessity, and return format. Lacks pagination details beyond cursor mention, but schema covers that. No output schema needed. Adequate for its 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% with detailed parameter descriptions. Description does not add extra meaning beyond what the schema provides, only mentions return format. 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?

Description states 'List YOUR authenticated account's bookmarked tweets, most recent first.' Provides specific verb (list), specific resource (bookmarked tweets), and scope (authenticated account). Clearly distinguishes from sibling tools like twitter_bookmark_search and twitter_bookmark_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?

Description mentions requirement for authenticated session but does not explicitly state when to use this tool versus alternatives or when not to use it. No exclusions or alternative suggestions provided, though sibling tool names imply 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 and destructiveHint=false. Description adds that it requires an authenticated session, returns tweets plus cursor, which 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 purpose, no wasted words. Efficiently communicates key 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?

Describes input (query) and output (tweets and cursor), but lacks detail on response structure. However, given no output schema and straightforward use case, it's mostly 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. The tool description adds minimal parameter info (only mentions cursor output), 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?

Description states it performs 'full-text search within YOUR authenticated account's bookmarks', clearly identifying the tool's action and resource. It distinguishes from siblings like twitter_bookmarks by specifying search vs. 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?

Explicitly says to use for retrieving a bookmarked tweet by keyword and mentions authentication requirement. No when-not or alternatives provided, 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 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?

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 declare readOnlyHint=true and destructiveHint=false, but the description adds value by specifying the authentication requirement and the return shape ('profile data per overlap account plus a cursor'). This context helps the agent understand the operational constraints beyond what annotations provide.

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

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

The description is two sentences, each serving a distinct purpose: the first explains the core operation, the second adds requirements and output. It is front-loaded with the most critical information and contains no redundant or unnecessary 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?

The description covers the essential aspects: what the tool does, required authentication, and output (profile data + cursor). While there is no output schema, the description gives a sufficient overview. It could be more complete by clarifying the response structure or edge cases, but for a read-only tool with extensive parameter documentation, it is reasonably 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 parameter descriptions are already detailed (e.g., ct0, count, cursor). The tool description adds only the high-level requirement of an authenticated session, which is implicitly covered by the auth parameters. Given the high schema coverage, a score of 3 is appropriate as the description does not significantly augment the parameter semantics.

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

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

The description clearly defines the tool's purpose: listing 'Followers you know' for a target user, which is the overlapping followers between the target and the authenticated account. It uses specific verbs ('List') and resource ('target user id'), and the phrase 'mutual-connection overlap' distinguishes it from sibling tools like 'twitter_user_followers' (all followers) or 'twitter_check_follow_relationship' (single check).

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 'Requires an authenticated session behind your key,' which is a prerequisite for use. The concept of mutual-connection overlap implicitly indicates when to use this tool (to find known followers) versus other follower tools. However, it does not explicitly mention when not to use it or provide direct comparisons to sibling tools, which would elevate it to a 5.

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 indicate readOnlyHint=true and destructiveHint=false. The description adds value by detailing the return format ('tweets with author and metrics plus a cursor') and authentication requirements ('Requires an authenticated session behind your key'). It does not contradict annotations and provides useful 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 concise—four sentences front-loaded with the primary purpose. Every sentence provides essential information without redundancy. It efficiently covers purpose, usage, return data, and high-level guidance.

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

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

Given the tool has 6 parameters (none required) and no output schema, the description adequately covers pagination, authentication, and general return data. It could mention rate limits or typical response size, but the current completeness is sufficient for an agent to invoke the tool 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 coverage is 100%, so baseline is 3. The description enriches parameters with practical details, such as the typical range for 'count', pagination instructions for 'cursor', and usage notes for 'proxy_url' (recommended for writes). This adds significant value beyond the schema descriptions.

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

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

The description clearly states the tool retrieves the authenticated user's home timeline, specifying 'Get YOUR authenticated account's Home timeline (the 'Following'/'For you' feed), most recent first.' This verb+resource combination is specific and distinguishes it from sibling tools like twitter_advanced_search or twitter_user_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 explains when to use the tool ('to read what your account would see when it opens X') and notes the requirement for an authenticated session. It implies a read-only context but does not explicitly exclude alternative tools for similar purposes, such as twitter_advanced_search. The guidance is clear but lacks explicit when-not-to-use statements.

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. The description adds that it returns profile data and supports pagination with cursor, which are useful behavioral details beyond 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?

Three sentences, front-loaded with the main action, and no redundant information. Efficiently communicates purpose, return type, pagination, and use cases.

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

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

Given the tool's simplicity (read with two optional params), the description covers the main purpose, return type, pagination method, and typical use cases. No output schema exists, but the return is explained as 'profile data,' which is sufficient.

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

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

Schema coverage is 100%, so description does not need to add parameter info. The description mentions pagination and list_id location, but these are already in the schema. It adds no new semantic value beyond what is structured.

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

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

The description clearly states it lists members of a Twitter/X List by numeric list ID and returns profile data. It is specific but does not explicitly differentiate from sibling tools that also list users (e.g., twitter_user_followers), though those are for user lists rather than curated lists.

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

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

Provides explicit use cases: 'enumerate curated account sets, including competitor lists, industry watchlists, or media outlet lists.' This gives clear context but does not mention when not to use it or 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 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.

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

Annotations already declare readOnlyHint=true and destructiveHint=false; the description builds on this with genuinely non-obvious behavior: search-index lag causing missing recent posts, no retweets returned, and the filterable nature. This goes beyond annotations without contradicting them. A small deduction for not addressing return-format or error behavior, though pagination via cursor is mentioned.

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?

Five dense, front-loaded sentences, each earning its place: purpose → key filters → limitations/lag → alternative tool → pagination and ID location. No filler, no redundancy, and the critical differentiator ('FILTERABLE List feed') is bolded and appears early.

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 7-param list tool with 100% schema coverage, the description covers purpose, alternates, caveats, pagination, and ID discovery. With no output schema, it might briefly note the pagination response shape, but 'Paginate with cursor' plus the rich schema largely compensate. Minor gap keeps it from a 5.

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 exceptionally detailed parameter descriptions (clamping behavior, exclusive until semantics, 400 on bad format, string 'true'/'false' for include_replies). The description adds the 'Paginate with cursor' directive but this is also implied by the cursor schema entry. Per calibration, high coverage makes 3 the correct baseline since the schema carries the load.

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?

Uses a specific verb+resource pairing ('Read the posts written by the members of a public Twitter/X List, newest first, through X's search index') that fully specifies scope, ordering, and mechanism. Explicitly differentiates from sibling twitter_list_timeline by contrast ('Use twitter_list_timeline instead when...').

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 names the alternative (twitter_list_timeline) and states exactly when to choose it over this tool ('when you want the List exactly as X shows it, retweets and native ordering included'), including the tradeoff ('accept that it takes no filters'). This is textbook when-to-use-vs-alternative 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 behavioral context beyond annotations by mentioning it's a read operation with 'no daily write cap applies' and pointing out that it 'Reads through YOUR OWN registered session', implying authentication side effects. However, it does not detail potential latency or error conditions beyond the error object in the return.

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 lengthy but each sentence contributes unique information: purpose, usage, return fields, auth, and read-only status. It is structured logically, though the final sentence about read-only nature is a bit redundant with the annotations. Overall, no 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 lack of an output schema, the description provides essential return fields (media_id, state, check_after_secs, progress_percent, error object). It covers purpose, usage timing, authentication, and read-only nature. It could be more detailed about error handling or potential failures, but it is sufficiently complete for an agent to use the tool 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 provides descriptions for all parameters (media_id, ct0, proxy_url, auth_token, user_agent). The description only reiterates the auth_token/ct0 requirement and mentions media_id, without adding further detail about proxy_url or user_agent. It does mention the output parameter check_after_secs, but that is not an input parameter, so the added value is limited.

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: 'Check whether an uploaded media_id has finished processing' and distinguishes it from the upload tool by explaining the asynchronous nature. It uses specific verbs and provides a precise scope.

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 when to use it: 'before you attach it to a tweet' and explains the polling behavior: 'Poll this until then'. It also gives a clear directive to honor check_after_secs to avoid tight-looping, which serves as practical 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?

With annotations already marking the tool as non-read-only and non-destructive, the description adds valuable context: it acts as the registered account session, supports only base64 image data over JSON transport, and returns ok and the media_id. This goes beyond the structured 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 four sentences with no filler. It front-loads the core action and return value, then provides essential auth and format constraints. Every sentence contributes distinct, useful information.

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

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

Given the tool has 5 parameters, no output schema, and rich descriptions in the schema, the description covers the essential operational context: purpose, prerequisites, supported input format, and return shape. It could mention success/failure details or size limits, but it is sufficiently complete for an agent to invoke it correctly when paired with the schema.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces the meaning of media_data and the auth_token/ct0 pairing, but does not add substantial new parameter semantics beyond what the schema already documents. The return-value mention is useful but not parameter-specific.

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: 'Upload an image to X and get a media_id to attach to a tweet via twitter_create_tweet's media_ids.' This clearly states the tool's function and distinguishes it from read-only Twitter tools and the media_status sibling by emphasizing the upload-and-return-media_id flow.

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 clear usage context: it is for uploading images meant to be attached to tweets, it names the dependent tool (twitter_create_tweet), and it explains the required session setup ('register first with twitter_customer_session or twitter_user_login, or pass auth_token/ct0 for this call'). It does not explicitly list exclusions or alternative upload tools, but such alternatives are not evident among siblings.

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false, but the description adds valuable behavioral details: it reports service status and counts, zero-monitor behavior returns zeroed counts, takes no arguments, and mentions 'Free per call.' 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.