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

Beyond the annotations (readOnly, idempotent, non-destructive), it discloses two non-obvious operational facts: the call consumes 0 units but still counts against the per-minute rate limit, and its scope is restricted to the key behind this connection. Those details materially affect how an agent budgets and paces its calls, which the annotation block alone would 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?

Two compact sentences: the first front-loads what is returned, the second carries cost/limit/safety constraints. No filler, no restatement of the title, and every clause adds information an agent would otherwise have to guess.

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 zero parameters, full annotation coverage, and an output schema that documents the return shape, the description supplies exactly the missing layer: cost accounting, rate-limit impact, and key scoping. Nothing needed to invoke this correctly is absent.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline is 4. The description correctly avoids inventing parameter-like options (e.g., no account selector), reinforcing that the key identity is implicit in the connection.

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

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

States a specific verb and resource ('Check the units left on the TweetAPI API key behind this connection') and enumerates the returned fields: available units, plan allowance, PAYG balance, and per-minute rate limit. That framing cleanly separates it from every sibling tool, which all fetch tweet/user/list/space content rather than account quota 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 makes the use case clear (check remaining quota, verify plan/PAYG state) and gives a decision-relevant fact — it costs 0 units — that tells an agent this call is cheap to make preemptively. It does not explicitly say 'call this before heavy searches' or name an alternative, but no sibling overlaps, so there is little routing ambiguity to resolve.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so safety is covered. The description still earns credit for operational context the annotations do not carry: an API key is required, one request per call, and roughly 1 unit with a cost estimate returned per result. It stops short of describing throttling, error behavior, or what happens with an invalid or private community ID, so it is solid but not rich.

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

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

Three short sentences with zero waste: what it returns first, sibling routing second, cost and auth third. Information is front-loaded and each sentence carries distinct facts.

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?

An output schema exists, so return values need not be detailed, yet the description still names the key fields and mentions the cost estimate in each result. Auth requirement, request cost, and sibling alternatives round out everything an agent needs before calling this single-parameter 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 description coverage is 100% and the single communityId parameter already documents both the numeric ID and the link form, so the description adds no syntax beyond the schema. The phrase 'by community ID or community link' mirrors what the schema states; baseline 3 applies when the schema carries the 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?

Opens with a specific verb and resource ('Fetch one community's details') and enumerates the returned fields (name, description, member count, settings), plus the accepted identifier forms. It explicitly names the sibling tools for posts and members, so the agent can separate it from tweetapi_community_tweets and tweetapi_community_members without opening any schema.

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

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

States the selection condition directly: use this for the community's own details, use tweetapi_community_tweets for posts and tweetapi_community_members for members. That is explicit alternative routing for the most likely confusion set, leaving little to infer.

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 (which already declare readOnly, idempotent, openWorld, non-destructive), the description discloses the API key requirement, that each call makes exactly one TweetAPI request costing about 1 unit, that per-result cost estimates are returned, and that the operation is paginated. That is substantive operational context an agent cannot get from structured fields 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?

Four tight sentences, front-loaded with what the tool returns and followed by cost and pagination mechanics; nothing is padded. The standalone 'Read-only.' sentence slightly duplicates the readOnlyHint annotation but serves as a quick safety cue.

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 annotations covering the safety profile and an output schema covering return shape, the description only needed to cover access, cost, and paging — and it covers all three, including the exact field to pass for the next page. Nothing required for a correct invocation is missing.

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

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

Schema description coverage is 100%, so all three parameters (cursor, communityId, responseFormat) are already fully documented in the schema, including the link format and the cursor provenance. The description reinforces cursor paging but adds no syntax or constraint details beyond what the schema already states, so the baseline 3 applies.

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

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

States a specific verb and resource plus a scope qualifier: 'Fetch one page of posts with photos or videos from a community, as on its Media tab.' The media-type restriction and community scoping make it clearly distinguishable from siblings like tweetapi_community_tweets or tweetapi_user_photos without opening any schema.

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

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

The 'Media tab' framing plus the explicit 'by community ID or community link' gives clear context for when this is the right call. It does not, however, name the alternative to use when the agent wants text-only community posts (e.g. tweetapi_community_tweets), so there is no explicit when-not 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 readOnly/idempotent/non-destructive, and the description adds material context beyond them: API-key requirement, one request per call, typical cost of 1 unit, and a per-result cost estimate. It also explains the exact pagination contract via completeness.nextCursor, so the agent knows both the cost model and how to resume.

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

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

Three short sentences, front-loaded with the action, then the disambiguation, then cost and pagination mechanics. Every clause carries information an agent would otherwise have to guess.

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 an output schema present the description need not explain return values, and it instead spends its words on auth, cost, and cursor-based resumption — exactly the gaps structured fields do not fill. Nothing needed to invoke and continue correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description nonetheless adds procedural meaning by tying the cursor parameter to the previous result's completeness.nextCursor and reinforcing that communityId accepts either a numeric ID or a link. The responseFormat enum is left entirely to the schema, which caps it at 4.

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

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

States a specific verb and resource ('Fetch one page of a community's members') plus the accepted identifier forms (community ID or link). It also distinguishes itself from tweetapi_community_details by assigning member-count lookups to that sibling, so an agent can separate the two without opening schemas.

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 routes member-count queries to tweetapi_community_details and gives concrete continuation instructions for pagination. It does not address the nearest ambiguous sibling, tweetapi_list_members (list vs community members), leaving that distinction to naming inference, which keeps it below 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?

Beyond the readOnly/idempotent annotations it discloses the auth requirement (TweetAPI API key), the per-call request and unit cost, and that results carry a cost estimate. It also spells out the pagination contract, including the exact field to pass back (completeness.nextCursor).

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?

Six short sentences, front-loaded with the core action and scope, followed by routing, cost, and pagination details. Each sentence carries distinct information with no 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?

Complete for a 2-parameter, read-only search with an output schema: the description covers scope, aliases, cost, and pagination rather than restating return fields. Nothing an agent needs in order to call it correctly is left out.

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, but the description adds practical meaning by tying cursor to completeness.nextCursor in the previous result and stating that it should be omitted on the first call. That goes slightly beyond the schema text, which is nearly identical but less explicit about the omit case.

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

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

States a specific verb and resource ('Search X communities by keyword') plus the scope of a single page. It explicitly separates itself from tweetapi_search (posts and accounts), so an agent can choose between them without opening either schema.

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

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

The description names the follow-up tools (tweetapi_community_details, tweetapi_community_tweets) and gives a clear alternative for a different resource type (tweetapi_search). What is missing is any when-not-to-use condition or guidance on query breadth, so it stops just short of a full routing rule.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, and the description adds real context beyond them: an API key is required, one TweetAPI request per call, typically 1 unit cost, and each result carries a cost estimate. The pagination trait (one page per call, loop on completeness.nextCursor) is behavior an agent could not infer from 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?

Front-loads the core action and scope, then layers the alternative, safety, cost, and pagination notes — each sentence carries distinct information. The cost sentence is slightly dense ('one TweetAPI request per call, usually costing 1 unit; each result includes a cost estimate') but nothing is redundant.

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 paginated read endpoint with an output schema, everything an agent needs is present: identifier formats, sort options, pagination loop, cost/auth expectations, and a sibling for the media-filtered variant. Return-value detail is correctly left to the output 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 coverage is 100%, with cursor, sortBy, communityId, and responseFormat all documented in the schema itself. The description restates the page/sortBy/cursor semantics but adds no syntax or format detail beyond what the schema already provides, so baseline 3 applies.

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

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

States a specific verb and resource ('fetch one page of posts in a community'), the accepted identifiers (community ID or link), and the ordering control (sortBy). It also names the sibling it is not — tweetapi_community_media for photo/video-only posts — so an agent can distinguish it without opening schemas.

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

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

Gives explicit routing for the media-only case ('Use tweetapi_community_media for only the posts with photos or videos') and clear pagination instructions via completeness.nextCursor. It does not distinguish against other community siblings such as community_search or community_details, so the guidance is strong but not exhaustive.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description goes beyond them usefully by disclosing the failure mode (TWEETAPI_DOCS_PAGE_NOT_FOUND) and the cost/auth profile ('Free: uses no API key or units'), which an agent needs for planning. It does not describe payload size or pagination of the returned docs section, keeping it short of a 5.

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

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

Two tight sentences with zero filler: the return payload is front-loaded, followed by the path/keyword/error contract and the cost note. Every clause carries information an agent would otherwise have to guess.

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 single required parameter, full schema coverage, no output schema and complete annotation coverage, the description supplies precisely what is missing: return shape, match precedence, error behavior and cost. Nothing an agent needs to invoke this correctly is absent.

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

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

Schema coverage is 100% and the parameter description already states that a path yields the most precise match, so the description's restatement of path-vs-keyword behavior adds little new meaning. Baseline 3 applies when the schema carries 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 uses a specific verb and resource ('Return the full reference for one TweetAPI endpoint') and enumerates exactly what comes back: method, path, title, whole docs section, parameters, cost and example request. It implicitly distinguishes itself from docs_search by promising a single endpoint rather than a result list, but it never names that sibling explicitly, so routing still takes a small inference.

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?

Clear operating guidance: an exact path like /tw-v2/user/followers returns that endpoint, a keyword returns the single best match, and a miss returns TWEETAPI_DOCS_PAGE_NOT_FOUND. What is missing is an explicit alternative — the description never points to tweetapi_docs_search or tweetapi_endpoint_lookup for cases where the agent wants multiple matches or a lookup rather than full docs.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds value beyond them by stating the tool is free and needs no API key or units, plus the shape of each returned match. It does not discuss result quality thresholds or what happens on zero matches.

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 action and return shape, followed by usage routing and the cost note. Nothing redundant.

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

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

No output schema exists, and the description compensates by listing the returned fields. Combined with the explicit alternative sibling and the zero-cost note, an agent has everything needed to call this 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% and both parameters are documented with ranges and a default for limit, so the schema carries the burden. The description only implies keyword matching and ranking by score; it adds little beyond 'best-matching', so baseline 3 applies.

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

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

Specific verb and resource: 'Search TweetAPI's public docs by keyword' with explicit statement of what comes back (title, snippet, source URL, score). It is clearly differentiated from the sibling tweetapi_docs_get_page, which it names.

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 when-to-use ('general questions such as pricing, limits, errors or authentication') and when-to-use-the-alternative ('for one endpoint's full reference, use tweetapi_docs_get_page'). No inference required.

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, idempotent, non-destructive, open-world behavior, so the bar is low, yet the description adds real value: a result cap of 10, the snippet-plus-source-URL return format (no output schema exists), and 'Free: uses no API key or units' which discloses cost/auth requirements. Minor omission: no statement about result ranking or what happens when nothing matches.

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

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

Three short sentences, zero filler: what it does and what it returns, when to use it plus the follow-up call, then the cost/auth note. Front-loaded with the core capability.

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

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

For a single-parameter lookup with no output schema, the description supplies the return format, result limit, and cost profile, which is close to complete. It falls short only on disambiguating against tweetapi_docs_search in a 47-sibling toolset where that overlap is a real selection risk.

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

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

Schema coverage is 100% and the schema already explains the path-vs-keyword distinction and that a path gives the most precise match. The description only echoes 'path or keyword', adding no syntax or format detail beyond the schema. Baseline 3 applies.

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

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

States a specific verb+resource ('Find the TweetAPI endpoint docs') and the return shape (up to 10 matching sections as snippets with source URLs). However, it never distinguishes itself from the near-identical sibling tweetapi_docs_search, so an agent still has to guess between the two.

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 it ('when you don't know the exact endpoint yet') and hands off to a named alternative (tweetapi_docs_get_page) for the full reference. The gap is that the competing docs_search sibling is not mentioned, so no exclusion rule exists for 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 readOnly, idempotent, openWorld and non-destructive, so 'Read-only' is redundant, but the description adds genuinely new behavior: a TweetAPI API key is required, one request is made per call, it usually costs 1 unit, and results carry a cost estimate. That cost and auth context is not derivable from any structured field.

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 resource and payload, then alternatives, then cost/auth caveats. Slightly padded by the redundant 'Read-only' and repeated cost phrasing ('usually costing 1 unit' plus 'cost estimate'), but nothing is wasted overall.

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?

An output schema exists, so return values need no prose explanation, yet the description still previews the shape usefully. For a single-parameter read tool, auth, cost, request count and sibling routing are all covered, leaving nothing an agent needs missing.

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

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

Schema coverage is 100% and the schema already documents the listId as 'Numeric list ID, or a list link such as https://x.com/i/lists/1234567890'. The description's 'by List ID or List link' restates that without adding format or edge-case detail, so the baseline 3 applies.

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

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

States a specific verb and resource ('Fetch one X List's details') and enumerates what comes back: name, description, owner, member and follower counts, visibility. It also names the three sibling list tools it is not, so an agent can separate it from tweetapi_list_members, tweetapi_list_tweets and tweetapi_list_followers without reading any schema.

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

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

Routes the agent explicitly: use this for details, tweetapi_list_tweets for posts, tweetapi_list_members for accounts in the list, tweetapi_list_followers for followers. Each alternative is paired with the condition that selects it, which is exactly what the crowded list_* sibling set requires.

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?

Goes well beyond the annotations by disclosing the auth requirement (TweetAPI API key), the request/cost model (one request per call, ~1 unit, cost estimate per result), and the pagination contract. Annotations already cover safety and idempotency, and the description adds the operational context they cannot.

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

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

Front-loaded with purpose, then scope disambiguation, then cost, then paging. Dense but nearly every clause carries information; the single paragraph is slightly crowded compared with splitting paging into its own 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?

An output schema exists, yet the description still supplies the one piece an agent needs to act on it (where nextCursor comes from). Auth, cost, scope, and paging are all covered for a simple three-parameter 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% so parameters are already documented, but the description adds meaning the schema lacks: it ties cursor to the output path completeness.nextCursor and explains the paging loop. That is real value above baseline 3.

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

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

States a specific verb and resource (fetch accounts that follow a list) and explicitly frames the inverse relationship with tweetapi_list_members, so an agent can tell the two apart without reading schemas.

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?

Names the sibling tool to use for the opposite set (members) and covers the pagination workflow. It does not address how this differs from the user-level follower tools in the sibling list, which would be the remaining ambiguity.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is given. The description still adds real operational context beyond them: an API key is required, each call is one request costing roughly 1 unit, and results carry a cost estimate. It does not disclose rate limits, error conditions, or what happens with private/suspended Lists, so this is good-but-not-rich for an annotated tool.

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

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

One front-loaded paragraph: purpose first, then sibling routing, then auth/cost behavior, then pagination mechanics. Every sentence carries distinct information with no redundant restatement of the name or title.

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

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

An output schema exists, so return values need not be described, yet the description supplies the key return detail an agent needs to continue paging (completeness.nextCursor). With auth, cost model, scope and pagination all covered, nothing material is missing for a read-only paginated list tool.

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

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

Schema description coverage is 100%, so the schema already documents cursor, listId and responseFormat including the enum meaning, establishing a baseline of 3. The description adds the pagination loop ('call again with cursor set to this result's completeness.nextCursor'), which is useful workflow context, but it does not explain listId link-vs-numeric handling or compact-vs-full tradeoffs beyond the schema.

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

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

States a specific verb and resource ('Fetch one page of the accounts that are members of a List'), including the lookup key (List ID or List link). It immediately distinguishes itself from tweetapi_list_followers and tweetapi_list_details, so an agent can choose correctly without opening a schema.

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

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

Names two concrete alternatives with the condition each covers ('accounts that follow the List' vs 'its counts'), which is exactly the when-to-use-which routing an agent needs in a 50-sibling namespace. No exclusions are stated, but the sibling routing is explicit and unambiguous.

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

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

Annotations already declare read-only and idempotent, and the description adds real context beyond them: an API key requirement, one request per call at ~1 unit cost with a per-result cost estimate, and the non-obvious fact that a short page is not necessarily the last one. That pagination caveat is exactly the kind of behavioral detail 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?

Front-loaded with purpose, then chaining, then safety/cost, then pagination — a sensible order with no filler. The final sentence partially restates the cursor parameter description, a minor 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?

An output schema exists, so return shape need not be re-explained, and the description still covers auth, cost, page-size caveats, and continuation, which are the things an agent must know to invoke it correctly. Nothing material is missing for a cursor-paginated search tool.

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

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

Schema description coverage is 100%, so all three parameters (including the responseFormat enum and cursor provenance) are already documented in structured form. The description reinforces cursor handling but adds no syntax or constraint beyond what the schema states, so baseline 3 applies.

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

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

States a specific verb and resource ("Search X Lists by keyword") plus the exact scope ("fetch one page of matching Lists"), which distinguishes it from the ID-based siblings like tweetapi_list_details and tweetapi_list_tweets. An agent can select it without opening the schema.

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

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

Gives explicit downstream routing ("Use the List IDs with tweetapi_list_tweets or tweetapi_list_members") and precise pagination instructions for when to re-call with a cursor. It does not explicitly say when to prefer this over other search entry points such as tweetapi_search, so it falls short of full alternative coverage.

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/idempotent safety, yet the description adds genuinely new behavior: an API key is required, one request per call, roughly 1 cost unit with a per-result cost estimate, and the exact next-page mechanism via completeness.nextCursor. This is the kind of context structured fields do not carry.

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

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

One dense paragraph, front-loaded with the action and scope, then alternatives, cost, and pagination in priority order. Every sentence carries information the agent needs; nothing is filler.

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

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

With an output schema present, return-value detail is unnecessary, and the description covers everything else an agent needs: auth requirement, cost model, pagination loop, and the sibling for membership. Nothing material is missing for a paginated 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%, so cursor, listId, and responseFormat are already documented. The description restates listId accepted forms and cursor semantics but adds no new meaning for responseFormat, so the baseline of 3 applies.

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

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

States a specific verb and resource ("Fetch one page of the posts in a List's timeline") and scopes the input domain (by List ID or List link). It is clearly distinguishable from siblings such as tweetapi_list_members or tweetapi_user_tweets without opening any schema.

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

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

Explicitly routes the agent to tweetapi_list_members for the membership question, and gives clear continuation guidance for paging. It does not state exclusions against other post-listing siblings (e.g. user_tweets), so it stops short of full when/when-not coverage.

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 this a non-destructive, idempotent, open-world read, so the safety profile is covered. The description adds genuinely new behavioral context beyond them: it is free and makes no API calls, and it discloses the shape of the returned content. What it does not say is whether the guidance is static or reflects the current API version.

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 what is returned, then the routing condition, then the cost note. Nothing is padded and every clause carries information an agent would otherwise have to guess.

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

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

There is no output schema, so the description correctly takes on the burden of describing return contents, and it does so for a simple two-string-input tool. The remaining gap is the undocumented effect of 'task' on the response beyond the schema's note that it is echoed back.

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

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

Schema description coverage is 100%, so both parameters are already documented and the baseline is 3. The description adds little beyond the schema, and it actually narrows the language list to 'Python or Node.js/TypeScript' while the schema accepts JavaScript too — a small inconsistency rather than added meaning. The 'task' parameter is not mentioned at all in the description.

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

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

States a specific verb and resource ('Return setup guidance for calling TweetAPI from your own code') and enumerates exactly what is returned: SDK package name, install command, import example and notes. It also names what it is not ('to fetch data now, use the live tools instead'), which separates it cleanly from the ~50 data-fetching 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?

Gives both sides of the routing decision: use this when writing an app that calls TweetAPI, use the live tools when you want data now. The only minor gap is that it does not point at the docs siblings (tweetapi_docs_get_page, tweetapi_docs_search), but the primary alternative is named explicitly.

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

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

Annotations only cover the safety profile (readOnly, idempotent, openWorld, non-destructive); the description adds authentication requirements (TweetAPI API key), per-call request/cost economics (one request, usually 1 unit), that results carry a cost estimate, and the exact pagination mechanism. Those are material behaviors an agent cannot infer from annotations or schema.

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

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

Four tight sentences ordered by importance: what it does, how `type` chooses results, which siblings to use instead, then operational constraints and pagination. No filler, and the routing information is front-loaded ahead of the cost 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?

With an output schema present, return shape need not be explained, and the description still covers auth, cost, and pagination adequately. The only soft spot is that the compact-vs-full responseFormat tradeoff is left entirely to the schema, which is a minor gap rather than a blocker.

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 description largely restates the schema's own text for `type` and `cursor` rather than adding new meaning. It does tie pagination concretely to "this result's completeness.nextCursor", but that is also spelled out in the schema, so the baseline of 3 applies.

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

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

Uses a specific verb and resource ("Search X for posts or accounts"), anchors it to a familiar analogue ("like the x.com search box"), and explicitly names the two siblings it is not (tweetapi_list_search, tweetapi_community_search). An agent can route correctly without opening any schema.

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

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

The description explains what the `type` values select and then gives explicit when-not guidance by redirecting Lists and communities to their dedicated tools. Combined with the sibling list containing list_search and community_search, the decision boundary is unambiguous.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, and the description goes beyond them by disclosing the authentication requirement (TweetAPI API key), the request volume (one request per call), and the cost profile (~1 unit, with a per-result cost estimate). These are exactly the operational facts an agent needs before calling a metered external endpoint.

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

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

Three short sentences with the core purpose front-loaded, followed by cost/auth context and no redundant restatement of the title. Every clause carries information an agent can act on.

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

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

For a single-parameter read tool with an output schema (so return values need no explanation), the description covers purpose, input forms, auth, cost, and the dependency on the streaming sibling. Nothing an agent needs in order to call it correctly is missing.

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

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

Schema description coverage is 100% and the spaceId property already documents both accepted formats, including the full Space link example. The description restates "space ID or Space link" but adds no format, normalization, or error-handling detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ("Fetch details for a Space by its space ID or Space link") and adds a distinguishing payload detail: it returns the media key needed by tweetapi_space_stream_url. That lets an agent separate it from the sibling stream-URL tool without opening either schema.

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

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

Implies a usage sequence by noting the returned media key is needed for tweetapi_space_stream_url, which is a concrete when-to-use signal. It does not explicitly state when-not to use it or name any other alternative among the ~50 siblings, so it falls short of 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 declare readOnly/idempotent/non-destructive/openWorld, and the description adds context beyond them: API key requirement, one request per call, ~1 unit cost, and that each result carries a cost estimate. The notable omission is URL lifetime/expiry, which matters for a stream URL an agent may pass on to a consumer.

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

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

Front-loaded with the action and the required input source, then cost/auth facts. Every sentence carries information, though "Read-only." restates readOnlyHint=true and is mild 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 one-parameter tool with a 100% covered schema and an output schema, the description covers the pieces that structured fields can't: upstream dependency, auth, and cost model. Only the stream URL's lifetime/expiry behavior is left unstated.

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

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

Schema coverage is 100% and the single parameter is already documented with its source, so the schema does the heavy lifting. The description only reinforces provenance of mediaKey and adds no format or validation detail beyond it — baseline 3 applies.

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

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

States a specific verb and resource ("Fetch the audio stream URL for a Space") and names the sibling that produces the required input (tweetapi_space_by_id), so an agent can distinguish it from the other space/community tools without opening the schema.

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

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

Gives concrete workflow guidance: the mediaKey must come from a tweetapi_space_by_id result, which establishes the prerequisite call ordering. It does not state when *not* to use it or what happens if the Space has ended, but the chaining context is the main ambiguity an agent would face.

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

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

Annotations already declare readOnly, idempotent, non-destructive and openWorld, so the safety profile is covered without the description. The description adds genuinely new context beyond them: "Free: uses no API key or units," which tells the agent there is zero cost and no credential prerequisite for calling it — a meaningful behavioural fact absent from the structured fields. It does not mention rate limits or result size, keeping it at 4 rather than 5.

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

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

Three tight sentences: what it returns, how to filter, and when to use it, plus the free-cost note. Content is front-loaded with the return shape and nothing is repeated or padded.

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

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

There is no output schema, but the description compensates by enumerating the returned fields, so an agent knows what to expect. With all three filters optional, zero required parameters, and cost/auth behaviour stated, nothing essential for a correct first call is missing.

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

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

Schema description coverage is 100%, and each parameter already carries its own description with a concrete example (e.g. /tw-v2/user/followers). The description's "Filter it with toolName, endpointPath or category" only restates the parameter names without adding syntax, matching rules beyond "Exact tool name," or precedence when multiple filters are combined, so the baseline 3 applies.

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

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

The description opens with a specific verb and resource ("List the tools on this server as JSON") and enumerates exactly what each entry contains — name, description, category, endpoint, estimated cost, response formats, input schema. That is a precise inventory of a catalog tool, clearly distinct from siblings like tweetapi_endpoint_lookup or tweetapi_docs_search, which operate on endpoints or docs rather than the whole tool set.

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

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

"Use it to pick the right tool or check costs before calling live tools" gives a clear when-to-use context, and the filter list implies narrowing by name, path or category. It stops short of naming an exclusion or an alternative sibling (e.g. when to prefer tweetapi_endpoint_lookup for a known endpoint), so it is clear but not fully routed.

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 safety (readOnly, idempotent, non-destructive, open-world), and the description adds genuinely new operational context: no pagination, API-key requirement, one request per call, ~1 unit cost, and that results include a cost estimate. That is exactly the kind of cost and auth disclosure annotations cannot express.

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

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

A compact burst of clauses, front-loaded with purpose and immediately followed by the downstream-usage detail and cost model. No sentence is filler; every clause carries distinct information.

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

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

For a zero-parameter list endpoint with an output schema, the description covers purpose, downstream use, pagination behavior, auth, and cost. Nothing an agent needs in order to call it correctly is missing.

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

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

Zero parameters, so there is no parameter semantics to explain; the description instead documents the return fields (woeid, countryCode) and their downstream use. This is the expected baseline for a no-arg tool.

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 with a specific verb and resource ('List the locations X serves trends for'), scopes it (worldwide, countries, cities), and explicitly identifies its role as the feeder for tweetapi_trends. An agent can distinguish it from the sibling trends tool without opening any schema.

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

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

The description makes the workflow clear: call this first, then pass the woeid/countryCode to tweetapi_trends. It does not state exclusions or when not to bother (e.g., if you already know the woeid), so it falls short of full when/when-not coverage.

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 read-only, idempotent and open-world, and the description adds substantial context on top: it requires a TweetAPI API key, makes exactly one request per call at roughly 1 unit, surfaces a cost estimate in each result, and specifies the error behavior for unsupported countries.

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 tight sentences, front-loaded with what is fetched before the parameter rules, then cost and error behavior. No filler and nothing repeated without 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?

An output schema covers return shape, so the description correctly focuses on selection rules, prerequisites, cost, and failure modes. Nothing an agent needs in order to call this correctly is missing.

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

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

Schema coverage is 100% and the schema already documents the mutual exclusivity and formats, so guidance like 'two-letter code such as US' is somewhat duplicative. The description still adds meaning the schema lacks by stating that omitting both parameters yields worldwide trends.

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

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

States a specific verb and resource ('Fetch the trending topics X shows') plus the three scope modes (worldwide, country, location). It also distinguishes itself from the sibling tweetapi_trend_locations by naming it as the source of woeid values rather than a substitute.

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

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

Gives explicit selection rules: pass country OR woeid, never both, omit both for worldwide, and use tweetapi_trend_locations to obtain a woeid. It also warns that an unsupported country fails with not found rather than falling back to worldwide, which prevents a common misuse.

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 read-only, idempotent, non-destructive, open-world, but the description adds cost and auth context they cannot express: an API key is required, one request is made per call, the cost is usually 1 unit, and each result carries a cost estimate. It also discloses the pagination contract (one page per call) and the responseFormat trade-off, neither of which is inferable from the safety 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?

Four sentences, front-loaded with what the tool returns before routing advice and operational constraints. Every sentence carries load: payload scope, alternatives, auth/cost, pagination contract. No restatement of the title or filler.

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

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

The tool is a paginated, billed, authenticated read with an output schema; the description covers all four concerns and explicitly defers return-value detail to the output schema while still naming the key cursor field. An agent has everything needed to call it correctly, page it, and budget for it.

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, but the description adds cross-field meaning the schema only states locally: it ties the cursor input to the output field completeness.nextCursor, explaining the pagination loop end to end. sortBy and responseFormat semantics are left to the schema, which already documents them fully with enums and defaults.

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 ('Fetch one tweet with full details') and goes further by naming the payload shape: parent tweets for replies plus a page of replies. It explicitly distinguishes itself from tweetapi_tweet_metrics (counts only) and tweetapi_tweet_details_by_ids (many tweets), so an agent can differentiate it from siblings without reading schemas.

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 names two concrete alternatives with the exact condition that selects each: metrics for counts only, details_by_ids for many tweets. It also gives operational guidance for pagination ('call again with cursor set to this result's completeness.nextCursor') and for omitting the cursor on the first page, leaving nothing to inference.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description goes well beyond them: it names the exact place incomplete results surface (completeness.notReturned), states the auth requirement (TweetAPI API key), and gives request/cost behavior (one request per call, ~1 unit, per-result cost estimate). That is precisely the operational detail structured fields cannot carry.

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

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

Four short sentences, front-loaded with the capability and limit before caveats. The only dead weight is 'Read-only.', which merely restates readOnlyHint and earns no new information for the agent.

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

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

For a two-parameter read tool with an output schema and full annotations, everything an agent needs to call it correctly is present: input forms, batch ceiling, what is excluded, how partial results are reported, and the cost/auth profile.

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

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

Schema coverage is 100% and both parameters are documented there in detail, so the baseline is 3. The description only restates the ID-or-link input and the 200 cap and says nothing about the responseFormat trade-off, which the schema already explains.

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

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

States a specific verb and resource with scope: fetch details for up to 200 tweets by post ID or post link. The batching limit implicitly separates it from the singular tweetapi_tweet_details, but no sibling is named explicitly, so the differentiation is inferred rather than stated.

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 batch size and 'No replies are included' exclusion imply the use case (bulk hydrate known IDs, not conversation retrieval), but the description never says when to prefer tweetapi_tweet_details or tweetapi_search, nor states prerequisites for obtaining the IDs.

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

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

Annotations only declare read-only/idempotent/non-destructive/open-world, but the description adds auth requirements (TweetAPI key), per-call cost and the presence of a cost estimate in results, one-request-per-call semantics, and the empty-page behavior. It also makes pagination state explicit, which the annotations say nothing about.

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

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

A single front-loaded paragraph with no wasted clauses: purpose, public-visibility note, empty-result edge case, safety, auth/cost, then pagination. Each sentence contributes something an agent needs before calling.

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 an output schema and rich annotations, and the description still covers the gaps those don't: credentials, cost model, one-page semantics, and the empty-result case. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3, and the description largely restates schema content (tweetId accepts a link; cursor comes from completeness.nextCursor). It adds modest value by framing the cursor as the continuation loop against the output field, but says nothing about responseFormat, which the schema documents instead.

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

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

States a specific verb and resource ('Fetch one page of the replies that a post's author has hidden') plus the accepted identifier forms (post ID or post link). That is precise enough to separate it from sibling reply-oriented tools such as tweetapi_tweet_details, tweetapi_tweet_quotes, and tweetapi_user_tweets_and_replies without opening a schema.

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

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

The scope ('hidden replies are public on X') and the empty-result condition make the intended use clear, and the pagination sentence tells the agent exactly how to continue. It stops short of naming a sibling to use for non-hidden replies, which is the main remaining gap.

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 repeats what annotations already declare ('Read-only', non-destructive) but does add genuinely new behavioral facts: an API key is required, one TweetAPI request is made per call, and each call usually costs 1 unit with a cost estimate returned. It does not explain what a 'unit' is or what happens on invalid/private/deleted posts, so the disclosure is useful but incomplete.

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 compact sentences, front-loaded with the core action and immediately followed by the scoping constraint and the alternative tool. No filler or repetition; every clause carries information an agent can act on.

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?

Auth, cost, request count, input flexibility, and sibling routing are all covered, and an output schema exists so return values need not be described. The only soft spot is the unexplained cost unit and no note on failure modes for deleted or protected posts.

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 documents the single tweetId parameter including the link format (https://x.com/jack/status/20). The description's 'Accepts a post ID or post link' merely restates the schema, adding no new syntax or edge-case meaning.

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

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

States a specific verb and resource ('Fetch only the engagement counts ... for one tweet') and enumerates exactly which counts are returned (likes, retweets, replies, quotes, bookmarks, views). It also scopes the tool negatively ('without the conversation'), which separates it from the heavier tweet-details 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?

Explicitly routes the agent to the alternative: 'Use tweetapi_tweet_details for the full tweet.' What is missing is guidance against the other adjacent siblings (tweetapi_tweet_quotes, tweetapi_tweet_retweets, tweetapi_tweet_hidden_replies), which also take a post ID and could be confused with this one.

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?

Goes well beyond the annotations (which only establish read-only, idempotent, non-destructive, open-world) by disclosing the auth requirement (TweetAPI API key), the request/cost model ('one TweetAPI request per call, usually costing 1 unit'), that results carry a cost estimate, and the exact pagination mechanism. These are the operational facts an agent needs before spending quota.

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 compact sentences, front-loaded with the purpose before the alternatives, then safety/cost, then pagination. No sentence restates the name or title, and each carries a distinct operational fact.

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 paginated read with an output schema and rich annotations, nothing essential is missing: identity input forms, sibling routing, cost/quota implications, and the cursor loop are all covered, and return-shape explanation is rightly delegated to the output 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 schema already documents all three parameters, including the accepted post-ID-or-link forms and the full-vs-compact responseFormat enum. The description reinforces cursor usage by pointing at 'this result's completeness.nextCursor,' which is mild added value, but it says nothing about responseFormat or the compact field-dropping tradeoff. Baseline 3 is appropriate.

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

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

States a specific verb and resource — 'Fetch one page of quote posts of a post (posts that quote it), by post ID or post link' — and immediately disambiguates from the two nearest siblings that return adjacent relationship types. An agent can distinguish this from retweets and details without opening any schema.

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

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

Explicitly routes the agent: 'Use tweetapi_tweet_retweets for plain reposts and tweetapi_tweet_details for replies,' which names the alternatives and the condition selecting each. It also gives the continuation condition — call again with the cursor when the page is exhausted.

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?

Goes well beyond the annotations (readOnly/idempotent/non-destructive) by disclosing the API-key requirement, that each call makes exactly one TweetAPI request and usually costs about 1 unit, that results carry a cost estimate, and that responses are single pages requiring cursor chaining. That is exactly the operational context an agent needs before calling.

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 tight sentences, front-loaded with the action and scope, then the sibling disambiguation, then cost/auth constraints, then pagination. Every sentence carries distinct, useful information with no 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?

Return values are covered by the existing output schema, so the description need only handle purpose, prerequisites, cost, and pagination — all of which it does. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100%, so all three parameters are already documented in the schema, including the cursor's origin and the full/compact responseFormat trade-off. The description reinforces cursor usage but adds no new syntax or format detail, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Fetch one page of the accounts that reposted a post'), plus accepted input forms (post ID or post link) and page scope. It is clearly distinguishable from the quote-post sibling, which it names explicitly.

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

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

Names the alternative to use for quote posts (tweetapi_tweet_quotes) and the condition that selects it, and states the pagination procedure: call again with cursor set to completeness.nextCursor. There is no ambiguity about which tool handles reposts versus quotes.

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?

Goes well beyond the annotations by disclosing that the post is unchanged, that an API key is required, that each call makes exactly one request costing roughly 1 unit, and that results carry a cost estimate. Annotations already cover readOnly/idempotent safety, so this is pure added value about cost and auth.

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

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

Four short sentences, front-loaded with the action and identifier forms, then side effects, then cost. No sentence is redundant with the schema or annotations in a wasteful way.

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

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

For a two-parameter, read-only, single-request tool with an output schema and full annotation coverage, the description covers everything the agent needs: what it does, how to identify the target, that nothing is mutated, and the cost model.

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 both parameters are documented there, so the baseline is 3. The description only restates the identifier forms ('post ID or post link') that the tweetId schema already documents and adds nothing about dstLang code conventions.

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

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

States a specific verb and resource ('Translate one post's text into another language') plus the accepted identifier forms, scoping it to a single post. This clearly separates it from sibling readers like tweetapi_tweet_details or tweetapi_search, which do not translate.

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

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

Gives clear context (translate one post's text; use tweetapi_tweet_details to read the original and its replies), which implicitly routes the agent correctly. It stops short of explicit exclusions, e.g. it never says what to do for multi-post translation or that no bulk variant exists.

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

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

Annotations already declare readOnly, idempotent, open-world, and non-destructive, so the safety profile is covered. The description adds real value beyond that: it requires a TweetAPI API key, issues exactly one request per call, usually costs 1 unit, and returns a per-call cost estimate. It stops short of describing pagination or failure behavior, keeping it below a 5.

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

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

Three tight sentences: purpose and payload first, sibling routing second, operational constraints last. Every clause carries information (fields returned, alternative tool, auth, cost) with no filler.

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

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

For a single-optionality-free parameter read tool with a full output schema, the description covers everything an agent needs to select and invoke it: what it returns, how to identify the target, what it costs, and which sibling to use instead. Return-value details are correctly left to the output 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 coverage is 100% and the schema already documents that the username field accepts a plain username, an @handle, or a profile link such as https://x.com/jack. The description restates the same three forms without adding format rules or edge cases, so the schema is doing the heavy lifting — the baseline 3 applies.

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

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

States a specific verb ("Fetch") and a specific resource ("About this account details") and enumerates the contents (location, verification, username history, affiliates, creation method). It explicitly distinguishes itself from the regular profile tool tweetapi_user_by_username, so the agent can differentiate it from siblings without opening a schema.

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

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

The description names an alternative (tweetapi_user_by_username) and the condition that selects it ("for the regular profile"), making the use/use-not boundary explicit. The accepted identifier forms (username, @handle, profile link) further clarify the calling 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?

Beyond the annotations (which already declare readOnly/idempotent/non-destructive), the description discloses authentication requirements, per-call cost behavior (usually 1 unit, cost estimate in each result), pagination contract, and empty-result semantics. That is exactly the operational context annotations cannot express.

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

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

Front-loaded with the purpose, then cost, then pagination — a sensible order with no filler sentences. 'Read-only.' duplicates the readOnlyHint annotation and could be dropped, but the overall length is proportionate to the tool's 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?

With an output schema present and rich annotations, the description still supplies the pieces an agent needs to call it correctly: auth, cost, single-page paging mechanics, and empty-list behavior. Nothing material is missing for a paginated read endpoint.

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 three parameters are fully documented in the schema, including the cursor/nextCursor loop and the responseFormat enum trade-off. The description's pagination sentence restates the cursor parameter's schema text rather than adding new meaning, so baseline 3 applies.

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

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

States a specific verb and resource — 'Fetch one page of the accounts affiliated with a business profile' — and anchors it to a recognizable surface ('as on its Affiliates tab'). No sibling tool covers affiliates, so an agent can route here unambiguously.

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

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

Gives clear usage context: default affiliate group only, empty list for profiles with none, and an explicit instruction for retrieving subsequent pages. It stops short of naming an alternative tool or stating exclusions (e.g., that non-business profiles aren't applicable), and the username-vs-userId routing advice lives only in the schema.

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 read-only and idempotent, but the description adds real operational context beyond them: TweetAPI API key requirement, one request per call costing roughly 1 unit, and a per-result cost estimate. It does not cover error or rate-limit behavior, but for a paged read tool this is substantial added disclosure.

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 short sentences, each carrying distinct information: scope, exclusion, auth and cost, and pagination. Key constraints are front-loaded and nothing is repeated.

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 an output schema exists, return-shape explanation is unnecessary, and the description covers scope, paging, cost, and prerequisites. A small gap remains around ordering or page-size behavior, but an agent has what it needs to call 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?

Schema coverage is 100%, so cursor, userId, and responseFormat are already documented in the schema, including the username-lookup guidance. The description's cursor sentence largely restates the schema and adds no new format or constraint detail, so baseline 3 applies.

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

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

States a specific verb and resource: 'Fetch one page of the posts that published a user's X Articles,' plus the exact payload (title and preview text). This clearly separates it from sibling listing tools like tweetapi_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?

Explicitly states a limitation ('full Article text is not included') and routes the agent to tweetapi_tweet_details with the post ID for the full text. Continuation is spelled out ('to get the next one, call again with cursor set to this result's completeness.nextCursor').

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered; the description still adds real context beyond them: API-key requirement, one request per call, ~1 unit cost, and a per-result cost estimate. What it leaves out (pagination, error behavior) is secondary for a single-record lookup.

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

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

Three short sentences, front-loaded with the operation and its scope, then the alternative, then the operational constraints. No redundancy or filler.

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

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

An output schema exists, so return values need no explanation, and the description covers the remaining caller concerns: auth, request volume, cost, and where the cost estimate appears. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so both userId and responseFormat are already documented in the schema, including the username fallback and the full/compact trade-off. The description adds no further parameter detail, which is the expected baseline when the schema does the work.

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

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

States a specific verb and resource ('Fetch one public user profile by numeric user ID') and immediately distinguishes itself from the batch sibling tweetapi_user_by_ids, so an agent can pick the right tool without opening either schema.

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

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

Explicitly routes the multi-user case to tweetapi_user_by_ids, and the schema plus description together make clear that username lookups need tweetapi_user_by_username. The when-to-use condition is stated rather than implied.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, open world), and the description goes well beyond them: it discloses the API key requirement, one request per call, an approximate cost of 1 unit, and that per-result cost estimates are returned. It also explains the partial-failure behavior via completeness.notReturned, which is exactly the kind of behavioral detail an agent cannot infer from structured fields.

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

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

Four tight sentences: purpose and limit first, then the partial-result note, then the sibling routing, then operational constraints. Every sentence carries information, though the cost clause is slightly dense and could be split for faster scanning.

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?

An output schema exists, so return-shape explanation is not owed, and the description still adds auth, cost, and partial-result semantics for a batched read tool. The only real gap is guidance on when to choose responseFormat=compact, which is left entirely to the schema.

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

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

Schema description coverage is 100%, so both userIds and responseFormat are already documented in the schema, including the enum semantics and the 100-item cap. The description's 'up to 100 ... numeric user ID' restates schema content and says nothing about responseFormat, so the baseline 3 applies.

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

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

States a specific verb and resource ('Fetch ... public user profiles ... by numeric user ID') plus a concrete scope cap of 100 per call. That distinguishes it clearly from the single-record sibling tweetapi_user_by_id and from the username-based 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?

Explicitly routes username-based lookups to tweetapi_user_by_usernames, which is the most likely confusion point in a family with ~45 user tools. It stops short of saying when not to use it or contrasting with the singular tweetapi_user_by_id, so it is strong rather than exhaustive 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 readOnly, idempotent, openWorld and non-destructive, so safety is covered; the description adds genuinely new operational facts — an API key is required, each call is one TweetAPI request costing roughly 1 unit, and the result carries a cost estimate. It stops short of describing failure modes or rate limiting, so it is strong but not exhaustive.

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 purpose before the alternative and cost details, with no filler. The only redundancy is "Read-only," which merely restates readOnlyHint from the annotations.

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

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

For a two-parameter read tool with full schema coverage, an output schema, and rich annotations, the description covers purpose, the sibling alternative, auth, and cost. Nothing an agent needs in order to call it correctly is missing.

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

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

Schema coverage is 100%, so both parameters are already documented, including the username formats and the full/compact enum behavior with fieldsOmitted. The description only restates the identifier forms and adds no syntax or constraint detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ("Fetch one public user profile") plus the accepted identifier forms, and explicitly names the sibling tweetapi_user_by_usernames as the many-users variant. An agent can distinguish this from user_by_id, user_by_ids and user_by_usernames from the description alone.

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

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

Gives a concrete routing rule: use this tool for a single user, switch to tweetapi_user_by_usernames for several at once. That is an explicit alternative with the condition that selects it, which is the strongest form of guidance short of listing exclusions.

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

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

Annotations already declare read-only, idempotent, non-destructive, open-world, and the description adds real operational context beyond them: API key requirement, one request per call, roughly 1 unit of cost with a per-result cost estimate, and the fact that unresolved accounts surface in completeness.notReturned rather than erroring. That is exactly the added-value layer annotations cannot express.

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

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

Four tight sentences in a single paragraph: capability and limit first, failure behavior second, sibling routing third, cost/auth last. No filler and nothing buried.

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 annotations, a fully described input schema, and an output schema, the remaining unknowns for an agent are cost, auth, partial-failure behavior, and batching limits — all of which the description covers. Nothing needed to call it correctly is missing.

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

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

Schema description coverage is 100%, so both parameters are already documented; the description's mention of usernames/@handles/profile links and the 100-item cap largely restates the schema. responseFormat is left entirely to the schema, so no extra semantic value is contributed here.

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

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

States a specific verb and resource ('Fetch up to 100 public user profiles') plus the accepted identifier forms (username, @handle, profile link). It also names the sibling to use instead for numeric IDs, so an agent can distinguish it from the many other user tools without opening a schema.

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

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

Gives an explicit alternative rule ('Use tweetapi_user_by_ids when you have numeric IDs') and a hard batching limit of 100. It does not address when to prefer the singular tweetapi_user_by_username sibling, which is the closest neighbor in the catalog, so the routing guidance is strong but not exhaustive.

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

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

Annotations already declare readOnly, idempotent, non-destructive and open-world, and the description corroborates rather than repeats them by adding operational facts the annotations cannot carry: an API key is required, it makes one request per call at roughly 1 unit cost, and the response includes a cost estimate. Only the exact failure behavior (e.g. what happens for a nonexistent or protected account) is left unstated.

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-loaded with the core action and output semantics, then the username fallback, then the cost/auth note. Every sentence adds distinct information with no restatement of the name or title.

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

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

An output schema exists so return values need not be detailed, yet the description still describes both result fields and their direction. Combined with the auth, cost, and prerequisite guidance, an agent has everything needed to invoke this two-parameter 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% and the schema already describes subjectId as the potential follower and targetId as the potentially followed account. The description reinforces the ordering semantics ('the first follows the second', 'the second follows back'), which removes any lingering ambiguity about which returned field maps to which argument.

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

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

States a specific verb and resource ('Check the follow relationship between two accounts by numeric user ID') and additionally defines both output fields, following and followedBy, so the direction of the relationship is unambiguous. This clearly distinguishes it from siblings like tweetapi_user_followers_ids or tweetapi_user_following_list, which enumerate relationships rather than test a single pair.

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

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

Gives an explicit routing rule: 'Use tweetapi_user_by_username first if you only have usernames,' which covers the most likely precondition failure. It stops short of excluding alternatives such as the followers/following list tools for bulk checks, so it falls short of a full when/when-not statement.

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 'Read-only' claim is consistent with readOnlyHint=true and destructiveHint=false, so no contradiction. Beyond the annotations it adds real context: API key required, one request per call, roughly 1 unit of cost with a cost estimate in each result, and a page-by-page continuation model. That is useful, but return-shape detail is largely delegated to the output schema.

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

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

Four short sentences with no filler: what it returns, why to pick it, cost/auth profile, and how to paginate. The payload constraint and the cheapness claim are front-loaded where an agent will read them first.

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

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

For a three-parameter paginated read with a full output schema, everything an agent needs is present: auth requirement, cost model, single-request semantics, and the next-page procedure. Return values correctly are not duplicated in prose because the output schema covers them.

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, and the description adds the paging contract by tying the input cursor to this result's completeness.nextCursor, making the loop explicit. It says nothing about the count ceiling or the username-lookup prerequisite, both of which live only 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?

States a concrete verb and resource (fetch follower user IDs for a user ID) and immediately delimits the payload as 'strings only, no profiles', which separates it from the profile-returning followers siblings. It does not name any sibling tool explicitly, so the differentiation is inferential rather than stated.

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?

'Cheapest way to walk a large follower graph' gives a clear selection criterion and the pagination instruction explains the continuation loop. It stops short of an explicit exclusion such as 'use tweetapi_user_followers_list when you need profiles', leaving the agent to infer the alternative from what is absent.

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

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

Annotations already declare read-only/idempotent, and the description adds genuinely new behavioral context: API key requirement, one TweetAPI request per call, ~1 unit cost with a per-result cost estimate, and pagination via completeness.nextCursor. This is exactly the extra context annotations cannot carry.

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

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

Four short sentences, each front-loaded with the core action first, then the alternative, then cost/auth, then pagination. No filler and nothing buried.

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?

An output schema exists, so return shape is not the description's burden; with pagination, cost, and auth covered, an agent has everything needed to call this correctly on the first try.

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 count, cursor, userId, and responseFormat are all documented in the schema itself. The description reinforces count as page size and explains the cursor loop, but adds no format or constraint detail beyond what the schema already provides.

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

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

States a specific verb and resource with scope: 'Fetch one page of follower profiles for a user ID.' It explicitly contrasts with tweetapi_user_followers_ids, though it does not differentiate from other follower-listing siblings such as tweetapi_user_followers_v2 or tweetapi_list_followers, leaving a small ambiguity.

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

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

Names the alternative (followers_ids) and its selection condition ('when you only need IDs'), and the schema further routes username-holders to user_by_username first. There is no guidance on when to prefer the v2 or list_followers variants, but the primary use case 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 cover the safety profile (readOnly, idempotent, non-destructive), so the description earns credit for adding what they cannot: API-key requirement, one request per call, ~1 unit cost with a per-result cost estimate, and the cursor-based pagination contract via completeness.nextCursor. Minor redundancy in restating "Read-only," which the annotations already declare.

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

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

Front-loaded with purpose, then alternatives, then cost/behavior, then pagination — a logical progression with almost no filler. Slightly dense in the cost sentence and the redundant "Read-only" clause keep it from a 5.

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

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

For a 3-parameter read tool with a full output schema and complete annotation coverage, everything an agent needs to call it correctly is present: identity input constraint, pagination loop, cost expectation, and sibling routing. Return-value detail is correctly deferred to the output schema.