AIsa Social

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

Adds substantial context beyond the readOnlyHint/openWorldHint/destructiveHint annotations: the call is free, it requires the Authorization header, and it discloses result semantics ('ok is true only when the balance was read; otherwise each entry of errors says what to do in next_step'). That tells an agent how to interpret partial failure, which 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?

Three sentences, front-loaded with what the agent gets, followed by cost/auth, then call triggers, then result interpretation. No sentence is redundant and none could be dropped without losing 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 read tool with an output schema already present, the description covers the remaining gaps: cost, auth requirement, invocation triggers, and the ok/errors/next_step contract. Nothing an agent needs to call or interpret 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?

The tool takes zero parameters, so the description has nothing parameter-level to compensate for, and the schema is fully covered. A 4 rather than 5 reflects that it adds no input-syntax detail, though none is possible here.

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

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

The description states a concrete resource set (identity/key, account balance, Go-to-Market wallet, usage over 1/7/30 days) rather than restating the name. It is clearly distinguishable from every sibling, which are all Reddit, batch, or search tools. An agent knows exactly what it will learn by calling it.

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 triggering conditions are given: 'Call it to verify a new connection or to explain a 402.' That is a strong when-to-use statement. It stops short of 5 because it names no alternative tool or a when-not condition, though the sibling list offers no obvious competing diagnostic.

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, closed-world), so the description is not required to restate it. It adds genuine operational context: the batch_use prohibition, exact-name/prefix requirements, and session reuse semantics. It does not cover failure handling when names are invalid, 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?

Front-loaded with the core action and size limit, and every sentence carries workflow value. The session_id sentence duplicates the schema's own parameter description, which is minor redundancy rather than bloat.

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

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

For a read-only batch retrieval tool with an output schema, the description supplies the orchestration context an agent needs (source of names, next steps, session handling) without needing to explain return values. Nothing essential to correct invocation is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds real meaning beyond the schema by constraining names to those returned by search and warning against a client prefix such as mcp__aisa__, which is not encoded 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 specific verb and resource ('Retrieve schemas for 1 to 20 exact tool names') and pins the source of those names to search. This clearly separates it from siblings like search (finds tools), batch_quote, and batch_use.

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 sequences the workflow: build arguments from successful schemas, then call batch_quote, and 'Do not call batch_use yet.' This is an explicit when-to-use and when-not-to-use instruction naming the alternative siblings.

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

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

Goes well past the readOnly/idempotent annotations by explaining that quotes are price observations rather than authorization grants, and precisely delimiting what auto_execute_eligible does and does not waive (user prohibition, narrower scope, tighter budget). It also guarantees no execution fallback, which is the key behavioral risk for this 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?

Purpose is front-loaded and most sentences carry distinct rules (no fallback, eligibility limits, naming, session reuse). It is on the long side and the argument-shape constraint is stated twice in spirit, but little is truly wasted.

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

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

An output schema exists, so return-value documentation isn't required, yet the description still flags the two response fields that matter for a downstream decision. Combined with session and naming guidance, an agent has everything needed 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?

At 67% schema coverage the schema already documents each parameter, so the description earns credit only for added meaning: exact-name rules for 'tool', session_id reuse semantics, and the 1-to-20 argument-shape parallel with batch_use. It doesn't clarify search_id beyond what the schema states.

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

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

States a specific verb and resource ('Obtain AIsaServices cost quotes for 1 to 20 published tools') plus the crucial scope qualifier 'without executing them.' It is immediately distinguishable from the sibling batch_use, which executes rather than quotes.

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

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

Explicitly names the parallel sibling ('Same input as batch_use') and draws the boundary ('Never falls back to execution'). It also gives operational conditions: use names exactly as search returns them, strip any mcp__aisa__ prefix, and reuse session_id from Search for the task.

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 mutability, destructiveness, and open-world behavior. The description adds critical business logic: billable calls, quote dependency, the meaning of auto_execute_eligible (waives only cost confirmation, not user prohibitions), and no silent retry. It doesn't detail rate limits or return format, but with an output schema present, that's acceptable.

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

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

The description is dense and front-loads the cost warning, but it packs many separate instructions into one block, making it less scannable. Some sentences like 'A missing or failed quote is not free' add value, but the overall flow could be better structured.

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

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

Given the destructive, open-world annotations and the presence of an output schema, the description covers the essential preconditions and behavioral constraints. It could mention error handling or partial failure behavior, but the core guidance is sufficient for correct invocation.

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

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

Schema coverage is 67%, and the description adds important semantics: tool names must be exact without client prefix, session_id reuse guidance, and 1-20 call limit. It doesn't explain search_id, but the schema description for search_id is already clear enough.

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

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

The description clearly states the verb and resource: 'Execute 1 to 20 independent published-tool calls', and the title matches. It distinguishes itself from batch_quote by requiring a quote first, but doesn't explicitly contrast with the singular 'use' sibling, though that's implied by 'batch'.

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

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

The description gives explicit when-to-use and when-not-to-use conditions: only after a successful batch_quote with auto_execute_eligible=true or explicit user authorization. It also states re-quote conditions and prohibits silent retries, leaving little 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 covered. The description adds genuinely new behavioral context — the ~4 KB footprint versus 380 KB, the flat/already-normalised shape, and the injected billing estimate. It doesn't discuss rate limiting or the credit-free cached path, which the schema covers but the description does not reinforce.

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 and size comparison, then the selection rule, then id sourcing — a sensible order with little filler. It runs long and the HTML-comment pricing block is noise, but that block appears to be machine-injected boilerplate rather than authorial padding.

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, and the schema itself carries the cache_max_age semantics. Given that, the description covers everything an agent needs: what it returns, how big it is, when to prefer it, and where the id comes from.

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 schema already documents cache_max_age and its enums. The description still adds value beyond the schema by specifying the id is 'numeric' and by telling the agent where to obtain it (data.user.id, id from search, post owner).

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 ('Returns a compact public profile for a numeric Instagram user id'), quantifies the payload (~4 KB vs 380 KB), and explicitly separates itself from the sibling get_instagram_profile. It also names a second sibling (get_instagram_search_profiles) as an id source, so an agent can route 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 decision rule: 'Prefer this endpoint whenever the id is in hand' and 'Use get_instagram_profile only when a handle is all that is available.' It even enumerates the three places the required id can be sourced from, so the prerequisites are fully closed.

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), and the description adds behavioral facts the annotations cannot convey: the 400 error on photo posts, the ~13 second latency as the slowest call in the API, and the ~1 KB payload size. These are exactly the beyond-annotation details that change an agent's calling strategy.

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

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

Front-loads purpose, then constraints, then alternative routing, in four tight sentences. The appended pricing comment block is boilerplate rather than task-relevant guidance, which slightly dilutes an otherwise waste-free entry.

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 names the return shape (id, shortcode, transcribed text), and it covers the operational envelope: duration cap, error behavior on photo posts, latency, and payload size. 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 description coverage is 100%, and the two non-trivial parameters (cache_max_age, allow_long_transcription) carry extensive inline documentation including enum values, billing semantics and the 'true'-only opt-in rule. The description adds no parameter-level detail beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb (transcribes the speech) and resource (public Instagram video or reel), and explicitly distinguishes itself from get_instagram_post by contrasting spoken words with the author's caption. An agent can separate this from the transcript-adjacent 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?

Gives a hard precondition (video under two minutes), the failure mode when violated (photo post returns 400 bad_request), the diagnostic step when URL type is unknown (check is_video with get_instagram_post first), and names an alternative tool for a different need (caption via edge_media_to_caption). When-to-use and when-to-use-something-else are both explicit.

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

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

Annotations already cover the read-only/idempotent/non-destructive profile, but the description goes further by disclosing response payload location (data.xdt_shortcode_media), approximate response size (~197 KB), and the side effect plus credit cost of download_media (mirrors media to permanent storage, 10 credits vs 1). It does not discuss rate limits or auth requirements, but the added operational cost/size context is genuinely useful beyond the annotations.

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

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

Purpose and routing are front-loaded, and every sentence carries operational information. However, the long enumeration of output fields in the first sentence is largely redundant given the tool has an output schema, making it denser than necessary.

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 structure, and it still supplies size, cost, caching-adjacent trade-offs, and sibling routing. An agent has everything needed to decide whether to call this tool and how to configure 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 description coverage is 100%, so all six parameters (including cache_max_age semantics and download_media cost) are already documented in the schema. The description reinforces the download_media cost/default trade-off but adds no syntax or behavior that the schema does not already carry, 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 opening sentence gives a specific verb (returns), resource (full metadata for one public post or reel), and identity mechanism (by URL). It is immediately distinguishable from siblings like get_instagram_post_comments and get_instagram_media_transcript, which the description itself 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 routing rules are provided: call get_instagram_post_comments for the comment thread and get_instagram_media_transcript for spoken words in a video. It also gives a clear when-not for a costly parameter ('leave it off unless the files are needed'), so the agent knows both alternatives and cost trade-offs.

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, yet the description adds substantial extra context: the normalised response shape, approximate ~10 KB payload size, cursor paging, and the key constraint that only top-level comments are returned while child_comment_count merely reports reply counts. This is behavioural detail far beyond the annotations.

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

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

Front-loaded with purpose and shape, and each sentence carries information (shape, size, pagination, reply limitation). The pricing boilerplate and the 'one of the few small responses' remark are the only mild padding.

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 plus an output schema present, the core safety and return-shape burdens are covered, and the description still enriches them. It is slightly incomplete/inconsistent regarding how include_replies reconciles with the claim that replies cannot be expanded.

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 schema already documents url, cursor and include_replies, and the description adds little parameter-specific meaning. There is a mild tension: the description says replies 'are not included, and there is no endpoint that expands them,' while the schema exposes include_replies to fetch replies, which could confuse an agent about whether replies are retrievable.

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 ('Returns the comments on a public post or reel by URL'), and names the sibling it is not for post-level data ('call get_instagram_post'). An agent can distinguish this from the sibling 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?

Explicitly routes the agent to get_instagram_post when the post's caption/view counts/video URL is wanted, giving a clear alternative selection rule. However it gives no guidance on when to prefer this over get_instagram_user_posts or the digest tools for broader comment needs.

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, openWorld, non-destructive), yet the description adds substantive behavior: an approximate payload size (~380 KB), the counterintuitive finding that trim saves under 1% and shouldn't be relied on, and the exact response paths where counts and posts live. This is meaningful context an agent cannot get from the 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?

The core content is front-loaded and every sentence carries information: response shape, size, trim caveat, and the cheaper alternative. The trailing pricing boilerplate adds length but is a platform-injected block rather than author prose, so it only marginally detracts.

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-value documentation is not strictly required, yet the description still maps the key fields to their JSON paths. Combined with the size estimate, trim caveat, and alternative-tool routing, an agent has everything needed to call this correctly and predict the response.

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

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

Schema description coverage is 100%, so the baseline is 3. The description goes beyond the schema by disclosing that the trim parameter is effectively useless for shrinking the payload — information that directly contradicts the optimistic schema text 'Set to true to get a trimmed response' — and by naming where the handle's data surfaces. cache_max_age is left entirely to the schema, which documents it well.

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 ('Returns the full public profile for an Instagram handle') and identifies the upstream source. It explicitly distinguishes itself from the sibling get_instagram_basic_profile, so an agent can route correctly 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?

Provides an explicit alternative with its selecting condition: 'When the numeric id is already known, get_instagram_basic_profile returns the same headline numbers in about 4 KB.' It also warns that trim=true is not a viable way to reduce payload. It does not address other profile-adjacent siblings (instagram_profile_digest, get_instagram_user_posts), which keeps it 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?

Goes well beyond the annotations (readOnly/openWorld/idempotent) by disclosing coverage limits ('what Google has indexed publicly, not everything on Instagram'), measured payload size (~87 KB) and latency (~8s), and that all four engagement counts are populated. It does not cover auth requirements or pagination depth behavior, so it stops 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?

Dense but front-loaded: purpose and mechanism first, then caveats, then routing to siblings. The exhaustive enumeration of return fields partly duplicates the existing output schema and is the one sentence that does not fully earn its place.

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

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

Given a rich output schema and full annotations, the description fills the remaining gaps an agent needs: data-coverage caveat, latency/size expectations, and alternative tool routing. Only minor parameter-level detail (page/limit behavior) is left unexplained.

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 75%, so the baseline is already anchored at 3. The description adds meaning by clarifying that date_posted 'narrows to a relative window' and by framing query as the keyword driver; page/limit still carry no description beyond their schema text.

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 (searches reels by keyword) and immediately distinguishes itself from siblings by naming the mechanism ('through Google rather than Instagram's login-gated search'). An agent can identify this tool's niche 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?

Explicitly routes to alternatives with their selecting conditions: get_instagram_search_hashtag for a specific hashtag, get_instagram_reels_trending for what is popular with no query. This is exactly the when/when-not/alternative guidance the dimension asks for.

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 cover the safety profile (readOnly, idempotent, openWorld), yet the description adds substantial behavior: batch pagination with overlapping successive batches requiring dedup on shortcode, measured payload size (~411 KB / 30 reels), and the caveat that play_count/ig_play_count come back null here unlike in get_instagram_reels_search. That is real, non-obvious operational context.

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

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

Front-loaded with what it returns, then pagination/dedup behavior, then routing to the sibling. Dense but every clause carries information; the embedded field enumeration and the injected pricing comment add bulk without adding invocation guidance.

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

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

For a no-parameter, output-schema-backed tool, everything an agent needs is present: scope, pagination/dedup requirement, known null fields, size expectations, and the correct alternative for filtered searches. Nothing material is missing.

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

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

Zero parameters, so the baseline is 4. The description reinforces this by stating it takes no parameters and cannot be filtered, which prevents an agent from inventing filter arguments, but there is no further parameter detail to add.

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 ('Returns the reels Instagram publishes on its public instagram.com/reels page') plus the normalized output shape. It explicitly distinguishes itself from get_instagram_reels_search and implicitly from get_instagram_user_reels by scope (public trending page vs topic search vs a user's reels).

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 operational guidance: 'call repeatedly and de-duplicate on shortcode' because batches overlap, plus 'Takes no parameters and cannot be filtered; to search by topic use get_instagram_reels_search.' Both the when and the when-not (with a named alternative) are stated.

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

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

Annotations already cover read-only, idempotent, open-world and non-destructive, yet the description adds non-obvious behavior: results are Google-indexed rather than direct Instagram data, the cursor is a Google results page number rather than an Instagram cursor, and payload size is about 78 KB for ten posts. The cursor quirk in particular is exactly the kind of detail that prevents misuse.

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?

Purpose, return shape, enum behavior, the cursor caveat and the alternative are all front-loaded with no filler. It is densely packed into a single block rather than cleanly segmented, and the injected pricing block adds bulk, but every sentence of the authored text earns its place.

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

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

With an output schema, full annotation coverage and 100% schema description coverage, the description already goes further by naming the normalized return fields and the size/cursor behavior. 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 description coverage is 100%, so the schema already documents hashtag, cursor, media_type and date_posted; the description mostly restates them (optional '#', all vs reels). It adds little parameter meaning beyond what the schema provides, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Finds public posts carrying a hashtag through Google') plus the exact scope of coverage. It names the sibling it is not (get_instagram_reels_search) and explains the shared normalized shape, so an agent can distinguish 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 clear routing guidance: media_type=reels vs all, and an explicit alternative ('To search caption keywords rather than a hashtag, use get_instagram_reels_search'). It stops short of stating exclusions or prerequisites (e.g., hashtag is not required), so it is strong context rather than a full when/when-not matrix.

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, openWorld, non-destructive), yet the description still adds meaningful traits: the source is Google (open-world scraping, not the Instagram API), the measured payload/latency (~18 KB, ~13 s), and the matched_from field that explains why a profile appeared. Rate limits and failure behavior are not covered, which keeps it short of a 5.

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

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

Purpose and routing are front-loaded and the performance metrics are compact, but the long enumeration of return fields is largely redundant with the existing output schema and consumes most of the description's length. It could be trimmed to keep only the fields that inform selection.

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 still supplies the source of the data, cost/latency expectation, sibling routing, and the chaining target for the returned id. Nothing an agent needs to invoke 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 description coverage is 100%, so both parameters are already documented, and the description adds no syntax or format detail beyond restating 'keyword or bio phrase'. The cursor/pagination parameter is not addressed at all. Baseline 3 is appropriate when the schema does the heavy lifting.

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 ('Searches Google for public Instagram profiles matching a keyword or bio phrase') and enumerates the returned identity fields, so the agent knows exactly what it gets back. It also distinguishes itself from siblings by naming the post-search alternatives, so an agent can pick 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?

Gives an explicit exclusion ('To search posts rather than people, use get_instagram_search_hashtag or get_instagram_reels_search') and a downstream chaining rule ('The numeric id feeds get_instagram_basic_profile directly'). Both when-to-use and when-not-to-use are stated rather than inferred.

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, openWorld), and the description adds real behavior beyond them: raw Instagram media objects under a 'reels' key, cursor/has_more paging, and a measured payload size (~177 KB for five reels). It also discloses that the response shape matches get_instagram_user_reels rather than the normalised search-endpoint shape, which is non-obvious and useful.

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

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

Front-loaded with the core purpose, then progressively more specific detail (shape, acquisition paths, size, alternative tool). It is dense but every content sentence carries information; the appended pricing block is boilerplate rather than authored prose.

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 doc-dumped, yet the description still orients the agent on response shape and paging. The one residual gap is that audio_id is technically optional in the schema but effectively the tool's subject, and the description never says what happens if it is omitted.

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 goes beyond the schema by explaining how audio_id is obtained and where it lives on other responses. Cursor semantics are only echoed from the schema rather than extended.

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+filter: 'Returns the reels that use one audio track.' It explicitly names the sibling it is not (get_instagram_reels_search for keyword-based discovery), so an agent can distinguish it 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?

Gives concrete selection guidance: use this when you have an audio_id, use get_instagram_reels_search when you want keyword search. It also supplies two confirmed acquisition paths for audio_id (the /reels/audio/<id>/ URL number and clips_metadata.original_sound_info.audio_asset_id), which removes the main prerequisite uncertainty.

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, openWorld, non-destructive), yet the description adds genuinely new traits: the ~206 KB payload size, the fact that it is nearly all inlined markup and styling, and that it contains zero structured profile data. These are the details that change how an agent handles the result.

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

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

The author-written text is tight and front-loaded: purpose first, then handling advice, then the alternative tools. The injected pricing banner adds length the author does not control, which keeps this just short of 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?

An output schema exists, so return values need not be explained, and the description goes further by characterizing the payload's size and composition. For a single-parameter read tool with full annotation coverage, nothing an agent needs 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% for the single 'handle' parameter, so the schema already carries the semantics. The description mentions the handle only in passing and adds no format or validation 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 ('Returns Instagram's official profile embed widget for a handle as a single html string') and immediately distinguishes itself from data-returning siblings by noting it carries no structured profile data. An agent can identify the tool's output shape 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?

Explicitly routes the agent to alternatives: get_instagram_basic_profile when the numeric id is known, get_instagram_profile when only the handle is. It also gives a usage posture ('treat the result as something to store or render rather than something to read'), which is exactly the when/when-not guidance needed.

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 readOnly/idempotent/non-destructive, but the description adds real behavioral context: the response echoes the id in prefixed form, the 404 misattribution gotcha, and measured payload size (~630 KB for 38 stories) that scales with the album. This is exactly the kind of beyond-annotations disclosure that earns a top score.

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 the parameter gotcha, then the failure mode, then the size note. Every sentence carries actionable information; nothing is padding despite the density.

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 values need no elaboration, yet the description still names key fields. Combined with the ID-format warning and size scaling, an agent has everything needed 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%, yet the description adds the critical semantics the schema omits: the id must be the bare numeric form from get_instagram_user_highlights, and the prefixed highlight:<id> form yields a 404 whose message misleadingly blames deletion or a private account. This is meaningful parameter meaning beyond the schema.

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

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

States a specific verb and resource ('Returns the stories inside one highlight album') and enumerates the returned fields, which cleanly separates it from the sibling list-level get_instagram_user_highlights. An agent can tell exactly what this tool does versus its 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?

It explicitly routes the agent to get_instagram_user_highlights as the source of valid IDs and implies this tool is the per-album follow-up. It does not state explicit exclusions or when not to use it, but the upstream/downstream relationship 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, so the safety profile is covered. The description adds genuinely non-structured context: approximate payload size (~6 KB), the fields returned, the chaining prerequisite for the detail tool, and a latency tradeoff between handle and user_id. It stops short of rate-limit or failure-mode detail.

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 what it returns, then the routing rationale, then the parameter tip — a sensible order with no filler. The speed/parameter sentence duplicates the schema text rather than earning new space, and the embedded pricing block sits awkwardly in the middle of the tool description.

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

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

With an output schema present, the definition need not enumerate returns, yet it does so concisely alongside cost and chaining guidance. Nothing critical is missing for a two-optional-parameter read tool; only explicit pagination or empty-result behavior 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 description coverage is 100% and both properties already document themselves, including the 'use user_id for faster response times' hint, which the description largely repeats. The description confirms both params are optional by omission but adds no new syntax, format, or mutual-exclusion guidance 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 ('Lists the story highlight albums on a public profile') and immediately differentiates from sibling get_instagram_user_highlight_detail by declaring itself 'the only source of a highlight id.' An agent can pick between the two 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?

Gives explicit usage context ('a cheap way to see whether an account keeps highlights at all') and the routing condition to the sibling tool, noting the detail tool 'requires the bare numeric id exactly as returned here.' It also tells the agent which parameter to prefer and why, which is more than most definitions offer.

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, openWorld), yet the description adds substantial context beyond them: measured payload size (632 KB), the limited effect of trim (only down to 523 KB), pagination loop mechanics, and the fields present in each item. This is exactly the value-add the dimension rewards.

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 pagination, payload realities, and alternatives in a logical order; nearly every sentence earns its place. Slightly dense, and the appended pricing boilerplate is external noise not attributable to the tool author.

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

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

Despite an output schema existing, the description still conveys return shape and size, pagination termination, and sibling routing. For a large-payload, paginated list tool, an agent has everything needed 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 baseline is 3, but the description adds real meaning: it clarifies that next_max_id is a cursor for paging and that trim=true barely reduces the already-large payload, tempering a user's expectation. It does not document the handle parameter's format, keeping it from a 5.

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 scope ('Returns one page of a public account's timeline, reels and photos and carousels alike') and explicitly distinguishes itself from get_instagram_user_reels and get_instagram_post. An agent can identify the tool's role 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?

States the selection rule explicitly: use get_instagram_user_reels for reels alone and get_instagram_post for one known post. It also pre-empts a common wrong assumption by noting neither alternative yields a smaller payload.

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, openWorld, non-destructive), yet the description adds behavior beyond them: one-page-at-a-time pagination via max_id, an expected payload size of 594 KB per page for context budgeting, and the exact fields returned per reel. That is real operational context not derivable 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?

Return shape and pagination are front-loaded, and the alternative-tool routing sits at the end where it belongs. The sentences are dense but each carries distinct information; the appended pricing boilerplate is noise but outside the author's prose.

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, yet it still sketches the envelope and cross-references a sibling tool's input contract. Combined with annotations and 100% schema coverage, 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 description coverage is 100%, so the schema already documents handle, user_id, max_id, and trim, and the description largely restates the user_id-vs-handle preference and max_id chaining. The trim parameter is not addressed at all in the description. Baseline 3 is appropriate given the schema does the heavy lifting.

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

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

The description states a specific verb and resource ('Returns one page of a public account's reels'), names the response envelope (items[].media) and the pagination token (paging_info.max_id), and explicitly contrasts itself with get_instagram_user_posts for the full timeline. An agent can distinguish it from get_instagram_song_reels, get_instagram_user_posts, and reels_search 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?

It names two concrete alternatives with selecting conditions: get_instagram_song_reels is invoked by piping clips_metadata.original_sound_info.audio_asset_id, and get_instagram_user_posts covers the whole timeline including photos and carousels. It also advises user_id over handle for speed, giving the agent actionable routing rather than 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/openWorld/idempotent/non-destructive, so the safety profile is covered elsewhere. The description adds substantial behavioral context beyond that: pagination via cursor, concrete payload sizes (104 KB for 16 pins; 28 KB trimmed) and the exact field subsets returned. It stops short of stating rate limits or error behavior, so a 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?

Front-loaded with the core action and paging behavior, and every sentence carries information. The two inline field enumerations ('node_id, link, domain...' and the trim field list) are dense and slightly bloat the text, and the injected pricing boilerplate sits outside the definition's control.

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 already exists, so return values need no further explanation, and annotations cover the read-only/idempotent profile. Between the URL-source guidance, paging semantics and field-set/size notes, 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 coverage is 100%, so the baseline is 3, but the description adds real meaning: url must be absolute, with relative board paths needing an https://www.pinterest.com prefix, and trim=true is quantified as cutting 104 KB to 28 KB while enumerating the retained fields. This goes well beyond the schema's one-line parameter docs.

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 — 'returns one page of pins from a board URL' — and immediately differentiates from siblings by noting it also emits a paging cursor and that board pins use a distinct field subset from search results and pin detail. An agent can distinguish it from get_pinterest_search and get_pinterest_user_boards 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 the agent: 'For a user's board list rather than one board's pins, use get_pinterest_user_boards,' and explains where valid URLs originate (board.url on search results, or get_pinterest_user_boards). Both when-to-use and the alternative are named.

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 cover the safety profile (readOnly, idempotent, non-destructive), and the description goes well beyond them: response size (12.5 KB), what trim actually changes (drops richMetadata and category, keeps a named field set), how shortcode URLs fail with 404, and the caching behavior's cost implications. This is unusually rich disclosure for a read 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?

Front-loaded with purpose, then alternatives, then output-shape detail — a sensible ordering. It is dense and the long field enumeration plus the embedded pricing note add bulk, but nearly every sentence carries decision-relevant information, so it stays efficient rather than 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?

An output schema exists, so return values need not be described, yet the description still quantifies size and the trim trade-off that the schema cannot express. Combined with the 404 and URL-format warnings, 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%, so the baseline is 3, but the description adds real meaning: the exact URL shape pinterest.com/pin/<id> and a precise account of what trim trades away, which is more than the schema's vague 'trimmed down version'. cache_max_age semantics remain schema-only, keeping this just short of a 5.

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 (fetches) and resource (one pin) scoped by URL form, and explicitly distinguishes itself from get_pinterest_search and get_pinterest_board. An agent can route between the three pin/board/search tools without opening any schema.

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

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

Gives explicit alternatives and the condition selecting each: 'To find pins by keyword use get_pinterest_search; to page through the board a pin sits on use get_pinterest_board.' It also adds a pre-call check (ensure a numeric trailing id) and a caveat to expect occasional 404s, which is actionable when-to-use guidance.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, openWorldHint, destructiveHint=false), so the description is not obligated to restate that. It adds genuinely useful behavioral facts instead: measured payload size (~110 KB for 17 pins), the trimmed 28 KB size, and exactly which six fields survive trim. It stops short of documenting rate limits or cursor expiry.

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 return shape, then the size/trim tradeoff, then routing — a sensible priority order with no padding in the sentences themselves. The embedded pricing comment block is boilerplate noise that dilutes an otherwise tight entry.

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 the exhaustive per-pin field listing (images in five sizes, board, pinner sub-fields) is partly redundant with what the schema already exposes. The non-redundant parts — payload size, trim economics, and cross-tool field handoffs — are exactly what the agent needs before calling, making the description sufficient overall.

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 75% and the schema barely describes trim ("trimmed down version") and not at all limit. The description compensates by quantifying the trim tradeoff and enumerating the dropped fields (title, link, board, domain), which is meaning the schema does not carry. limit and cursor remain unelaborated.

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 (searches Pinterest for pins by keyword) plus the return shape (pins plus a pagination cursor). It also explicitly distinguishes itself from the two closest siblings, get_pinterest_board and get_pinterest_pin, and from other platform search tools in the list.

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

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

Gives a concrete when-to-use rule for trim ("only skip trim when you need those") and routes follow-up work to get_pinterest_board and get_pinterest_pin with the exact field that feeds each. It does not, however, state when a caller should prefer this over other search tools (e.g., get_reddit_search), so the routing is sibling-aware but not exhaustive.

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

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

Annotations already cover read-only/idempotent/non-destructive, so the bar is lower, yet the description adds real behavioral detail: response payload size (59 KB for 10 boards), the trim ratio and exactly which fields survive trimming. This is the kind of operational context an agent needs to avoid oversized responses.

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 output fields, then the trim tradeoff, then routing. Dense but nearly every sentence earns its place; the trailing pricing boilerplate is injected and slightly dilutes the structure.

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?

Pagination (cursor), input format, response shape, payload-size tradeoff, and sibling routing are all covered. With an output schema present, return values need not be explained, and the extra field listing is a bonus rather than a gap.

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

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

Schema coverage is 100% so baseline is 3, but the description goes beyond the schema's terse 'trimmed down version' by naming the exact fields trim keeps, and reinforces that handle is a bare username rather than a profile URL.

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+resource+scope: 'Lists a user's public boards by username, with a cursor to page.' It also names the sibling tools it is not (get_pinterest_board for pins, get_pinterest_search for cross-Pinterest search), so an agent can route correctly without opening another 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 to alternatives with conditions: feed each board's url to get_pinterest_board for pins, use get_pinterest_search for Pinterest-wide search. It also clarifies the expected handle input format. There are no explicit when-not-to-use statements, but the alternative routing 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, openWorld), and the description adds genuinely new behavioral detail: the paging shape differs from both sibling search tools (more.has_more/more.cursor vs after vs cursor), and the payload cost is quantified ('about 21 KB for 19 top-level comments'). That size estimate and paging divergence are exactly the traits an agent cannot get 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?

The core content is a single run-on sentence that enumerates every post and comment field even though an output schema already exists, which is redundant rather than informative. Routing guidance that an agent most needs is buried at the end, and the appended pricing boilerplate further dilutes it.

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?

Because an output schema exists, the field enumeration is unnecessary and the description would be complete without it; what remains (routing from search tools, paging semantics, response size) is the information an agent genuinely needs. It is slightly over-complete rather than under-complete.

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

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

Schema description coverage is 75%, so the baseline is already near 3. The description clarifies what cursor does ('more comments, or replies') and implies the url input, but it never explains trim or accounts for the undocumented 'trimmed' string parameter, so it adds only marginal meaning beyond the schema.

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

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

Opens with a specific verb and resource: 'Returns one post and its discussion from a post URL.' It also explicitly differentiates itself from the search siblings by positioning them as the discovery step, so an agent can distinguish this tool from get_reddit_search and get_reddit_subreddit without opening any schema.

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

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

Gives a clear entry condition: 'To find posts worth opening, start from get_reddit_search or get_reddit_subreddit,' and describes the cursor path for continued paging. It stops short of stating any when-not-to-use case, so it is clear context rather than 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 readOnly/openWorld/idempotent/destructive=false, so safety is covered. The description adds substantial non-annotation behavior: latency (8-16s, slowest endpoint), payload size (8-26 KB), pagination via an after token, and the full returned field list. It stops short of documenting rate limits or failure behavior, but adds real context beyond the annotations.

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

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

Front-loaded with the core action, then alternatives, then performance. The 19-field enumeration is verbose but informative for a search result. The pricing block is boilerplate appended by the platform rather than the author's prose, so it doesn't count against structure.

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 the field list is somewhat redundant, yet the description still supplies pagination, performance expectations, sorting semantics and routing to siblings. It omits auth/prerequisite notes and does not flag that 'query' is practically required despite required=[], a minor gap for a 10-param 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 60%, so the description must compensate for some gaps. It meaningfully enriches 'sort' (relevance, new, top, comment_count) and 'timeframe' (narrows the window) and explains 'after' for paging, but leaves limit, count, trim/trimmed, filter and query semantics to the schema. Adequate but partial.

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

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

States a specific verb and resource ('Searches every public subreddit for posts matching a query') with scope ('every public subreddit') and names what it returns. It explicitly distinguishes itself from get_reddit_subreddit_search and get_reddit_post_comments, so an agent can tell them apart 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?

Names two alternatives with the exact conditions that select them: use get_reddit_subreddit_search 'to stay inside one community' and get_reddit_post_comments 'to read one post's discussion'. This is explicit when-to-use-each guidance rather than implied context.

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

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

Annotations already establish the read-only, idempotent, non-destructive profile, so the description is free to add runtime behavior instead. It does: the timeframe/sort=top 400 error (rather than silent ignoring), case-sensitive subreddit names, pagination via the after token, and a concrete ~18 KB / 24 posts size figure. Auth and rate-limit behavior are still unstated, so it falls 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?

Front-loaded with the core purpose and scope, then constraints, then routing. Every sentence carries information, including the size estimate and error edge case. The appended pricing boilerplate adds length without helping tool selection.

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 6-param, unpaginated-boundary tool with an output schema, this covers purpose, constraints, paging, alternatives and approximate payload size. Minor gaps remain: the trim payload reduction and cache_max_age are not clarified in narrative form. Nothing an agent needs to call it successfully 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 83%, so the schema already documents sort, timeframe, after and trim; the description largely restates the sort enum and the timeframe constraint. It adds the genuinely useful case-sensitivity note for subreddit, but leaves cache_max_age and the semantics of trim (what gets removed) unexplained. Baseline 3 is appropriate when the schema carries most of the load.

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

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

States a specific verb+resource and scope: the post stream of one subreddit. It explicitly distinguishes itself from the three nearest siblings (get_reddit_search, get_reddit_subreddit_search, get_reddit_subreddit_details), so 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?

Names the alternatives and the exact conditions that select them: use get_reddit_subreddit_search to search inside the same subreddit, get_reddit_subreddit_details for its metadata. It also states the sort=top pairing rule for timeframe, giving explicit when-to-use behavior rather than leaving it 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, openWorld and non-destructive, so the safety profile is covered. The description adds real behavioral context beyond that: approximate response size (~5 KB, smallest response here), the case-sensitivity gotcha, and the explicit scope exclusion (returns no posts). It doesn't discuss caching semantics, though the schema covers those.

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

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

Front-loaded with the core purpose and return fields, then usage, then the case-sensitivity caveat, then sibling routing. Every sentence carries information; the trailing billing block is platform metadata rather than authored prose.

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-value documentation is not required, and the annotations already carry the safety profile. The description nonetheless covers identity, scope, size, naming constraint, and sibling routing, which is everything an agent needs to select and invoke this 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 description coverage is 100%, so the baseline is 3. The description adds only the framing that the target can be given 'by name or by URL' (clarifying that the two params are alternatives) and restates the case-sensitivity rule already documented on the subreddit field. The cache_max_age enum is left to 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 ('returns metadata about one subreddit') and enumerates the exact fields returned, so the agent knows precisely what it gets. It also explicitly distinguishes itself from siblings by noting it returns no posts and naming get_reddit_subreddit and get_reddit_subreddit_search as alternatives.

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 when-to-use guidance ('size a community or read its rules before posting anything elsewhere') and explicit when-not-to-use routing ('It returns no posts at all: for those call get_reddit_subreddit, or get_reddit_subreddit_search'). Alternatives are named with the condition that selects them.

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 read-only, idempotent, open-world, non-destructive call, so the safety profile is covered. The description goes well beyond that with measured cost/latency (~5 KB, ~2 seconds), the pagination model (cursor token, contrasted with get_reddit_search's 'after'), and the empirical constraint that only posts are ever returned. That is exactly the kind of 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?

Purpose and scope are front-loaded, and the comparison sentences each carry distinct routing value. It is a dense single paragraph, and the enumeration of return fields duplicates what the output schema already provides, which is the one clearly removable element (ignoring the injected pricing boilerplate).

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 five-parameter, zero-required search tool with an output schema present, the description supplies everything needed to call it correctly: scope, pagination, alternatives, latency/cost expectations, and the sort caveat. Nothing important is deferred to inference.

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 earns an extra point by resolving a genuine ambiguity: the supplier enum advertises a 'comments' sort value that the description reports as never producing comments, which the schema alone would mislead an agent about. Cursor usage is also clarified in prose; subreddit name format and timeframe are left to 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 with explicit scope: 'Searches inside one subreddit and returns matching posts with a cursor token to page.' It immediately distinguishes itself from the sibling get_reddit_search by contrast (one subreddit vs all of Reddit, cursor vs after), so an agent can route 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?

Names two alternatives explicitly and the condition selecting each: get_reddit_search for site-wide search, and get_reddit_post_comments ('pass its url') for retrieving replies under a result. It also warns that the sort parameter should not be read as implying comment/media results, which preempts a likely misuse. This is close to a complete routing guide.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description still adds useful behavior: that it returns complete article text instead of the truncated tweet, where the payload lives (`article`), and a pricing note. The `article` key is semi-redundant given the output schema, keeping this from 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 that front-load the capability, then the usage condition and alternative. The pricing block is boilerplate metadata rather than prose bloat.

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 values need not be explained, and the description nonetheless notes the `article` key. Purpose, trigger, alternative, and cost are all present for a simple one-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?

Single parameter with 100% schema description coverage, so the schema already documents `tweet_id`. The description only restates "by its tweet ID" with no added format or edge-case 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 (Get) and resource (full body of an X Article / long-form post) keyed by tweet ID, and immediately distinguishes it from the ordinary-tweet tool. An agent can tell exactly what this returns 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 an explicit trigger ("when a tweet links to or is an Article and the 280-character preview is not enough") and names the alternative for the other case ("For ordinary tweets use `get_twitter_tweets`"). When-to-use and when-not-to-use are both covered.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and openWorld. The description adds where the payload lands ('Returns the object under community_info') and discloses the per-request cost, which the annotations do not cover. It stops short of noting rate limits or failure modes, 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?

Three tight sentences that lead with the purpose, then usage, then return shape; the pricing note is boilerplate appended after the substance and 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?

A read-only, single-parameter lookup with an output schema in place needs only purpose, routing, and return location — all present. Annotations carry the safety profile and the output schema covers the payload fields.

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

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

With 100% schema description coverage the baseline is 3, but the description adds format detail the schema lacks by specifying the ID is numeric, which helps an agent avoid passing a screen name or slug.

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 ('Get metadata for an X Community by its numeric community ID') and enumerates the returned fields (name, description, member count, access rules). It also names the sibling route for a different goal (discovery via get_twitter_community_tweets_all), so an agent can distinguish it from get_twitter_community_members, get_twitter_community_tweets, etc.

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

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

Explicitly says when to use it ('qualify a community before pulling its members or posts') and provides the alternative for the adjacent task ('to discover communities by topic, search their posts with get_twitter_community_tweets_all'). This routes the agent correctly without schema inspection.

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 genuinely useful behavioral context: cursor-based pagination and that full user objects are returned (the latter is partly redundant given 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?

The purpose is front-loaded in the first clause, and the alternative is deferred to the end where it belongs. The body is tight, though the injected pricing boilerplate is noise the definition author does not control.

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 annotations covering the safety profile, the description needn't explain return values or read-only status. It covers purpose, pagination, and the sibling alternative, leaving little an agent would need that isn't in structured fields.

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

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

Schema description coverage is 100%, so both parameters (community_id, cursor) are already documented. The description only echoes the pagination concept via 'cursor-paginated' and adds no syntax, format, or constraint detail beyond the schema, so baseline 3 applies.

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

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

The description states a specific verb and resource ('List the members of an X Community') and explicitly distinguishes itself from the moderator-listing sibling. An agent can identify this tool's scope 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?

It gives clear usage context ('map who participates in a topic-specific group') and names the specific alternative for moderators with the selecting condition. It stops short of stating when NOT to use it versus the many other community siblings (info, tweets), so it is clear 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 readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is fully covered structurally. The description adds only two behavioral facts beyond that: results are cursor-paginated and it 'Returns full user objects'. It says nothing about ordering, page size, or how a partial page should be interpreted, so the added context is modest.

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

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

The authored portion is three tight sentences with the core purpose front-loaded and the sibling routing at the end, so it reads well. It loses a point only because the injected pricing block roughly doubles the rendered length with billing boilerplate that competes with the substantive wording.

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

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

With an output schema present, the description is not obliged to explain the returned user objects, and it correctly avoids doing so. Purpose, scope, pagination, and the alternative tool are all covered; only secondary operational detail (page size, cursor exhaustion) is absent, which is minor for a read-only 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 both `community_id` and `cursor` are already documented in the schema; the baseline is 3. The description's 'cursor-paginated' phrase only restates the cursor parameter's function rather than adding format or usage detail (e.g. passing back the returned cursor).

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

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

States a specific verb and resource ('List the moderators of an X Community') plus a scope qualifier ('cursor-paginated'), and explicitly contrasts itself with the closest sibling, `get_twitter_community_members`. An agent can distinguish this from the members/info/tweets family without opening any schema.

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

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

Gives an explicit use case ('identify the people who set the agenda... highest-leverage contacts for outreach or partnership') and names the alternative for a different need ('For the full membership use `get_twitter_community_members`'). Nothing about tool selection is left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false. The description adds value beyond them by disclosing pagination behavior ('cursor-paginated'), the shape of the result ('full tweet objects with engagement counts'), and billing context, though it doesn't cover rate limits or result caps.

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 that are front-loaded with purpose, then usage, then return shape. The injected pricing block adds length but is boilerplate rather than authored content, so the core prose is efficient.

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

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

An output schema exists, so return values need not be detailed, and the description still gives a useful hint about the result shape. Annotations plus description fully equip an agent to invoke this tool correctly for its narrow, well-scoped purpose.

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 cursor and community_id are already documented in the schema. The description's mention of cursor pagination corroborates but does not add syntax, format, or ID-acquisition guidance beyond the schema, so baseline 3 applies.

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

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

States a specific verb (get) and resource (posts inside one specific X Community) with scope qualifiers (cursor-paginated). It explicitly names the sibling get_twitter_community_tweets_all as the alternative, so an agent can distinguish the two 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?

Gives the affirmative use case ('read what a known community is actually discussing') and the negative/alternative case ('If you do not know which community to look at, search across all of them with ..._all'), which routes the agent correctly between siblings.

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

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

Annotations already cover read-only, idempotent, open-world behavior, so the bar is lower. The description adds useful context—cursor pagination, sort options, and that full tweet objects are returned—though it omits billing implications beyond the appended pricing note and rate-limit behavior.

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

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

Front-loaded with the core action and scope, followed by a compact usage rationale and sibling routing. The appended pricing block adds tokens but is operational metadata rather than the description's own prose.

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 enough for a 3-param search tool with full schema coverage, annotations, and an output schema. It covers scope, sorting, pagination, and siblings; only deeper behavioral details like error modes or limits are 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%, so the schema documents query, cursor, and queryType. The description mentions sorting by Latest/Top and cursor-paginated results but adds no syntax, format, or filter semantics beyond what the schema already provides, so baseline 3 is appropriate.

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

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

States a specific verb (Search), resource (posts across all X Communities), and scope (by keyword, sorted, paginated). It explicitly distinguishes itself from the public-timeline sibling and names the narrower community tool.

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

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

Gives an explicit when-to-use rationale (topic-specific community discussion, higher signal density) and routes to siblings: get_twitter_community_tweets for a single community, get_twitter_community_info for metadata, and get_twitter_tweet_advanced_search for public timeline.

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, non-destructive, so the safety profile is covered. The description adds non-obvious operational context: page size of 20, cursor pagination, and the response key `followers`. It stops short of noting rate limits or whether the cursor is opaque, but the added value over annotations is real.

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 plus one routing sentence, all front-loaded: what it does, why to call it, and which sibling to use instead. No sentence is filler; the injected pricing comment is template noise rather than authored text.

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

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

An output schema exists, so return-value explanation is not strictly required, yet the description still points to the `followers` key, which helps. Combined with full schema coverage and rich annotations, an agent has everything needed to call it correctly; only minor operational details are 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 both parameters (`list_id`, `cursor`) are documented in the schema, so the baseline is 3. The description only alludes to cursor pagination generically and adds no format or ID-sourcing detail beyond what the schema already states.

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

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

Specific verb + resource ('List the accounts that subscribe to an X List') with pagination behavior stated up front. It explicitly distinguishes itself from the closest sibling by noting that `get_twitter_list_members` returns List members, not subscribers, so an agent can route 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?

Gives an explicit use case ('gauge how much attention a curated list attracts and who cares about that topic') and names the alternative tool for the adjacent-but-different case (members vs. subscribers). Both the when-to-use and the when-to-use-something-else are stated.

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

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

Annotations already declare readOnly/idempotent/openWorld and non-destructive, so safety is covered. The description adds real behavioral context beyond that: page size (20), cursor pagination, and the return key (`members`). It stops short of rate-limit guidance, but pricing is supplied inline, making this a solid above-baseline 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?

Front-loaded with the core action, followed by usage framing, return shape, then explicit sibling routing. Every sentence earns its place; the pricing block is metadata, not prose.

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 points to the `members` key. Combined with pagination and sibling routing, 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 description coverage is 100%, so both parameters are already documented and the baseline is 3. The description adds only that results are 'cursor-paginated, 20 per page', which lightly clarifies the cursor parameter's role but no format or ID-acquisition details 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 precise verb and resource ('List the accounts included in an X List') and immediately distinguishes itself from the two nearest siblings (list tweets vs. list followers). An agent can pick this 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?

Explicitly names alternatives with the conditions that select them: get_twitter_list_tweets_timeline for reading the members as a feed, and get_twitter_list_followers for subscribers. It also frames the use case (extracting a human-curated cohort), 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 cover the safety profile (readOnly, idempotent, openWorld, non-destructive), so the bar is lower. The description nonetheless adds real behavioral context: page size (up to 20), cursor pagination, and the return fields `has_next_page`/`next_cursor`. It doesn't mention rate limits or auth requirements, keeping it at a 4.

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, followed by use case and return-shape notes; each sentence is informative. The 'cheapest way to track a fixed cohort' phrasing leans slightly promotional and costs a bit of tightness.

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 values needn't be explained, yet the description still notes pagination fields. Pagination behavior, scope, and sibling routing are all covered, so an agent has everything needed 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 description coverage is 100%, so both parameters are already documented and the baseline is 3. The description reinforces `listId` and cursor-pagination semantics but adds no syntax or format detail beyond the schema.

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

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

States a specific verb (Get), resource (tweet timeline of an X List), and scoping parameter (`listId`), which cleanly distinguishes it from the many sibling timeline tools like get_twitter_user_tweet_timeline. An agent can identify the target 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 an explicit use case (monitor a hand-curated set of accounts as a single feed) and routes to a related sibling (get_twitter_list_members) for a distinct need. It lacks an explicit when-not or a direct comparison to the user-level timeline sibling, so it falls just 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, so the safety bar is pre-covered. The description adds useful context the annotations don't: the returned payload ('trend names and volumes under `trends`') and an account-specific pricing/usage note. It omits rate limits or freshness guarantees, but the additions are genuine.

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?

Purpose is front-loaded and the two core sentences are dense with no waste. The injected pricing block adds length that isn't part of the tool's intrinsic description, slightly diluting the otherwise tight structure.

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 rich output schema and full annotation coverage, the description supplies what the agent still needs: the location semantics, the returned field group, and the downstream search tool. It leaves only minor gaps like pagination/freshness, which the output schema may cover.

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 params are already documented; the description largely restates WOEID and the default `count` of 30 rather than adding syntax or format meaning. Baseline 3 applies when the schema carries the parameter burden.

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 ('Get the trending topics for a location') and pins the identifier (Yahoo WOEID), distinguishing it from the sibling tweet/user tools without ambiguity. It also names the natural next step tool, making its role in the workflow unmistakable.

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

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

It gives a clear scenario ('real-time read on what a specific market is talking about right now', 'timing content or spotting emerging stories') and routes the follow-up to `get_twitter_tweet_advanced_search`. However, it never states when NOT to use it or how it relates to other trend-adjacent siblings, so it stops short of full explicit routing.

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, openWorld, non-destructive), so the lower bar applies. The description still adds real behavior: cursor pagination semantics, the has_next_page/next_cursor return fields, sort modes, and supported query operators. It omits auth requirements and rate limits, which keeps it from 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?

Front-loaded with purpose, then operators, pagination, and alternatives in a tight sequence where each sentence carries information. The injected pricing boilerplate is not authored content but does add noise.

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 exhaustively explained, and annotations carry the safety profile. The description still covers usage context, alternatives, pagination flow, and query syntax, so 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 coverage is 50%, so the schema does part of the work. The description usefully explains the query-string operator syntax and the Latest/Top sort (mapping to queryType), but count, max_results, and start_time are undocumented in both places. It adds value over the schema without fully compensating for the coverage gap.

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 (search) and resource (X posts) and immediately differentiates itself by naming the two sibling alternatives for account search and user timelines. An agent can distinguish this from any account-scoped tool 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?

Explicitly declares when to use it ('primary entry point for X content research when you do not yet have tweet IDs or handles') and routes to the correct alternatives ('to search accounts use get_twitter_user_search', 'to read one account's posts use get_twitter_user_tweet_timeline'). Nothing is left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds real context beyond them: cursor-based pagination, and the shape of the payload ('full tweet objects with engagement counts'). It also carries a usage-based billing note with a per-request estimate, which is material for an agent deciding whether to call it. It does not mention rate limits or result caps.

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

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

Three tight sentences, front-loaded with the core definition before the routing advice. The injected pricing block is boilerplate rather than tool guidance, but it is short and clearly delimited, so it does not disrupt the structure.

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 usefully summarizes the payload. Purpose, alternatives, and pagination are all covered. The only shortfall is the undocumented sinceTime/untilTime pair, which an agent may need to bound a large quote set.

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 60%, and the description only reinforces the cursor parameter via 'cursor-paginated'. The two time-window parameters (sinceTime, untilTime) have no description in the schema and no explanation here, so half-documented inputs remain opaque. Baseline 3 is appropriate since the schema does much of the work but the description does not compensate for the gap.

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 ('Get quote tweets of a given tweet') and immediately defines the concept ('posts that embedded it with added commentary'), which is genuinely useful because 'quote tweet' is jargon. It explicitly distinguishes itself from get_twitter_tweet_replies_v2 and get_twitter_tweet_retweeters, so an agent can route without opening any schema.

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

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

Gives the when-to-use rationale ('to see how a post is being reframed or argued about, which is often more revealing than plain replies') and names both alternatives with the condition that selects each: direct replies -> get_twitter_tweet_replies_v2, silent amplification -> get_twitter_tweet_retweeters. Nothing is left to inference.

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

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

Annotations already declare readOnly, idempotent, non-destructive, open-world, so the safety profile is covered. The description adds real behavioral value beyond that: pagination behavior, the ordering limitation of the v1 endpoint, and the shape of returned objects. It stops short of describing rate limits or response envelope details, but is solid given annotation coverage.

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

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

The core definition is three tight, front-loaded sentences that each carry routing or behavioral information. The appended pricing boilerplate is machine-generated and not part of the semantic definition, slightly diluting conciseness but not the author's fault.

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-value structure need not be spelled out, and annotations carry the safety profile. Combined with the sibling routing and pagination notes, an agent has everything needed to invoke this correctly. Complete for a read-only list 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 description coverage is 100%, so the schema already documents cursor, tweetId, and the queryType enum with its default. The description reinforces the cursor pagination and default-order behavior but adds no syntax or format detail beyond the schema. Note a mild tension: the schema exposes an ordering enum while the description says this v1 endpoint returns default order only.

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 ('Get the direct replies to a tweet') and immediately scopes the shape of the result (cursor-paginated, full tweet objects). It explicitly distinguishes itself from two named siblings, get_twitter_tweet_replies_v2 and get_twitter_tweet_thread_context, so an agent can route correctly 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 use context ('read the discussion under a post — sentiment, corrections, or follow-up questions') plus two exclusion routes: use v2 for ordering control, use thread_context to walk upward to the root. This is a full when/when-not/alternatives treatment.

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 the safety profile (readOnly, idempotent, non-destructive), so the bar is lower. The description still adds useful behavior: page size (20 per page), cursor pagination, the Relevance default, and a usage-based billing note. It stops short of disclosing rate limits or quota behavior, but covers more than the annotations do.

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

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

The tool-relevant content is two tight, front-loaded sentences with zero waste. The injected pricing block is boilerplate that dilutes the payload slightly but is small relative to the whole.

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; the description correctly just notes they are full tweet objects with engagement counts. Pagination, defaults, sort semantics, the sibling relationship, and billing are all covered, so nothing needed 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, but the description adds semantic meaning beyond the schema by explaining what Relevance, Latest, and Likes actually surface. That is genuine interpretation, not restatement of the enum.

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 ('Get replies to a tweet') and immediately distinguishes itself from the sibling get_twitter_tweet_replies by naming the ordering control. An agent can tell the two apart 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 says to use this instead of `get_twitter_tweet_replies` 'whenever ordering matters' and explains what each ordering buys you ('Likes surfaces the community's top responses, Latest gives a live view'). The alternative and the selecting condition are both named.

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, open-world, non-destructive, so the description is freed to add what they don't: the return shape ('user objects — handle, name, bio, follower count, verification — not tweets') and cursor pagination. It adds no permission, rate-limit, or ordering detail, which is the only real gap.

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?

Core content is three tight sentences with the scope statement front-loaded and the negative clarification ('not tweets') placed early. The injected pricing boilerplate adds bulk the author did not control, which keeps this just short of 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 two-parameter read tool with full schema coverage, an output schema, and rich safety annotations, the description supplies the missing return-type context and the sibling disambiguation an agent needs. Only ordering/result-count behavior is unspecified, a minor omission.

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

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

Schema description coverage is 100%, so both parameters (tweetId, cursor) are fully documented in the schema itself. The description echoes pagination via 'cursor-paginated' but adds no format, cursor-opacity, or max-page-size detail beyond the schema. Baseline 3 is appropriate.

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

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

Specific verb and resource ('List the accounts that retweeted a given tweet') plus the pagination model. It also distinguishes itself from a close sibling by naming `get_twitter_tweet_quotes` as the tool for retweets with commentary, so an agent can route 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?

Gives an explicit use case ('map who amplified a message and how influential they are') and names the alternative tool for the adjacent case (quote tweets). It stops short of stating exclusions against the other retweet-adjacent siblings (replies, thread context), so it is clear context rather than complete routing guidance.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so safety is covered. The description adds real value beyond that: batch acceptance in one call and the exact fields returned (text, author, source client, language, creation time, engagement counts), which helps an agent judge sufficiency 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?

The core is front-loaded and tight, with purpose, precondition, alternative and return fields in three economical sentences. The appended pricing boilerplate adds length that serves billing context rather than tool selection, a minor deduction.

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

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

For a simple ID-expansion lookup with full schema coverage, an output schema, and rich annotations, the description supplies everything an agent needs: precondition, batch behavior, alternative entry point, and field coverage.

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?

Only one parameter and schema coverage is 100%, so the schema already documents the comma-separated ID format. The description's note that multiple IDs are accepted in one call adds a small amount of batch semantics but nothing about limits or ordering; baseline 3 applies.

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

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

States a specific verb (Fetch) and resource (full content of specific tweets) plus the precondition (you already know their numeric IDs). It also names the sibling `get_twitter_tweet_advanced_search` as the contrasting entry point, so an agent can place 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 when-to-use (you already have IDs) and when-not-to-use (if you do not have IDs yet), routing the agent to the correct alternative by name. The 'expand IDs surfaced by search, timelines, or replies' line clarifies its role in a workflow.

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 covered. The description adds valuable behavioral context: cursor-paginated output and the parent-chain reconstruction behavior. It stops short of noting auth requirements or rate limits, so a 4 is warranted.

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

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

The core description is front-loaded and efficient: purpose, trigger, return format, and alternative in four tight sentences. The appended billing note is clearly demarcated but does add non-behavioral length, keeping it just under 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?

With annotations covering safety, a full schema, and an output schema present, the description needn't explain return values yet still summarizes them usefully. It covers the key distinctions and pagination behavior; only auth/permission details are absent, which is minor given the read-only annotations.

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

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

Schema description coverage is 100%, so both parameters are fully documented in the schema itself (cursor semantics and the reply/original tweet note for tweetId). The description's 'accepts either a reply or an original tweet' merely echoes the schema's tweetId description, adding no new parameter semantics. 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 ('Reconstruct the conversation around a tweet') and clarifies its scope by noting it accepts either a reply or an original tweet. It explicitly distinguishes itself from the sibling get_twitter_tweet_replies_v2, so an agent can tell them apart 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?

Provides an explicit trigger condition ('when a tweet lacks context on its own and you need the parent chain') and names the alternative with its selecting condition ('For only the replies below a post use get_twitter_tweet_replies_v2'). Nothing is left to inference.

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

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive, so the safety profile is covered. The description still adds real value beyond that: what the panel surfaces (country, verification details, username-change history) and the shape of the return ('a single profile object under `data`'). It does not mention auth or rate limits, but the annotation bar is met with useful extra context.

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

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

Three front-loaded sentences with zero waste: purpose, use case, return shape, and sibling routing in order of importance. The appended pricing block is boilerplate, not part of the authored description.

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

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

An output schema exists, so return values need not be enumerated, yet the description still notes the `data` wrapper. For a one-parameter read tool with rich annotations, everything an agent needs to select and call it correctly is present.

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

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

Schema coverage is 100%, so the single userName parameter is fully documented by the schema; baseline is 3. The description's 'by @handle' offers a marginally different framing than the schema's 'screen name' but adds no syntax or format detail beyond it.

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

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

States a specific verb + resource — fetch the extended 'About this account' panel for an X user by @handle — and explicitly contrasts it with the sibling get_twitter_user_info. An agent can distinguish this from the standard-profile 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?

Gives explicit when-to-use ('provenance and trust checks') and names the alternative with its selecting condition ('For the standard profile (bio, follower counts, avatar), use get_twitter_user_info instead'). Nothing is left to inference.

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

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

Annotations already establish that this is a read-only, idempotent, non-destructive, open-world operation. The description adds only a usage-based pricing estimate, which is useful cost context but does not explain batch size behavior, return format, rate limits, or any other operational trait. It does not contradict the annotations, but it adds very little beyond them.

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

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

The text is short and structured as a comment block, so it is not bloated. However, it is almost entirely irrelevant to tool selection and invocation, with no front-loaded purpose statement. The resulting definition is under-specified rather than concise in any useful sense.

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 batch user-lookup tool with one undocumented parameter and an output schema, the description provides no operational, semantic, or usage information. Only a billing estimate is present, leaving the definition critically incomplete for correct tool selection and invocation.

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

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

The single input parameter, userIds, has 0% description coverage in the schema, and the description does not mention it at all. It does not explain the comma-delimited format, the 100,000 ID maximum, the 1 ID minimum, or what kinds of user identifiers are accepted. With low schema coverage, the description was required to compensate and completely failed to do so.

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 contains only a pricing boilerplate block and never states what the tool does. The name and title imply batch retrieval of Twitter users, but the description itself provides no verb, resource, or scope. This is a missing purpose, not merely a vague or tautological one.

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

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

No guidance is given about when to use this tool, when not to, or how it relates to alternatives. In particular, it never mentions the single-user sibling get_twitter_user_info or explains when batch lookup is preferable. An agent is left to infer usage entirely from the tool name.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive, so the safety profile is covered. The description adds genuinely new behavior: it answers both directions (A→B and B→A) in a single request and returns the flags under `data`. The pricing disclosure adds cost context. Minor gap: no note on what happens when a handle doesn't exist or when accounts are protected/private.

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

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

Front-loaded with the core behavior followed by the routing advice, with no redundant sentences. The injected pricing block inflates the text slightly but is boilerplate rather than author padding.

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, full schema coverage, and an output schema present, the description needn't explain return values, yet it usefully points to `data`. Routing to alternatives and bidirectional semantics are covered. Edge-case behavior (nonexistent/private accounts) is the only material omission.

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

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

Schema coverage is 100%, with both source_user_name and target_user_name documented as screen names, so the baseline is 3. The description only adds 'by @handle', a small hint on identifier format, but does not clarify directionality mapping (which param is the follower vs. the followed) 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 (check), resource (follow relationship), and scope (one X user follows another, both directions, by @handle). It explicitly names the sibling tools it is not (get_twitter_user_followers / get_twitter_user_followings), 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 when-to-use guidance: 'Use this for a single targeted lookup instead of paging through...'. Names the alternatives and the condition (single targeted lookup vs. paging), 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 cover the safety profile (readOnly, idempotent, openWorld, non-destructive), yet the description adds real behavioral context: 200 results per page by default, has_next_page/next_cursor pagination, and the shape of each entry. It stops short of stating rate limits or cursor lifetime, but the added pagination and page-payload detail is well beyond what the annotations provide.

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

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

Front-loaded with the core action, then pagination, then use cases, then sibling routing — a logical order with no redundant sentences. The injected aisa-pricing boilerplate adds length that does not serve tool selection, which keeps it out of the top band.

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

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

Despite an output schema existing, the description goes further by summarizing the per-entry fields, and it covers pagination, the identifier format, use cases, and both alternatives. Given a three-parameter read-only tool with full annotation coverage, an agent has everything needed to call it 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 the baseline is 3, and the description earns a step up by clarifying that the user is addressed by @handle rather than the schema's vaguer "screen name," and by restating the 200-per-page default in prose. It does not add cursor format or sizing rules beyond the schema.

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

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

States a specific verb (list), resource (accounts that follow a given X user), the identity key (@handle), and the ordering (newest follower first). It also names the two closest siblings and how they differ, so an agent can pick it apart from get_twitter_user_followings and get_twitter_user_verified_followers 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?

Explicitly gives when-to-use scenarios (audience analysis, mapping a competitor's follower base, finding influential followers) and names both alternatives with their selecting conditions — reverse direction for followings, verified subset for verified followers. It even flags that the verified sibling takes a numeric user_id rather than a handle, which is exactly the kind of routing detail that prevents a wrong call.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered structurally. The description adds genuine behavior beyond that: 200 entries per page, has_next_page/next_cursor paging, and a cost estimate (~$0.0036 per request, usage-based). It stops short of auth/permission requirements or rate-limit behavior, so it is strong but not complete.

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

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

The core sentence is front-loaded and every clause about direction and alternatives earns its place. The auto-injected pricing block adds length that is not behavioral guidance, which dilutes an otherwise tight definition.

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 explained, yet the description still flags the two pagination fields an agent needs to iterate. Combined with direction, alternatives, page size and cost, 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 description coverage is 100%, so cursor, pageSize and userName are already documented in the schema, and the description adds no format or syntax detail for them. The phrase 'identified by @handle' loosely maps to userName but the schema lists no required parameters, so the description does not clarify whether the handle is mandatory. 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 ('List the accounts a given X user follows'), and immediately pins the direction of the relationship with 'identified by @handle'. It explicitly names the sibling that does the opposite direction and the sibling that tests a single pair, so an agent can separate it from the ~30 other get_twitter_* 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 the analytical use case ('infer a user's interests, information sources, or professional network — who someone follows is usually a stronger signal of intent than who follows them') plus two explicit alternative routes: get_twitter_user_followers for the reverse direction and get_twitter_user_check_follow_relationship for a single pair without paging. When-to-use and when-to-use-something-else are both covered.

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 the meaningful scoping detail that this is a public-profile lookup keyed by handle, plus the returned field set; it does not mention auth or rate limits, which keeps it short of a 5.

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

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

Purpose is front-loaded and each subsequent sentence earns its place by routing to a distinct sibling. The injected pricing block adds length that is not part of the tool's semantic content, keeping 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?

An output schema exists so return-value explanation is optional, annotations carry the safety profile, and the single parameter is fully documented. An agent has everything needed to select and call this tool correctly, with sibling disambiguation included.

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 there is only one parameter, so the schema already documents it (baseline 3). The description adds value by specifying the format is the @handle/screen name and by routing numeric-ID callers to a different tool, which the schema alone does not convey.

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 (look up) and resource (one X/Twitter user's public profile) with the exact input form (@handle). It is immediately distinguishable from the profile-adjacent siblings it names, so an agent can route without opening any schema.

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

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

Gives an explicit when-to-use framing (to assess identity, reach, or credibility before trusting content) and then names three concrete alternatives with the condition that selects each: numeric ID → get_twitter_user_batch_info_by_ids, extended metadata → get_twitter_user_about, posts → get_twitter_user_tweet_timeline.

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

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

Annotations already establish read-only, idempotent, open-world, non-destructive behavior, so the bar is lower; the description still adds real behavioral context — cursor pagination and the response shape (data, has_next_page, next_cursor). It does not discuss rate limits or the billing estimate's non-fixed nature beyond the injected pricing note.

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