AIsa Social

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

Annotations already declare destructiveHint=true and openWorldHint=true, so safety is covered. The description adds valuable behavior: independence of items (one failure doesn't cancel others) and per-call billing. These are not derivable from annotations and help the agent set expectations.

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

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

Three short sentences with zero filler. The action and limit are front-loaded. The phrase 'tool-router's batch_use' is redundant since it restates the tool name, but it's a minor flaw. Overall it is concise and well-structured.

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

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

With annotations covering destructive behavior and an output schema presumably describing results, the description covers the key operational aspects: concurrency limit, independence, and billing. It doesn't mention error reporting formats, but those likely live in the output schema. It is sufficiently complete for a batch tool.

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

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

Schema description coverage is 100%, so the schema fully documents each parameter. The description adds no parameter-specific details. The calls parameter's description already explains the structure and batching context, so the baseline of 3 applies; the description doesn't need to compensate.

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

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

The description states a clear action (execute) and resource (operations) with a concrete limit (up to 20) and concurrency. It doesn't explicitly name the sibling 'use' for single operations, but the distinction is clear enough from the concurrency and limit. The redundancy of 'tool-router's batch_use' is minor.

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 no guidance on when to use this tool versus the sibling 'use' tool. The schema note about 'steps at the same execution_level of a plan go in one batch' is helpful, but it lives in the schema, not the description. The description only implies batching via concurrency but doesn't state when to choose it over the single-operation alternative.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds meaningful context: it is free, stops before any spend, and explains how price.model varies (quoted, list, dynamic, composed). It also clarifies that suggested_max_price_usd has headroom. This goes beyond the annotation flags and gives the agent a clear model of what happens.

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

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

The description is moderately long but well structured: it opens with the core purpose, then explains the price model in a dedicated paragraph. No redundancy or filler. It front-loads the most critical information (contract fields) and then gives necessary detail about price semantics. Slightly dense but not overly verbose.

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

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

The tool has an output schema, so return values need no description. The description covers the key behavioral aspects (no spend, pricing models, max_price headroom) and clarifies edge cases like routes without a price. For a read-only informational tool, this is complete enough for an agent to use 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 parameters are already documented. The description adds some nuance, such as how arguments affect pricing and that required parameters may be needed before a price can be quoted. It also clarifies with_quote's purpose (one round trip, spends nothing). These are useful but not essential given the schema's completeness.

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 purpose: returning the full contract of one or more operations, including schemas, read_only, side_effects, price, and known_pitfalls. It clearly distinguishes this from executing operations (use, batch_use) and from discovery (search, list_categories). The verb 'get' and the noun 'details' align with the title, and the first sentence is explicit.

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

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

The description implies the tool is used to assess an operation before spending (e.g., 'A quote authenticates like a call but stops before any spend'), and the schema says 'One operation_id from search', hinting at a flow. However, it never explicitly states when to choose this over siblings like use or search, nor does it give exclusions. The guidance is implied, not 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 readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering safety. The description adds useful behavioral context: the compact size (~4 KB), the normalized flat fields, and the explicit list of returned fields. It doesn't contradict annotations and goes beyond them by explaining what data shape to expect.

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

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

The description is dense but efficient. It front-loads the core purpose, then provides size comparison, field list, and usage guidance. Each clause earns its place; while it's a single long sentence, splitting it would improve readability but not information content.

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

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

For a single-parameter, read-only tool with an output schema, this description is remarkably complete. It specifies the exact return fields, clarifies the input constraint, provides provenance for the id, and gives routing to alternatives. Nothing an agent needs to call it correctly is missing.

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

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

The schema documents userId with a description and example, but the description adds crucial semantics: the id must be numeric, and it explains how to obtain it from other tools (data.user.id, search results, or post owners). This is meaningful beyond the schema's simple 'Instagram user id'.

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

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

The description opens with a specific verb and resource: 'Returns a compact public profile for a numeric Instagram user id.' It immediately distinguishes itself from get_instagram_profile by contrasting size (4 KB vs 380 KB) and field list. An agent can tell exactly what this tool does and how it differs from siblings 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?

The description gives explicit when-to-use and when-not-to-use guidance: 'Prefer this endpoint whenever the id is in hand' and 'Use get_instagram_profile only when a handle is all that is available.' It also explains how to obtain the id from three other tools, fully routing the agent to the correct alternative.

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

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

Beyond the readOnly/idempotent/non-destructive annotations, the description discloses the photo-error behavior, the two-minute duration limit, the measured 13-second latency, and an approximate 1 KB response size. These are the operational behaviors an agent needs to anticipate and they do not contradict 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?

Four sentences each carry distinct information: purpose and output, constraints and error, performance and payload size, and the caption alternative. The most important selection criteria are front-loaded before operational details.

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

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

With a single parameter and an output schema present, the description covers everything an agent needs to decide and invoke correctly: input constraints, failure mode, fallback verification, and the sibling tool to use for captions. No critical gap remains.

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

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

The schema only says the url is an Instagram post or reel URL, but the description adds substantive meaning: it must be public, a video or reel, under two minutes, and should be verified with is_video when the type is unknown. This materially improves correct invocation.

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: it transcribes speech in a public Instagram video or reel and lists the returned transcript fields (id, shortcode, and transcribed text). This clearly differentiates it from caption-focused siblings like get_instagram_post.

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 explicit conditions for use: the target must be a video under two minutes, a photo returns 400 bad_request, and when the type is unknown the agent should check is_video with get_instagram_post first. It also directs the agent to use get_instagram_post's edge_media_to_caption when the written caption is 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: the response size ('Measured at about 197 KB'), the credit cost difference (1 vs 10 credits), and the side effect of download_media=true ('mirrors the media to permanent storage'). This is useful behavioral disclosure that annotations don't provide.

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

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

The description is three sentences with no filler. It front-loads the core purpose and return data, then adds the cost warning, then routes to siblings. Every sentence earns its place and the structure is logical.

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

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

The description is complete for a read-only metadata tool. It covers the return path, key fields, response size, cost implications, and sibling routing. The output schema exists, so return values don't need further explanation. An agent has everything needed 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 schema already documents all four parameters. The description adds context for download_media (credit cost and permanent storage) and implies the URL is the primary identifier, but it doesn't add much beyond the schema for trim or region. Baseline 3 is appropriate since 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 ('Returns full metadata'), a specific resource ('one public post or reel identified by its URL'), and the exact data path ('data.xdt_shortcode_media'). It also lists the key fields returned, which distinguishes it from sibling tools like get_instagram_post_comments and get_instagram_media_transcript.

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

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

The description explicitly names sibling tools for related use cases: 'For the comment thread call get_instagram_post_comments with the same URL, and for the spoken words in a video call get_instagram_media_transcript.' It also gives clear guidance on when to use the download_media parameter ('leave it off unless the files are needed'). This is explicit routing and usage context.

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

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

Beyond the annotations (read-only, idempotent, non-destructive), the description adds valuable behavioral context: the response is normalized and small (~10 KB), only top-level comments are returned, child_comment_count is informational only, and replies cannot be expanded. This materially helps the agent set expectations about output size and limitations.

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, each earning its place: the first defines the return shape, the second adds a size expectation, and the third clarifies scope limits and routes to a sibling tool. The core behavior is front-loaded and there is no redundant restating of the schema or annotations.

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

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

For a simple GET-like tool with two parameters sufficient descriptions in the schemached, an output schema, and strong annotations, the description is complete. It covers paging, top-level-only behavior, the unexpandable replies limitation, and the sibling tool for related data, so nothing an agent needs to call it correctly is missing.

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

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

The input schema already describes both parameters fully (url and cursor), so the schema carries most of the burden. The description adds minor context by confirming the URL may point to a post or reel and mentioning the cursor is used for paging, but it does not substantially extend the schema's parameter explanations.

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 names a specific resource (comments on a public Instagram post or reel by URL) and states the action (returns them in a normalized shape). It also lists the exact fields returned)Skip and distinguishes itself from get_instagram_post by directing that tool to post metadata, so an agent can tell it apart 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 states when to use the tool (when you need comments on a public post/reel), and explicitly says to call get_instagram_post instead for the post itself. It also discloses that only top-level comments are available and that no endpoint expands replies, preventing fruitless attempts to fetch child comments through this API.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds valuable operational context beyond those hints: the data comes from Instagram's own web API, the payload is about 380 KB, trim barely reduces it, and the response contains specific fields under data.user. No contradiction with annotations exists.

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

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

The description is dense but every sentence earns its place: it states the purpose, lists the response contents, gives the payload size, warns about trim's inefficiency, and points to the lighter alternative. It is front-loaded with the core result and organized in a logical flow.

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 two-parameter tool with an output schema present, the description covers response shape, payload size, the trim caveat, and the sibling alternative thoroughly. It does not mention error cases or rate limits, but the annotations and output schema reduce the burden, making the description complete enough for correct invocation.

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

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

Schema coverage is 100%, so the schema already documents both parameters. The description goes further by quantifying trim's actual effect (saves under one percent) and advising against relying on it, which is meaningfully useful semantics beyond the schema. The handle parameter is adequately covered by its example in the schema.

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

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

The description states a specific verb and resource: 'Returns the full public profile for an Instagram handle'. It also distinguishes itself from get_instagram_basic_profile by noting the basic variant returns the same headline numbers in 4 KB when the numeric id is known, so an agent can easily tell the two apart.

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 names get_instagram_basic_profile as the alternative when the numeric id is already known, including the size trade-off. It also warns that trim=true saves under one percent and should not be relied on, giving clear when-to/when-not-to guidance for configuration.

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, openWorldHint, idempotentHint, and destructiveHint falsecars. The description adds meaningful behavioral context beyond that: the source is Google's public index, coverage is incomplete, measured size/time are provided, and engagement counts are populated. This gives the agent concrete expectations about data scope and performance without contradicting annotations.

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

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

The description is compact yet information-dense, with the core purpose front-loaded, followed by coverage constraints, performance characteristics, and explicit routing to alternatives. Every sentence adds useful information, and nothing is 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?

Given the tool's complexityaine, the presence of an output schema listing all return fields, annotations covering safety, and a thorough description of behavior, limitations, and alternatives, the definition is fully sufficient for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters with examples and descriptions. The description adds some interpretive value (e.g., date_posted narrows to a relative window) but does not materially expand parameter semantics 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?

The description uses a specific verb ('Searches') and names the exact resource ('reels by keyword through Google'), while distinguishing it from the login-gated Instagram search. It also explicitly differentiates from sibling tools like get_instagram_search_hashtag and get_instagram_reels_trending, making the tool's unique role immediately clear.

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

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

The description explicitly states when to use this tool vs alternatives, naming get_instagram_search_hashtag for hashtag searches and get_instagram_reels_trending for trending reels with no query. It also clarifies coverage limitations and the behavior of date_posted, giving clear context for selecting and invoking the tool.

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

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

The description discloses that Instagram serves small overlapping batches, that the tool returns about 30 reels and 411 KB, and that play_count and ig_play_count came back null on every item. This goes well beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) and gives the agent critical expectations about pagination, size, and null fields. No contradiction with annotations.

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

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

The description is dense but every sentence earns its place: it states the source, the normalized shape, the batching/overlap behavior, the measured size and null fields, and the sibling alternative. It is front-loaded with the core purpose and then provides operational details. No fluff or repetition.

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

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

Given the tool has no parameters, an output schema exists, and annotations cover safety/idempotency, the description is complete. It explains the return shape, the need for de-duplication, the null-field caveat, and the alternative for topic search. An agent has everything needed to invoke and process the result correctly.

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

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

The tool has zero parameters, and the schema coverage is 100% (empty properties). The description explicitly states 'Takes no parameters and cannot be filtered,' which adds clarity beyond the empty schema by ruling out any hidden filtering capability. Since there are no parameters to document, the description fully covers parameter semantics.

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

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

The description states a specific verb ('Returns'), a specific resource (the public instagram.com/reels page), and the normalized shape of the result. It also explicitly distinguishes itself from get_instagram_reels_search, which is a sibling tool, by noting the difference in play_count/ig_play_count population. This makes the tool's purpose unmistakable.

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

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

The description explicitly says the tool takes no parameters and cannot be filtered, and it directs the agent to use get_instagram_reels_search for topic-based search. It also provides operational guidance: call repeatedly and de-duplicate on shortcode because batches overlap. This is clear when-to-use and when-not-to-use guidance.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint false), the description discloses that it searches via Google, returns a normalized shape consistent with a sibling tool, notes that the cursor is a Google page number (not an Instagram cursor), and gives an approximate response size (~78 KB). This adds substantial behavioral context beyond what annotations provide.

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

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

The description is a single paragraph that front-loads the core purpose, then adds critical usage details (media_type, cursor semantics, size) and a routing note. It is informative without being bloated, though it could be tightened by removing the size measurement which may be overly specific for an agent's selection decision.

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 4-parameter schema with enums, an output schema, and rich annotations, the description covers the search method, parameter nuances, sibling differentiation, and performance expectation. An agent has all necessary information to select and invoke this tool correctly without missing context.

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

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

Schema coverage is 100%, so every parameter is documented in the schema. The description adds meaningful nuance for the cursor parameter (explaining it is a page number) and clarifies media_type options ('narrow to reels'), which go slightly beyond the schema's basic descriptions. This justifies a score above the baseline of 3.

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

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

The description states a specific verb ('Finds') and resource ('public posts carrying a hashtag through Google'), and explicitly distinguishes it from the sibling get_instagram_reels_search by contrasting the search method. The purpose is unambiguous and differentiated.

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

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

It clearly states when to use this tool versus the alternative: 'To search caption keywords rather than a hashtag, use get_instagram_reels_search.' It also explains the media_type option for narrowing results, providing explicit usage context without leaving anything 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=true, openWorldHint=true, and idempotentHint=true, so the safety profile is covered. The description adds measurable operational context ('Measured at about 18 KB and 13 seconds') and discloses that the tool relies on Google search results, which an agent can factor into cost and reliability decisions. No contradiction with annotations.

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

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

The purpose, cost, downstream chaining, and sibling routing are each valuable and the description is front-loaded. However, the first sentence enumerates roughly fifteen output fields, which is largely redundant with the existing output schema and makes the description longer than needed.

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 the output schema documenting return fields and annotations covering safety and open-world semantics, the description fills the remaining gaps: cost, search mechanism, and downstream integration. An agent has everything needed to decide whether and how to call 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 coverage is 100%, and the description adds little beyond it: 'keyword or bio phrase' restates the schema's 'Bio or caption keyword/phrase to search for,' and the cursor behavior is already documented ('next Google results page number'). Baseline 3 is appropriate when the schema carries the parameter documentation.

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

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

The description opens with a specific verb and resource scope: 'Searches Google for public Instagram profiles matching a keyword or bio phrase' and enumerates exactly what is returned. It differentiates from sibling search tools by naming get_instagram_search_hashtag and get_instagram_reels_search for post search, so an agent can distinguish profile-search from post-search 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?

Explicit when-not guidance is given: 'To search posts rather than people, use get_instagram_search_hashtag or get_instagram_reels_search.' The description also gives a downstream chaining instruction ('The numeric id feeds get_instagram_basic_profile directly'), which helps an agent plan multi-step workflows.

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 tool as read-only, idempotent, and non-destructive, so the description doesn't need to repeat those. It adds significant behavioral context by mentioning the raw response shape, the approximate payload size (177 KB), and the output fields (cursor and has_more for paging), which help set expectations about response characteristics 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?

The description is relatively concise and front-loads the core function, then provides usage guidance, response details, and a sibling alternative in a logical flow. It is a bit longer than strictly necessary but every sentence adds value, so it earns a 4 rather than 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?

Given the presence of an output schema, the description doesn't need to detail return fields, but it still covers paging and the raw shape. The main gap is that it doesn't explain potential errors or edge cases (e.g., invalid audio_id), but the tool is relatively simple with only 2 parameters and good annotation coverage, so the description is nearly complete.

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

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

The input schema already comprehensively describes both parameters (audio_id and cursor) with examples and descriptions, so schema coverage is 100%. The description adds limited extra meaning by explaining how to derive audio_id from URLs or other API responses, but it doesn't elaborate on cursor usage beyond what the schema says. Thus, a baseline of 3 is appropriate.

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

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

The description clearly states the tool returns reels using a specific audio track, identifying the resource and the verb. It distinguishes itself from siblings by explicitly naming get_instagram_reels_search as the alternative for keyword-based search, making its unique purpose unambiguous.

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

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

It provides explicit guidance on when to use this tool vs alternatives, stating to use get_instagram_reels_search for keyword-based queries instead. It also gives concrete instructions on how to obtain the required audio_id, including two specific methods, which is critical for correct invocation.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds valuable behavioral context beyond those hints: result size (~206 KB), inlined markup/styling, and that it carries no structured data. This helps agents decide to store/render rather than parse. It does not mention rate limits or auth, but those are not required for this read-only embed 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?

Three sentences, each earning its place: first states the core action/output, second adds critical size/usage caveat, third provides routing to alternatives. The most important information (what it returns and how to use it) is front-loaded. No filler.

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

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

For a single-parameter tool with an output schema, the description is complete: it explains the return type (HTML string), the behavioral requirement (store/render, not read), the absence of structured data, and directs to alternatives. The output schema covers return details, so no further explanation is needed.

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

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

Schema coverage is 100% and the only parameter 'handle' is documented with an example, which meets the baseline. The description adds meaningful semantic distinction by noting that this tool takes a handle, unlike get_instagram_basic_profile which requires a numeric id, and by clarifying the tool's output is an HTML string derived from the handle. This helps agents select the correct identifier format.

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 Instagram's official profile embed widget for a handle as a single html string') and explicitly contrasts it with siblings that return structured data (get_instagram_basic_profile, get_instagram_profile). An agent can immediately distinguish this tool's purpose from the rest of the family 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?

It gives explicit when-to-use guidance ('ready to drop into a web page') and explicit when-not-to-use with named alternatives and conditions: 'for follower counts, biography or bio links use get_instagram_basic_profile when the numeric id is known, or get_instagram_profile when only the handle is.' This routes agents to the correct sibling based on data needs and available identifier.

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 read-only, idempotent, and non-destructive profile, so the description adds value by disclosing concrete behavioral traits: the response echoes the id as highlight:<id>, the prefixed input causes a misleading 404, and the payload size is roughly 630 KB for 38 stories with size scaling. This is exactly the kind of context structured 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?

Four sentences, each earning its place: the return payload, the source of the id, the critical prefixed-form pitfall, and size scaling. No fluff, no redundant restatement of schema or annotations.

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

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

For a single-parameter, read-only tool with an output schema and safety annotations, the description provides everything an agent needs for correct invocation: how to obtain the id, how to format it, the failure mode to avoid, and an indication of response size. Nothing material appears missing.

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

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

The schema already documents id and points to the highlights endpoint, giving a high baseline. The description adds essential semantics beyond the schema: the id must be a bare numeric value, not the prefixed highlight:<id> form, even though the response echoes the prefixed version. This prevents a real, observed failure mode and clarifies that the parameter should be supplied despite the empty required array.

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

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

The description opens with a specific verb and resource: 'Returns the stories inside one highlight album' and enumerates the payload fields (reel_type, latest_reel_media, owning user, items). It also references get_instagram_user_highlights for obtaining the id, which helps distinguish this detail endpoint from the album-list sibling.

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 establishes a clear workflow by instructing the agent to 'Pass the bare numeric id from get_instagram_user_highlights.' It also warns against feeding the prefixed form and explains the resulting misleading 404. It doesn't explicitly enumerate when to choose this over unrelated siblings, but the dependency relationship is clear.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds useful behavioral context beyond that: it notes the response is small (~6 KB), cheap, and reveals whether an account keeps highlights at all. It also clarifies the dependency on the numeric id, which helps the agent understand usage patterns. This is meaningful additional context, though 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?

The description is compact and front-loaded: the purpose is stated first, then key return details, then the critical dependency, then a parameter optimization tip. Every sentence adds value, and there is no filler. It is well-structured and efficient.

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

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

Given the tool's simplicity (two optional parameters, read-only, idempotent) and the existence of an output schema, the description covers everything an agent needs to invoke it correctly: what it returns, how it relates to the detail tool, performance characteristics, and a usage tip. No critical information is missing.

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

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

Schema description coverage is 100% — both handle and user_id are fully described with examples and usage notes. The description repeats the tip about using user_id for faster responses, which is already in the schema. No additional semantic information about parameters is provided beyond the schema, so the baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Lists the story highlight albums on a public profile.' It names the exact output fields and distinguishes itself from the sibling tool get_instagram_user_highlight_detail by explaining it is the source of the highlight id. This makes the tool's purpose unambiguous.

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

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

The description explicitly states when to use this tool: it is 'the only source of a highlight id' and that the detail tool requires the id exactly as returned here. It also advises using user_id for faster response, which guides parameter choice. This is explicit when/why guidance with a clear alternative mentioned.

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

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

Beyond read-only annotations, it discloses pagination behavior (next_max_id, more_available, num_results), response size (~632 KB, trim only reduces to 523 KB), and mentions internal flags and large payload, which is critical for performance expectations. No contradiction with annotations.

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

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

The description is dense and front-loaded with the primary purpose, then covers pagination and size. It includes a helpful comparison to siblings, though the size details (632 KB vs 523 KB) may be more than needed, making it slightly verbose but each sentence adds value.

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

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

Given a clear output schema exists (though not shown in detail, it's told as 'has output schema: true'), the description covers pagination, size, and alternative routes, which is adequate for a complex tool. Missing details like error handling or rate limits are minor given the rest of the context.

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

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

The schema covers all parameters (100%), and the description adds context around next_max_id and trim (trim doesn't reduce size much), but doesn't explain handle beyond the schema's 'Instagram handle' or next_max_id beyond 'Cursor to get next page'. Baseline 3 is appropriate as 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 ('Returns'), resource ('public account's timeline, reels and photos and carousels'), and result format ('raw Instagram media objects under items'), clearly distinguishing it from siblings like get_instagram_user_reels and get_instagram_post by scope and raw shape.

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 tells when to use this versus alternatives for reels or single posts, and notes that alternatives return the same raw shape, guiding selection. It doesn't explicitly state when NOT to use this tool (e.g., for profiles), but the context and sibling names imply those use cases.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior, so the burden is lower. The description still adds valuable behavioral context: it returns only one page, exposes raw Instagram media objects under items[].media, provides paging_info.max_id for the next page, reports the approximate response size (594 KB), and reveals which media fields are included.

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

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

Four dense sentences, each earning its place: the first defines the primary output and pagination, the second enumerates fields and cross-tool linkage, the third gives performance guidance, and the fourth names an alternative. No repetition or filler.

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

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

Given the annotations, complete schema coverage, and an output schema, the description covers everything an agent needs to call and interpret the tool correctly: pagination, response shape, performance tradeoff, returned field references, and the sibling to use for broader timelines.

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, trim, and max_id. The description mostly restates the schema's advice to prefer user_id for faster responses and doesn't add substantial new meaning per parameter. It does add useful cross-tool output semantics, but that relates to return values rather than parameter usage.

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

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

The description opens with a specific verb and resource: 'Returns one page of a public account's reels'. It clearly differentiates itself from the sibling get_instagram_user_posts by explicitly scoping this tool to reels only and noting that posts covers the whole timeline including photos and carousels.

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

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

The description gives explicit when-to-use guidance: pass user_id instead of handle for faster responses, use max_id from the previous response for the next page, and use get_instagram_user_posts instead when the whole timeline including photos and carousels is needed. It also chains to get_instagram_song_reels via the audio_asset_id explanation.

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

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

Beyond the readOnly/idempotent/non-destructive annotations, the description discloses pagination via cursor, page size semantics, payload sizes (104 KB vs 28 KB), exactly what trim=true keeps, and the relative-URL prefixing requirement. These are valuable behavioral details an agent needs to call the tool correctly and interpret results.

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

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

The description is dense but every sentence contributes: scope, pagination, field differences, size/trim tradeoff, URL provenance, and sibling routing. It is not overly long per the value it delivers, though the field list could arguably be trimmed.

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, annotations already covering safety, and this description covering pagination, payload size, field trim behavior, and URL construction, the agent has everything needed to select and invoke the tool correctly. No important gap remains.

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 examples, so the baseline is 3. The description goes beyond the schema by explaining trim=true's effect on field subset and size, cursor-based pagination, and how to construct or validate the url parameter (relative board URLs need https://www.pinterest.com prefix). This adds meaningful context.

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 action ('Returns one page of pins') on a specific resource ('from a board URL') and explicitly distinguishes the result field subset from search results and pin detail. It also names the sibling get_pinterest_user_boards as the different tool for board lists, making the purpose unmistakable.

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

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

The description gives explicit guidance on when to use this tool; it explains that board URLs come from search results' board.url or from get_pinterest_user_boards, and it directly routes the agent to get_pinterest_user_boards when a board list rather than one board's pins is needed. This is clear when-to-use and alternatives guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the bar is to add context beyond that — and the description delivers richly: empirically measured response sizes (12.5 KB vs 1.6 KB trimmed), exact fields preserved/dropped by trim, shortcode URLs returning 404 at a measured rate (3 of 12), and expectation of 404s on deleted pins. These are behavioral realities the agent could not infer from annotations or schema.

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

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

The description is dense and logically ordered: purpose → response shape → size/trim tradeoff → sibling routing → failure modes. Every sentence earns its place and the most decision-critical fact (what it fetches, by what URL form) is front-loaded. It loses one point only because the two field enumerations make it longer than strictly necessary given an output schema exists.

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 a full output schema and safety annotations, this description covers every decision an agent needs to make: what the tool does, URL format validation, trim's exact effect, which sibling to use instead, and realistic failure expectations. 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 coverage is 100% for both parameters, so baseline is 3, but the description goes far beyond the schema's generic 'Pinterest pin URL' and 'trimmed down version'. It specifies the exact URL form expected, the numeric-id requirement and shortcode failure mode for url, and precisely what trim does — which fields survive and which are dropped, plus the size delta. This materially improves an agent's ability to set trim correctly.

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

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

The description opens with a specific verb and resource: 'Fetches one pin by URL, of the form pinterest.com/pin/<id>.' It immediately distinguishes this from sibling search tools by emphasizing single-pin-by-URL lookup and explicitly noting the response shape differs from search results. An agent can tell exactly what this tool does and how it differs from get_pinterest_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?

Explicit routing guidance is provided: 'To find pins by keyword use get_pinterest_search; to page through the board a pin sits on use get_pinterest_board.' It also tells the agent when NOT to call (URLs ending in shortcodes) and what to check before calling (numeric trailing id). No other sibling in the list is left ambiguous relative to this tool.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description reveals concrete behavioral details: approximate response size for 17 pins, the 28 KB trimmed size, exactly which fields trim retains and drops, and the fact that results include a paging cursor. This is additive and highly useful context.

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

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

The description is dense but every sentence earns its place: a clear one-sentence purpose, a compact field enumeration, measurable size guidance, and sibling routing. It front-loads the core behavior before diving into payload details.

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

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

For a search tool with pagination, an optional trim mode, and a rich output shape, the description covers all essential operational context: result contents, size implications, field trade-offs, cursor usage, and related endpoints. The presence of an output schema further reduces any missing return-value ambiguity.

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?

Although the schema already documents all three parameters, the description adds meaning beyond the schema: trim's field-level impact, the cursor's role in pagination, and the keyword matching behavior. It also clarifies the response shape per pin, making parameter choices more informed.

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

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

The description opens with a specific verb and resource: 'Searches Pinterest for pins matching a keyword and returns pins plus a cursor to page.' It clearly distinguishes the tool from sibling Pinterest tools by stating it is keyword-based and explicitly routes follow-ups to get_pinterest_board and get_pinterest_pin.

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

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

The description provides explicit decision guidance: use trim only when full fields are needed, feed board.url to get_pinterest_board, and use get_pinterest_pin for engagement counts on a single pin. This tells an agent exactly when this tool and its alternatives are appropriate.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, covering safety. The description adds valuable behavioral context: it discloses response size and the effect of the trim parameter (trim ratio, what fields are kept), which goes beyond the schema. It doesn't contradict annotations.

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

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

The description is packed with useful information but is slightly longer than necessary. It front-loads the core purpose and then adds efficiency details. Every sentence contributes value, though the trim ratio could be considered a minor distraction; still efficient.

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

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

For a low-complexity tool with only two parameters, one required, and an output schema present, the description covers purpose, usage, parameter semantics, and behavior. There are no gaps that would prevent an agent from calling 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?

The schema already documents both parameters (trim and handle) with examples and descriptions, so baseline is 3. However, the description enhances meaning by explaining the trim impact (size reduction and field list), which is not in the schema, adding clear value beyond the schema.

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

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

The description clearly states the tool lists a user's public boards by username, with a cursor for pagination. It identifies the specific resource (Pinterest user boards) and differentiates itself from siblings by naming get_pinterest_board for board pins and get_pinterest_search for Pinterest-wide search.

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

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

The description explicitly instructs to use get_pinterest_board for reading board pins and get_pinterest_search for searching across Pinterest, providing clear when-to-use guidance. It also specifies the handle format (bare username, not full URL), which is a key usage detail.

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

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

Beyond the readOnly/idempotent hints, it reveals the exact top-level paging shape ('more.has_more and more.cursor'), the nested replies structure, and an empirical size ('21 KB for 19 top-level comments'). This gives an agent concrete expectations for response shape and cost.

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 behavior and paging warning are front-loaded, but the first sentence lists many fields that the output schema likely already specifies, making it longer than necessary. The size estimate and routing guidance earn their place.

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

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

For a read-only post-comments tool, it covers the URL input, response fields, paging mechanism, result size, and the relationship to search siblings. Given the annotations and output schema cover safety and structured return values, nothing critical is missing.

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

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

Input schema coverage is 100%, with the url, trim, and cursor parameters already described. The description adds context around cursor/paging, but does not materially change how the parameters are invoked, 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?

Opens with 'Returns one post and its discussion from a post URL', naming the verb, resource, and input. It enumerates post and comment fields, and contrasts paging with get_reddit_search/get_reddit_subreddit_search, so an agent can tell it apart from sibling search tools.

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

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

Explicitly tells the agent to 'start from get_reddit_search or get_reddit_subreddit' to find posts worth opening, which frames when this tool is the follow-up. It also warns that paging differs from those siblings. It does not spell out exclusion cases such as when get_details would be preferred, but the context is clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds substantial behavioral context beyond that: it discloses performance characteristics ('Measured at 8 to 16 seconds and 8 to 26 KB, the slowest endpoint here'), the pagination mechanism (after token), and the full list of fields returned. No contradictions with annotations.

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

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

The description is dense but front-loaded: the core purpose and paging mechanism appear first, followed by output details and parameter behavior, then performance and alternatives. Each sentence contributes information without redundancy. It's longer than minimal but justified by the tool's complexity.

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

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

Given the output schema is provided, the description doesn't need to enumerate return types, but it still lists key fields. It covers scope (all public subreddits), pagination, sorting, timeframe, performance, and alternatives. An agent has everything needed to decide when and how to call 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 coverage is 100%, so baseline is 3. The description adds meaning to sort ('accepts relevance, new, top and comment_count') and timeframe ('narrows the window'), and explains the after token's role in pagination. It does not explicitly describe trim, but the schema already documents it, and the description provides enough added value to warrant a 4.

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

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

The description opens with a specific verb and resource: 'Searches every public subreddit for posts matching a query and returns posts plus an after token to page.' It clearly distinguishes itself from sibling tools by naming get_reddit_subreddit_search and get_reddit_post_comments, so an agent can immediately tell this is the global search endpoint.

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

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

Explicitly states when to use alternatives: 'To stay inside one community use get_reddit_subreddit_search, which is faster and pages with cursor rather than after; to read one post's discussion use get_reddit_post_comments.' This gives direct routing guidance with clear conditions, 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?

Beyond the readOnly/idempotent annotations, it discloses page size ('about 18 KB for 24 posts'), the constraint error behavior (400 rather than ignoring timeframe), case sensitivity of subreddit names, and that results use an after token for pagination. No statement contradicts the annotations.

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

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

The description front-loads the purpose and then packs in field names, accepted sort values, a constraint, and sibling routing. It is largely efficient, though the sort value list and field list slightly overlap with schema/enum 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?

With an output schema present and rich annotations, the description covers the remaining essentials: pagination token, sort/timeframe constraint, case sensitivity, response size, and related tools. Nothing needed for correct invocation is missing.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful parameter context beyond the schema: subreddit names are case-sensitive, timeframe only works with sort=top and the failure mode is a 400, and after is the pagination token.

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 specifies a concrete action and resource: 'Returns the post stream of one subreddit with an after token to page.' It also names sibling tools for search and metadata, so an agent can distinguish it from get_reddit_subreddit_search and get_reddit_subreddit_details.

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 routing: use get_reddit_subreddit_search for searching inside the same subreddit and get_reddit_subreddit_details for metadata. It also warns that timeframe is only valid with sort=top and that other combinations return 400, so the agent knows when not to supply timeframe.

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

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

Annotations already declare readOnly, idempotent, open world, and non-destructive behavior, so the bar is lower. The description adds meaningful behavioral details beyond those: case-sensitive name resolution, approximate response size (about 5 KB), and the guarantee that no posts are included in the response.

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

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

The description is efficiently structured: what it returns, why to use it, a critical behavioral caveat, and sibling routing. The field list is long but directly useful, and no sentence is 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?

For a read-only metadata tool with an output schema, the description covers selection, invocation, caveats, and alternatives. Nothing material is missing: the agent knows what to expect, how to avoid case-sensitivity pitfalls, and when to choose a sibling tool instead.

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

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

Schema description coverage is 100%, so the schema already documents both parameters, their examples, and the case-sensitivity requirement. The description adds that the tool works 'by name or by URL', which is useful context but largely reinforces what the schema already conveys.

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 names a specific verb ('Returns metadata') and a specific resource ('one subreddit'), and enumerates the exact fields returned. It also distinguishes itself from siblings by explicitly stating it returns no posts and pointing to get_reddit_subreddit and get_reddit_subreddit_search for those cases.

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 concrete use cases: 'size a community or read its rules before posting anything elsewhere.' It also states what the tool is not for ('returns no posts at all') and names the alternatives to use instead, giving an agent clear routing logic.

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

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

Annotations already mark this as read-only and non-destructive, but the description adds critical behavioral details: every sort value returns only posts and never comments or media, response size is about 5 KB with ~2 second latency, and it is faster than the global search. This goes well beyond what annotations provide and corrects a misleading implication of the sort parameter.

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

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

Every sentence in the description earns its place: scope and pagination, return fields, the sort caveat, performance comparison, and the routing to a sibling tool. The most important distinguishing information is front-loaded.

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

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

Given the rich schema, output schema, and annotations, the description fully covers what an agent needs to select and invoke the tool correctly. It includes return field details, pagination behavior, performance expectations, the surprising sort behavior, and when to use sibling tools.

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

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

The input schema has 100% coverage, so parameters are already documented. The description adds extra semantic value by clarifying that the sort parameter's values all produce posts-only results and by explaining that cursor is the pagination token. This lifts it above the baseline.

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

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

The description clearly states the tool searches within one subreddit and returns matching posts, with a cursor token for pagination. It also distinguishes itself from get_reddit_search, which searches all of Reddit, so an agent can tell them apart.

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

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

The description explicitly names get_reddit_search as the alternative for all-of-Reddit searches and explains the difference in scope and pagination mechanism. It also points to get_reddit_post_comments for retrieving replies under a result, giving clear 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 cover readOnly, openWorld, idempotent, and non-destructive behavior, so the bar is lower. The description adds useful behavioral context: it returns complete text rather than truncated preview and locates the result under 'article'. This enriches the annotation profile without contradicting it.

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

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

Three sentences with zero filler. The core purpose, exact usage condition, return field, and sibling reference are all present and front-loaded. Every sentence contributes value.

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

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

With one parameter, a documented output schema, and annotations covering safety, the description is complete. It tells the agent when to use it, what it returns, and how it differs from the nearest sibling. No critical information is missing.

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

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

Schema description coverage is 100% for tweet_id, so the schema independently documents the parameter. The description only restates 'by its tweet ID', adding no new format, constraints, or examples beyond the schema. Baseline 3 is appropriate because the schema carries the semantics.

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

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

The description states a specific action (Get), resource (full body of an X Article), and identifier (tweet ID). It clearly differentiates from get_twitter_tweets by calling out ordinary tweets as a separate case, so an agent can distinguish the tool 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?

Explicit when-to-use guidance is given: 'when a tweet links to or is an Article and the 280-character preview is not enough.' It also names the alternative for ordinary tweets ('use get_twitter_tweets'), leaving no ambiguity about tool selection.

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, openWorld, and non-destructive traits. The description adds context beyond those annotations by specifying that the result is returned under `community_info` and by framing the operation as qualifying a community before further retrieval.

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, all informative, with the core purpose and expected return value front-loaded and no filler. The alternative-usage sentence is efficient and 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 only one parameter, complete annotations, a likely output schema, and a sibling routing instruction, the description covers every decision an agent needs to invoke this tool correctly. Nothing important appears 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 value by clarifying the ID's format ('numeric community ID') and its role within X Community context, which is not made explicit in the schema's generic 'ID of the community'.

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

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

The description uses a specific verb ('Get metadata') and identifies the exact resource ('an X Community by its numeric community ID') plus the fields returned (name, description, member count, access rules). It clearly distinguishes itself from sibling tools like get_twitter_community_members and get_twitter_community_tweets_all.

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

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

It explicitly states when to use the tool: 'Use this to qualify a community before pulling its members or posts.' It also names an alternative for discovering communities by topic: search their posts with get_twitter_community_tweets_all.

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 convey readOnly, openWorld, idempotent, and non-destructive behavior. The description adds useful behavioral context beyond annotations: cursor-based pagination and a full-user-object return shape. It stops short of discussing limits or cursor lifecycle, but the annotations lower the bar for safety-related 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?

Three sentences with no wasted words: purpose is first, use case follows, return shape is stated, and the relevant alternative is named. Every sentence contributes actionable 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 simple list operation with a required ID, an optional cursor, a full output schema, and safety annotations, the description covers all essential decision points: what it lists, why to use it, what it returns, and which sibling handles the related moderator case.

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 description adds only a minor nod to pagination via 'cursor-paginated' but no extra meaning beyond the schema, warranting the baseline score of 3.

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

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

The description uses a specific verb ('List') with a precise resource ('members of an X Community') and states it is cursor-paginated. It also distinguishes itself from the moderators tool, so an agent can tell them apart immediately.

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

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

It explains when to use this tool: to map participants in a topic-specific group, noting that membership is opt-in and higher-signal than general followers. It explicitly points to `get_twitter_community_moderators` for the moderator subset, giving clear routing to an alternative.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds that it is cursor-paginated and returns full user objects, which are not in the annotations. This provides useful behavioral context beyond the structured metadata, with no contradiction.

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

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

Two sentences with zero waste. The core function and pagination are stated first, then use case and alternative. Front-loaded and efficient.

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

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

For a simple read-only tool with 2 parameters (1 required), full output schema, and annotations covering safety, the description covers use case, pagination, return format, and alternative. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100% (both cursor and community_id have descriptions). The description mentions cursor-paginated but does not add new parameter details beyond the schema. Since the schema already documents both parameters clearly, the baseline of 3 is appropriate.

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

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

The description uses a specific verb 'List' and resource 'moderators of an X Community', and specifies cursor-paginated. It clearly distinguishes from sibling get_twitter_community_members by naming it as the alternative for full membership, so an agent can differentiate 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?

It states an explicit use case: 'identify the people who set the agenda in a community — the highest-leverage contacts for outreach or partnership.' It also names the alternative get_twitter_community_members for full membership, giving clear guidance on when to use which tool.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, covering safety. The description adds valuable behavioral context beyond annotations: it mentions cursor-based pagination and specifies the return content ('full tweet objects with engagement counts'). This goes beyond the bare safety profile, though it doesn't detail rate limits or error conditions.

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

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

The description is two sentences with no wasted words. The first sentence states the core action and pagination, the second provides usage guidance and return information. The key differentiator (specific community vs. all) is front-loaded.

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

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

For a read-only tool with an output schema, the description is nearly complete. It covers the scope (specific community), pagination, and return contents (engagement counts). The only minor gap is that it doesn't explicitly state how to obtain the community_id, but that is likely obvious or covered by sibling tools like get_twitter_community_info. Overall, an agent has enough to invoke it correctly.

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

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

Schema description coverage is 100%, so both parameters are already documented. The description's mention of 'cursor-paginated' reinforces the cursor parameter's purpose but adds no new syntax or format details. It doesn't clarify the community_id beyond what the schema already says. Baseline 3 is appropriate when the schema covers parameters fully.

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 ('Get') and resource ('posts published inside one specific X Community'), and immediately adds 'cursor-paginated' to convey the core behavior. It explicitly differentiates from the sibling tool get_twitter_community_tweets_all by noting the alternative is for searching across all communities when the target is unknown.

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

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

The description gives clear guidance: use this tool to read what a known community is discussing, and explicitly says to use get_twitter_community_tweets_all when the community is not known. This directly addresses when to use this tool vs. the alternative.

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 operation read-only, idempotent, and non-destructive. The description adds meaningful context beyond that: sorting behavior, cursor pagination, and that it returns full tweet objects. It does not mention rate limits or auth requirements, but those burdens are partially mitigated by the strong annotation profile.

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

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

The description is front-loaded with the core action and scoping, then usage rationale, return payload, and sibling alternatives. All sentences earn their place; there is no filler or irrelevant detail.

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

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

For a moderate-complexity search tool with an output schema and clear annotations, the description covers purpose, usage context, sorting, pagination, return payload, and alternative tools. An agent has enough information to call it correctly and avoid more specific sibling tools.

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 already documents query, cursor, and queryType. The description adds value by explaining that queryType maps to sort order ('Latest (default) or Top') and that search is keyword-based across communities. This helps an agent connect the parameters to the intended behavior more naturally.

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 ('Search'), resource ('posts across all X Communities'), and key modifiers ('by keyword', 'sorted by Latest or Top', 'cursor-paginated'). It clearly distinguishes this tool from the sibling `get_twitter_community_tweets` by emphasizing that it covers all communities, not one specific community.

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

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

The description explicitly says when to use this tool ('find topic-specific discussion inside communities rather than on the public timeline') and names alternatives for related use cases: `get_twitter_community_tweets` to read a specific community and `get_twitter_tweet_advanced_search` for public-timeline search. This leaves no ambiguity about 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: pagination behavior (20 per page, cursor-paginated) and the return shape (full user objects under `followers`). It does not mention rate limits or error cases, but the added pagination and response structure details go beyond the annotations.

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

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

Three sentences with no wasted words. The core purpose and pagination detail are front-loaded, followed by use-case context and a clear pointer to the sibling tool. Every sentence earns its place.

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

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

The description is complete for a read-only, cursor-paginated list tool. It explains the return structure (full user objects under `followers`), pagination, and the distinction from the sibling tool. The output schema exists, so return values are further documented. Minor gaps like rate limits or error handling are not critical given the annotations and output schema.

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

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

Schema description coverage is 100%, so the schema already documents both parameters (list_id and cursor). The description adds context about cursor-paginated usage but does not provide additional parameter-level detail beyond what the schema offers. Baseline 3 is appropriate since the schema carries the parameter documentation 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?

The description clearly states the tool lists accounts subscribing to an X List, with pagination details (20 per page, cursor-paginated). It explicitly distinguishes itself from get_twitter_list_members, which lists accounts included in the List, not subscribers. This makes the purpose unambiguous and differentiates it from the closest sibling.

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

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

The description provides explicit usage context: use it to gauge attention a curated list attracts and who cares about the topic. It also names the alternative tool (get_twitter_list_members) and the condition for choosing it (when you need accounts included in the List, not subscribers). This is clear when-to-use and when-not-to-use guidance.

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

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

Annotations already establish readOnly/openWorld/idempotent safety. The description adds valuable behavioral detail beyond that, such as '20 per page, cursor-paginated' and 'Returns full user objects under `members`.' This goes beyond what the annotations 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 well-organized sentences: the first states the operation and pagination, the second gives the use case, and the third routes to alternatives. There is no filler, and the most decision-relevant information comes first.

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

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

Given the output schema exists and annotations cover safety, this description is complete: it specifies pagination size, cursor mechanism, return field location, and sibling alternatives. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so both `list_id` and `cursor` are already documented. The description adds only mild contextual meaning for `cursor` via 'cursor-paginated' but does not explain parameter formats or defaults beyond the schema. A baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'List the accounts included in an X List.' It also distinguishes itself from nearby siblings like get_twitter_list_followers and get_twitter_list_tweets_timeline, so an agent can immediately tell what this tool uniquely does.

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

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

It explicitly states when to use this tool: 'Use this to extract a ready-made, human-curated cohort — someone else has already done the filtering.' It also names two alternatives with their distinct purposes, giving clear 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 establish read-only, idempotent, non-destructive behavior. The description adds meaningful behavioral detail beyond that: page size limit, cursor pagination, and the returning fields `has_next_page` and `next_cursor`. It does not discuss rate limits or auth, but the annotation coverage lowers the burden.

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

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

Three dense sentences with no wasted words: purpose and pagination, use case and rationale, return fields, and related sibling tool. Information is front-loaded and every sentence earns its place.

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

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

Given the output schema exists, annotations cover the safety profile, and the description covers pagination, return fields, and a related tool, nothing essential is missing for an agent 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 coverage is 100%, so the schema already documents both parameters. The description still adds value by explaining pagination behavior tied to the `cursor` parameter and clarifying that results are limited to 20 per page. It does not fully describe cursor format, but it supplements the schema meaningfully.

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 action and resource: 'Get the tweet timeline of an X List by listId'. It also adds concrete characteristics such as 'up to 20 per page, cursor-paginated', which makes the tool's scope clear and distinguishes it from related timeline/list tools.

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

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

The description gives clear when-to-use context: monitor a hand-curated set of accounts as a single feed, framing Lists as the cheapest way to track a fixed cohort. It names one alternative explicitly ('To see who is in the List use get_twitter_list_members'), though it does not explicitly contrast with alternatives like the single-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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context by stating the return shape ('Returns the object under `data`') and the kind of state information provided (scheduled/live/ended). This goes beyond the annotations without contradicting them.

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

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

Three sentences with no fluff. The core purpose is front-loaded, the use case is stated, and the return location is given. Every sentence earns its place.

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

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

For a single-parameter read-only tool with a rich output schema, the description is nearly complete. It covers what the tool does, when to use it, and where the result appears. It doesn't describe pagination or rate limits, but those are less critical for a single-ID detail lookup with an output schema 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 description coverage is 100%, so the schema already documents the single parameter (space_id). The description adds context about what the ID is used for ('by its space ID') but doesn't add format or source details beyond the schema. Baseline 3 is appropriate when the schema fully covers the parameter.

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

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

The description clearly states the tool retrieves details of an X Space by ID, listing the specific fields (title, state, host, participants, scheduling) and the use case (checking whether a Space is scheduled, live, or ended). It distinguishes itself from sibling tools by focusing on Space detail rather than tweets, users, or communities.

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

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

The description explicitly says when to use it: 'Use this to check whether a Space is scheduled, live, or ended, and who is hosting, before deciding to reference or attend it.' This provides clear context and a decision-oriented purpose, though it doesn't name a specific alternative tool to use instead.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is known. The description adds the return structure ('trend names and volumes under `trends`') and a usage flow, which goes beyond what annotations state. No contradictions.

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

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

The description is four sentences, each carrying relevant information: the core action, the use case, the return structure, and the next-step pointer. It is efficient and front-loaded, with no wasted words, though slightly longer than strictly 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?

For a simple read-only tool with an output schema, the description covers the essential usage, return format, and follow-up action. It doesn't mention pagination or rate limits, but those are not critical for a read-only, idempotent tool and are not expected given the 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 the schema already documents both `woeid` and `count` with descriptions and defaults. The description repeats the default count and WOEID reference but adds no new meaning beyond the schema, so a baseline of 3 is appropriate.

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

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

The description states a clear verb and resource: 'Get the trending topics for a location' and specifies the output under `trends`. It distinguishes itself from siblings by naming the follow-up tool `get_twitter_tweet_advanced_search` for searching posts, so an agent can tell this is about trends, not tweets.

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

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

It provides an explicit use case ('real-time read on what a specific market is talking about... useful for timing content or spotting emerging stories') and directs the agent to a specific alternative tool for the next step. This clearly routes the agent to the right tool for the job.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable functional behavior: cursor-paginated with has_next_page and next_cursor, and sorting by Latest or Top. It does not contradict annotations. It could have mentioned rate limits or error behavior, but those are not essential given the annotations.

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

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

The description is compact, front-loaded with the core purpose, then provides operator support, pagination behavior, and sibling routing. Every sentence earns its place, and the structure is logical and scannable.

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

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

Given the tool has an output schema and rich annotations, the description covers all necessary context: purpose, usage, operators, pagination, and alternatives. Nothing an agent needs to call it correctly is missing.

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

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

The schema covers 100% of parameters with descriptions, so the baseline is 3. The description enhances the query parameter by listing supported advanced operators (`from:`, `to:`, `since:`, `until:`, `min_faves:`, `-filter:replies`), and explains cursor pagination. This adds meaning beyond the generic schema description 'The query to search for.'

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

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

The description clearly states the tool's purpose: 'Search X posts by keyword or query with X's advanced search operators'. It explicitly identifies itself as the primary entry point for content research when no tweet IDs or handles exist, and differentiates from sibling tools like get_twitter_user_search and get_twitter_user_tweet_timeline by naming them directly.

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

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

The description provides explicit when-to-use guidance: 'This is the primary entry point for X content research when you do not yet have tweet IDs or handles.' It also gives clear alternatives: 'To search accounts rather than posts use get_twitter_user_search. To read one account's own posts use get_twitter_user_tweet_timeline.' No ambiguity remains.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds useful behavioral details beyond that: cursor-paginated results and return of full tweet objects with engagement counts. It does not contradict any annotation.

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

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

The description is three sentences with no filler. It front-loads the core action and pagination, then gives use case, return content, and alternatives. Each sentence contributes necessary 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 read-only two-parameter tool with an output schema and strong annotations, the description is complete: it explains purpose, when to use it, pagination, return contents, and sibling alternatives. Nothing needed for correct invocation is missing.

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

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

Schema coverage is 100% and both parameters have clear descriptions (tweetId and cursor). The description adds no additional parameter semantics beyond what the schema already provides, so the baseline of 3 is appropriate.

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

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

The description states a specific verb and resource: 'Get quote tweets of a given tweet', and defines them as 'posts that embedded it with added commentary'. It clearly distinguishes from sibling tools by naming direct replies and retweeters as different interaction types.

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 says when to use this tool ('to see how a post is being reframed or argued about') and names alternatives for other cases: direct replies via get_twitter_tweet_replies_v2 and retweets without comment via get_twitter_tweet_retweeters. This is strong 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?

Beyond the annotations that already mark it read-only, idempotent, and non-destructive, the description discloses cursor-based pagination, the default-only ordering constraint, and the return shape of full tweet objects with engagement counts. This gives the agent a clear behavioral model.

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

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

The description is compact and front-loaded: core action first, then use case, return behavior, and sibling routing. Every sentence contributes and none are 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?

With an output schema present and rich annotations covering safety, the description supplies everything else an agent needs: purpose, alternatives, pagination, ordering behavior, and return contents. Nothing important 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 input schema already covers both parameters fully at 100% coverage, so the baseline is 3. The description mentions cursor-paginated behavior and the default ordering but does not add deeper parameter-level detail beyond the schema.

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

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

The description names a specific verb and resource: 'Get the direct replies to a tweet'. It also distinguishes this tool from get_twitter_tweet_replies_v2 and get_twitter_tweet_thread_context, making its scope unmistakable.

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

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

The description explicitly says when to use this tool ('read the discussion under a post'), when to prefer a sibling instead ('Prefer get_twitter_tweet_replies_v2 when you want to control ordering'), and when to use another tool for the opposite direction ('To follow a conversation upward... use get_twitter_tweet_thread_context').

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context: 20 per page, cursor-paginated, and returns full tweet objects with engagement counts. However, it doesn't disclose details like rate limits or what happens with deleted/protected tweets, but the annotations carry the main safety burden.

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

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

Three sentences with no wasted words. The core purpose and key differentiator (sort order) are front-loaded, followed by pagination details and return value summary. Every sentence earns its place.

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

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

The description is complete for a read-only, cursor-paginated list tool. It covers the key behavioral details (page size, pagination, sort options, return type) and the output schema exists to explain return values. An agent has everything needed 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 schema already documents all three parameters. The description adds context about the default sort (Relevance) and the meaning of each sort option, but doesn't add significant meaning beyond the schema's own descriptions. Baseline 3 is appropriate.

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

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

The description clearly states the tool gets replies to a tweet with sort order control, and explicitly distinguishes it from the sibling get_twitter_tweet_replies. The verb 'Get' plus the resource 'replies to a tweet' and the specific sort options make the purpose unambiguous.

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

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

The description explicitly says to use this instead of get_twitter_tweet_replies whenever ordering matters, and explains when each sort option is appropriate (Likes for top responses, Latest for live threads). This is clear when-to-use guidance with a named alternative.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds value by specifying cursor-paginated behavior and clarifying the return type (user objects, not tweets). It also differentiates retweets from quotes, which is behavioral context not in the annotations. It doesn't cover rate limits or auth, but given the read-only nature and rich annotations, a 4 is appropriate.

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

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

Two sentences with no filler. The primary action and key distinction are front-loaded, and the alternative tool is mentioned concisely. Every word earns its place.

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

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

For a simple read-only list tool with an output schema, rich annotations, and a clear description that covers purpose, usage, and sibling differentiation, nothing critical is missing. The agent can call this correctly without further clarification.

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

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

Schema description coverage is 100%: both tweetId and cursor have descriptions. The description mentions cursor-paginated but does not add syntax or format details beyond the schema. Since the schema already documents both parameters adequately, the baseline of 3 is correct—the description adds marginal semantic value.

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

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

The description starts with a specific verb and resource: 'List the accounts that retweeted a given tweet.' It clearly states the output (user objects) and explicitly distinguishes from a sibling tool (get_twitter_tweet_quotes) by saying it returns retweeters, not quoted tweets. This makes the purpose unambiguous.

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

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

It provides a clear when-to-use context: 'Use this to map who amplified a message and how influential they are.' It also gives an explicit alternative for a different use case: 'For retweets that added commentary use get_twitter_tweet_quotes.' This tells the agent exactly when to choose this tool over a closely related one.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the read-only nature is covered structurally. The description adds useful behavioral context by enumerating the returned fields and noting that multiple IDs are accepted per call. It does not discuss edge cases like invalid IDs or rate limits, but those are minor for a read-only fetch with an output schema.

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

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

Three sentences with no filler: the first states the core function, the second adds contextual use case, the third names the fallback tool. Every sentence earns its place and the purpose is front-loaded.

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

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

For a tool with one required parameter and an output schema, the description covers input, return content, use case, and the alternative when not to use it. An agent has everything needed to decide whether to call it or choose the search sibling instead.

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

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

The schema only defines tweet_ids as an array of strings, with a terse property comment. The description adds that the IDs must be numeric and that multiple IDs can be supplied in one call, which clarifies how to construct the parameter. The lone schema wrinkle is 'comma-separated' vs the array type, but the description itself does not introduce that ambiguity.

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

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

The description opens with a specific verb and resource: 'Fetch the full content of specific tweets when you already know their numeric tweet IDs.' It also clearly distinguishes itself from get_twitter_tweet_advanced_search by framing this as the ID-based lookup versus search. No ambiguity about what this tool does.

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

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

It states exactly when to use it: when IDs are already known and you want to expand IDs from search, timelines, or replies into complete objects. It also gives an explicit alternative: 'If you do not have IDs yet, start with get_twitter_tweet_advanced_search.' This is clear when/when-not guidance.

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

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

Annotations already declare the tool read-only, idempotent, and non-destructive, so the description does not need to restate those. It adds useful behavioral detail by mentioning cursor-based pagination and the return fields `tweets`, `has_next_page`, and `next_cursor`, which goes 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?

The description is well-structured and front-loaded with the core purpose. Every sentence earns its place: what it does, when to use it, what it returns, and how it differs from a sibling tool. No fluff or repetition exists.

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

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

For a tool with only two parameters, a read-only/idempotent annotation set, and an output schema, the description covers everything needed to invoke it correctly: purpose, input type flexibility, usage context, pagination behavior, and the relevant alternative. No critical gap remains.

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 parameters are already well documented. The tool description confirms that `tweetId` can be a reply or original tweetable, but this mostly mirrors the schema's own description and adds little new semantic detail.

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: 'Reconstruct the conversation around a tweet.' It clarifies that the tool accepts either a reply or an original tweet and returns the 'surrounding thread,' which clearly differentiates it from sibling tools like get_twitter_tweet_replies_v2.

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

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

It explicitly states when to use the tool: 'Use this when a tweet lacks context on its own and you need the parent chain to interpret it correctly.' It also names the exact alternative for a different need, get_twitter_tweet_replies_v2, and distinguishes 'surrounding thread' from 'replies below a post.'

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, covering the safety profile. The description adds value by specifying the return structure (single profile object under data) and the types of signals it surfaces (country, verification details, username-change history), which goes beyond the annotations without contradicting them.

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

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

Two sentences with no wasted words. The purpose is front-loaded, followed by usage context and a clear alternative. Efficient and well-structured.

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

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

For a single-parameter read-only tool with a defined output schema (even if not shown here) and comprehensive annotations, the description covers everything needed: what it does, when to use it, what it returns, and how it differs from the sibling. Nothing essential 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% (the userName parameter is described as 'The screen name of the user'). The description adds a minor clarification with '@handle' implying format, but this is a small enhancement over the schema. Since the schema already covers the parameter adequately, a baseline of 3 is appropriate.

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

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

The description clearly states the tool retrieves the extended 'About this account' panel for an X user by handle, and explicitly distinguishes it from the standard profile tool get_twitter_user_info. This provides a specific verb, resource, and scope that uniquely identifies this tool among its many Twitter siblings.

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

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

The description gives explicit guidance: use for provenance and trust checks, and names the alternative (get_twitter_user_info) for standard profile data. It clearly states when to use this tool versus when not to, leaving no ambiguity for an agent.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, covering the safety profile. The description adds value by specifying the return format (array of user objects under `users`) and the input format distinction (numeric IDs vs handles), which are not in the annotations.

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

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

Three compact sentences, front-loaded with purpose, then usage context, then a critical clarification. Every sentence earns its place with zero redundancy.

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

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

For a single-parameter tool with an output schema and annotations covering safety, the description fully covers what an agent needs: how to format the input, what the output looks like, and when to choose this tool over its sibling. Nothing essential is missing.

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

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

The schema describes the parameter as 'Comma-separated user IDs', but the description adds critical semantic detail: it clarifies these are numeric IDs, not @handles, which is a common point of confusion. This goes beyond the schema description and justifies a higher score than the baseline 3.

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

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

States a specific verb (Resolve) and resource (many X users at once from numeric IDs), clearly distinguishing from get_twitter_user_info which looks up by handle. The purpose is unambiguous and actionable.

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 tells when to use: when a previous call gave IDs and you need full profiles in one request instead of looping. Also names the alternative (get_twitter_user_info) for handle lookups, providing a clear routing decision.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context beyond that: it checks both directions in one request, operates by @handle, and returns relationship flags under 'data', which helps the agent understand what the tool will do and what the response will contain.

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

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

The description is three sentences with no wasted words. The core purpose is front-loaded, the usage guidance names alternatives explicitly, and the return location is given succinctly. Every sentence contributes distinct value.

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

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

For a simple two-parameter read-only tool with annotations, fully documented parameters, an output schema, and sibling differentiation, the description covers everything an agent needs: what it does, when to use it, what it avoids, and where the result appears. Nothing important 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%, with each parameter described as a screen name. The description adds meaning by clarifying that source and target are X users identified by @handle and that the tool checks the relationship in both directions, which clarifies the roles of source_user_name and target_user_name beyond the raw 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?

The description states a specific verb and resource: 'Check whether one X user follows another, in both directions, by @handle.' It clearly distinguishes itself from siblings by stating that it is a single targeted lookup rather than paging through follower/following lists, and it names the exact question it answers: 'does A follow B, and does B follow A'.

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

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

The description explicitly tells the agent when to use this tool: 'Use this for a single targeted lookup instead of paging through get_twitter_user_followers or get_twitter_user_followings.' This directly names the alternatives and gives the condition for choosing this tool over them, leaving no inference required.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: pagination via has_next_page and next_cursor, default page size of 200, and the full user object fields returned. It does not mention rate limits or error handling, but that is not required given the annotation coverage and the read-only nature.

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 well-structured: it starts with the core action and ordering, then the return format and pagination, then use cases, and finally alternatives. Every sentence adds value, with no fluff. The key information is front-loaded, and the alternative references are concise yet complete.

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

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

Given the tool's moderate complexity (3 parameters, output schema present), the description covers purpose, usage, alternatives, return structure, and pagination. It even highlights a subtle trap (verified followers tool uses user_id, not handle). Nothing an agent needs to correctly call this tool is missing.

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

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

Schema description coverage is 100%, so all three parameters (cursor, pageSize, userName) have descriptions. The tool description reiterates that userName is a @handle and mentions the pageSize default and max, which are already in the schema. It does not add significant new meaning beyond the schema, so a baseline of 3 is appropriate.

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

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

The description clearly states the tool lists followers of a given X user identified by @handle, with ordering ('newest follower first') and pagination details. It explicitly differentiates from siblings by naming get_twitter_user_followings for the reverse direction and get_twitter_user_verified_followers for the verified subset, noting the latter's user_id requirement.

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

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

It provides explicit use cases ('audience analysis, mapping a competitor's follower base, or finding influential followers') and directs to alternatives with conditions (reverse direction → get_twitter_user_followings; verified subset → get_twitter_user_verified_followers, with a crucial caveat about handle vs. user_id). This leaves no ambiguity about when to use this tool versus 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering safety and idempotency. The description adds valuable behavioral context: pagination details (200 entries per page, has_next_page, next_cursor) and the conceptual rationale for using followings over followers. It does not contradict annotations.

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

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

The description is four sentences, each earning its place: purpose, pagination, use-case rationale, and alternatives. It front-loads the core function and keeps the alternative routing at the end, with zero redundancy.

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

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

With an output schema present and annotations covering the tool's safety profile, the description needn't detail every return field. It covers the main use case, pagination, and alternative tools. Missing details like error handling or rate limits are minor given the existing structured context.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description adds minor context like '@handle' and '200 entries per page', which reinforces the schema but does not significantly go beyond it. Baseline 3 is appropriate.

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

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

The description states a specific verb ('List') and resource ('accounts a given X user follows'), with clear identification via '@handle'. It also explicitly distinguishes itself from sibling tools (followers and check relationship), making the tool's purpose unambiguous.

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

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

It explicitly explains when to use this tool ('infer a user's interests, information sources, or professional network') and contrasts it with followers ('who someone follows is usually a stronger signal of intent'). It also points to the alternative for testing a single pair, giving clear 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 readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, covering safety. The description adds value by listing the specific returned fields (display name, bio, counts, verification, dates, etc.), which is useful context not in annotations.

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

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

The description is well-structured: it leads with the core purpose, gives usage context, lists returns, and then routes alternatives. Every sentence earns its place with no filler; the length is justified by the need to differentiate among siblings.

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

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

For a single-parameter read-only lookup with an output schema present, the description fully covers the call context, return fields, and alternatives. Nothing an agent needs to correctly invoke it 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% (the only parameter 'userName' is described as 'The screen name of the user'). The description reinforces this with '@handle (screen name)' but adds no substantive new meaning 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 ('Look up') and resource ('one X (Twitter) user's public profile by @handle'). It explicitly differentiates from three sibling tools by naming them and the conditions that select each, making its scope unambiguous.

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

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

Provides explicit when-to-use ('when you need to know who an account is — identity, reach, or credibility') and when-not-to-use conditions with named alternatives for numeric IDs, extended metadata, and posts. This fully routes the agent.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context beyond those: it discloses that the endpoint is cursor-paginated and specifies the response shape under `data` with `has_next_page` and `next_cursor`. This is useful for an agent deciding how to call and consume the tool, even though it does not mention rate limits or error conditions.

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

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

The description is two sentences with no filler. It front-loads the core purpose, immediately mentions the primary input choices, and ends with the valuable alternative guidance. Every sentence contributes to the agent's decision-making.

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

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

Given the tool's modest complexity (4 optional parameters), strong annotations, and full schema coverage, plus an output schema that documents the return structure, the description covers all needed context: usage trigger, alternative tool, pagination, and where the data lands. There is no missing information an agent would need 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 the parameter names and types are already documented. The description adds meaning by explaining the relationship between `userName` and `userId` (accepting either), and by framing `includeReplies` as optional in context. This goes beyond the raw schema, clarifying the intended usage of the parameters.

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

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

The description states a specific verb ('Get') and resource ('a user's most recent tweets'), and clearly distinguishes this tool from the sibling `get_twitter_user_tweet_timeline` by naming the exact alternative. It also clarifies the input types (userName or userId), leaving no ambiguity about what the tool does.

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

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

The description provides explicit guidance: use this tool when you have not resolved the handle to an ID, and use `get_twitter_user_tweet_timeline` when you already have the numeric ID and want the full profile-order timeline with parent-tweet expansion. This gives clear when-to-use and when-not-to-use instructions, naming the alternative directly.

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 and idempotent safety. The description adds pagination details (20 per page, has_next_page, next_cursor) and the unique time-window capability, which are valuable beyond the annotations. It doesn't mention rate limits or auth, but annotations cover the safety profile, so a 4 is appropriate.

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

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

Four sentences with zero waste. The core purpose is front-loaded, followed by a unique feature, usage guidance, return format, and an alternative — all in a tight, logical 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 an output schema present and annotations covering safety, the description provides all necessary operational context: pagination behavior, time window, usage scenarios, and a clear alternative. Nothing essential is missing for correct invocation.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds minor context (e.g., that sinceTime/untilTime bound the range and are Unix timestamps), but it doesn't go beyond the schema's own descriptions. Baseline 3 is correct.

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 precisely what it does: 'Get tweets that mention a given @handle' with a specific verb and resource. It also distinguishes from the sibling by naming get_twitter_user_tweet_timeline as the alternative for own posts, so an agent can tell them apart.

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: 'Use this for monitoring — brand mentions, inbound replies, reputation tracking' and gives the when-not with the alternative tool name. This is clear 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 signal read-only, idempotent, non-destructive behavior. The description adds meaningful behavioral context beyond that: it is cursor-paginated, returns full user objects under `users`, and searches accounts rather than posts. This enriches the agent's mental model without contradicting annotations.

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

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

The description is concise and front-loaded with the core action, then adds only high-value details: usage scenario, pagination/return format, and the sibling alternative. Every sentence earns its place with no filler or repetition.

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

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

For a two-parameter, read-only tool with full schema coverage, an output schema, and rich annotations, the description covers everything needed to invoke it correctly: when to use it, what to pass, how pagination works, and what comes back. No critical information is missing.

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

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

Schema description coverage is 100%, so the schema already documents both `query` and `cursor` clearly. The description reinforces the meaning of `query` with examples like 'a company name, a topic, a partial handle', which adds slight context, but it does not substantially elevate understanding beyond the schema.

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

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

The description states a specific action ('Search X user accounts by keyword') and a clear resource, and explicitly distinguishes itself from tweet search by saying 'This searches accounts, not posts'. It also names the sibling `get_twitter_tweet_advanced_search` as the alternative, making the tool's purpose unambiguous.

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

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

The description gives explicit use conditions: 'Use this when you know roughly who you are looking for... but not the exact @handle.' It also directly states when not to use it by pointing to `get_twitter_tweet_advanced_search` for tweet content searches, providing both positive and negative guidance.

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