Social Media Search API — Twitter, Instagram, Reddit, TikTok (XPOZ)

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

Annotations already declare idempotentHint=true and destructiveHint=false, so the agent knows repeated adds are safe. The description adds further useful context by disclosing that an error is returned when the plan limit is exceeded, which is valuable behavioral information 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: the first states the core purpose, the second details input structure, the third covers constraints and error behavior. No redundant content and front-loaded with the primary action.

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 and lack of output schema, the description sufficiently covers inputs, constraints, and error conditions. It does not describe the success return value, but for an 'add' operation this is not essential when no output schema exists.

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 individual fields (phrase, type, platform) and enums, but the description adds cross-field constraints (type-platform compatibility) that are not explicit in the schema. This gives the agent critical validation knowledge beyond the structured definitions.

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

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

Clearly states the verb 'Add' and the resource 'keywords/users to track', with explicit enumeration of accepted types and platforms. This distinguishes it strongly from sibling tools like getTrackedItems and removeTrackedItems.

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

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

Provides clear platform-specific constraints ('Subreddit is Reddit-only, hashtag is TikTok-only') and warns about plan limits. It implies the use case (adding tracked items) but does not explicitly name alternatives or exclusions, though sibling names make the distinction obvious.

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 'Gracefully stops operation at next checkpoint' and 'Returns confirmation', which add behavioral context beyond the annotations (idempotentHint, destructiveHint). It does not contradict the annotations; readOnlyHint=false aligns with a cancel operation. However, it omits details about error handling or what happens if the operation is already stopped.

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, with each sentence providing essential information: purpose, required parameter, behavior, return value, and verification alternative. There is no redundant or filler content, and it is front-loaded with the action.

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 cancel tool with one key required parameter, the description covers purpose, parameter requirement, behavior, and confirmation of completion. The absence of an output schema is acceptable because the description states 'Returns confirmation'. It also points to the relevant sibling for follow-up, making it sufficiently complete given the tool's complexity.

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

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

The schema covers 67% of parameters, but operationId's schema description is merely 'The operation ID' and provides little context. The tool description reinforces that operationId is required and refers to a running operation, adding some meaning. The optional feedback and _requestId are not explained in the description, but they are generic.

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 'Cancel running operation', which is a specific verb+resource that clearly states the action and target. This distinguishes it from the sibling tool checkOperationStatus, which is for verifying status, and from all the other sibling tools that perform different operations.

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

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

It explicitly says 'Use checkOperationStatus to verify cancellation completed', naming the alternative tool and indicating when to use it. It also implies this tool is for running operations ('running operation', 'at next checkpoint'), but does not explicitly state when not to use it, such as for completed or non-existent operations.

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 agent knows this is safe. The description adds meaningful context beyond annotations: that the key is not revealed, that authentication is required, and that it returns status/metadata. No contradictions with annotations.

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

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

The description is two short sentences, action-first, and every word adds value. It conveys purpose, a key behavior, a requirement, and return type with no filler.

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

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

For a simple tool with no output schema and safety annotations, the description is nearly complete. It covers purpose, a prerequisite, output, and a distinguishing behavior. Missing explicit contrast with getUserAccessKey, but the tool is simple enough that this is a minor gap.

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

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

Schema coverage is 50% (only 'feedback' has a description; '_requestId' is undocumented). The description doesn't discuss parameters, but the operation has no core parameters; the key is inferred from authentication. The note 'without revealing key' indirectly explains why no key parameter exists, but it doesn't add detail about the present 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 clearly states the verb ('Check') and resource ('access key status'), and adds 'without revealing key' to distinguish from tools that return the key itself. This is a specific, non-tautological statement that uniquely identifies the tool among siblings like getUserAccessKey.

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

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

The description mentions a required precondition ('authentication') but provides no explicit guidance on when to use this tool versus alternatives. The phrase 'without revealing key' implies a contrast with key-revealing operations but doesn't name alternatives or provide exclusion criteria.

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=true and destructiveHint=false annotations, the description adds critical behavioral context: the mandatory polling loop, exact 5-second waits, terminal statuses (success/no_data/error/cancelled), and the distinction between query and export operation responses. This fully compensates for the absence of 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?

Although lengthy, the description is well-structured with headings, numbered steps, and all-caps emphasis for critical rules. Every sentence adds essential protocol information, making the length justified for a complex async-polling tool. Front-loaded purpose ensures immediate comprehension.

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

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

Given the high complexity (async polling, two operation types, no output schema), the description covers all necessary context: return shapes for both operation types, status value enumeration, polling cadence, termination conditions, and even a migration note. No critical aspect is left undocumented.

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's description for operationId is minimal ('The operation ID'), but the tool description adds meaningful semantics by explaining the two operation ID formats (op_toolname_xxx vs op_datadump_xxx) and what each returns. It does not elaborate on feedback/_requestId, but those are generic and already adequately described in the schema where needed.

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: 'poll an async operation and retrieve its results or CSV download URL.' It clearly distinguishes this from sibling tools like cancelOperation and get* tools by focusing on status polling, while checkAccessKeyStatus is a different kind of status check.

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

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

It explicitly states when to use the tool: 'after any tool call made with responseType="paging" or responseType="csv"' and covers background job status checks, S3 link retrieval, and long-running query completion. It also includes a migration note directing users away from old tool names, serving as a strong alternative-guidance mechanism.

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, idempotentHint, destructiveHint=false), the description adds substantial behavioral context: default date range (6 months), query syntax rules (AND/OR/NOT, quoted phrases, @handles, field operators stripped, forward slashes treated as spaces), and trial access limitations. It also warns about the common error of using the wrong year for relative dates, which is valuable operational guidance.

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 long and covers many details: return type, query syntax, filters, default dates, year warning, use case, trial access, and signup instructions. While most sections earn their place, the trial access and signup paragraphs could be considered tangential to the core tool behavior. The structure uses clear separators (QUERY SYNTAX, IMPORTANT!!!!!) to aid readability.

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

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

Given the tool's complexity (8 parameters, rich query syntax, no output schema), the description is highly complete. It covers purpose, return value, query syntax, date filters, default behavior, use case, safety, and authentication. The absence of an output schema is compensated by explicitly stating the return type is an integer count. This provides an agent with sufficient information 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?

With 63% schema description coverage, the description adds significant meaning for the key parameters: it explains query syntax for 'phrase', date format for startDate/endDate (YYYY-MM-DD) with defaults, and the criticality of userPrompt for accuracy. However, internal parameters like _isTrial, _requestId, and _trialToken are not fully explained in the description (though trial token usage is mentioned), preventing a perfect score.

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

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

The description explicitly states 'Count tweets containing a specific phrase within a date range' and clarifies the return type ('Returns the total count of matching tweets (int) directly, or zero if none found'). This clearly distinguishes countTweets from sibling tools like getTwitterPostsByKeywords by focusing on counting rather than retrieving full tweet data.

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

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

The description provides clear usage context: 'Use for analytics and trend analysis without retrieving full tweet data.' This implies the tool is appropriate when only aggregate counts are needed, but it does not explicitly name alternative tools or state when not to use it. The contrast with retrieving full tweet data is implied rather than explicit.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds value by specifying the authentication requirement and the return structure (nested plan/billing/usage object), enriching beyond annotations without contradiction.

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

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

The description is concise and well-structured: the first sentence states the main purpose with detail, followed by two short sentences covering authentication and return format. Every sentence adds useful information with no redundancy.

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

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

It covers the essential aspects: what the tool returns, the auth requirement, and the nested object structure. Given the read-only nature and good annotations, the lack of error-handling details is acceptable for this simple use 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?

The only parameters are generic optional fields (feedback and _requestId) unrelated to the core operation. The description focuses on return content, and since there are no functional parameters, it does not need to elaborate further. Schema already covers the feedback 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's function: retrieving the authenticated user's account details including plan, billing, and usage specifics. It distinguishes itself from sibling tools (which focus on social media data) by targeting account metadata.

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 notes that authentication is required, which is a key prerequisite. It implies use when account details are needed, but there are no close alternatives to compare against, so no exclusions are necessary.

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 and idempotentHint, so the safety profile is covered. The description adds 'Required: authentication' and reveals the return structure (time-series buckets with subscriptionUsed, extraUsed, totalUsed, extraPurchased), going beyond the annotations. 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?

The description is four sentences with a clear structure: purpose, parameters, return shape, usage, and alternative. It is front-loaded and contains no filler or repetition.

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

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

With no output schema, the description explains the return format and fields, which is essential. It also covers authentication, usage scenarios, and an alternative tool, making the description fully self-contained for a read-only analytics tool.

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

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

Schema coverage is 75%, with range and granularity fully described. The description only restates these parameters with defaults, adding no new meaning beyond the schema. The additional parameters (feedback, _requestId) are not clarified in the description, but the schema's high coverage keeps this at 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 explicitly states the tool 'Get authenticated user's credits and export-rows usage over time' with a specific verb and resource. It also distinguishes itself from getAccountDetails by noting the alternative for current remaining balances, making its 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 clear guidance: 'Use for trend analysis and spotting usage spikes' and explicitly redirects users to getAccountDetails when they need current balances. This tells the agent exactly when to use this tool and when to choose a sibling tool.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description reinforces 'This is a safe, read-only tool'. It adds meaningful behavioral detail: fast mode caps at 300 results, paging/CSV are async, trial returns only 5 cached results and never triggers live fetching. 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?

Description is excessively long, including tangential trial-token acquisition steps, a 'CURRENT YEAR IS 2026' reminder, and feedback instructions not directly related to this tool. It is front-loaded with purpose and uses visual headers, but many sentences do not 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?

Despite having no output schema, the description fully covers return fields, all three response modes, pagination and CSV workflows, postId format requirements, date handling, and trial limitations. It gives an agent enough context to invoke the tool correctly and interpret results.

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

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

Description adds critical parameter context beyond schema: postId must be in 'strong_id format' with example and explicit warning against using only media_id; startDate/endDate should be omitted by default; responseType modes and limits are explained. Schema covers many parameters, so this is a strong complement, though it omits some schema-described internals like userPrompt.

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

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

Description opens with 'Get COMMENT CONTENT (text, likes) for an Instagram post', naming the exact resource and data. It differentiates from getInstagramPostInteractingUsers, explicitly saying 'NOT FOR USER PROFILES' and pointing to the correct sibling tool.

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

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

Provides clear use case ('Use for reading what people said'), explicit alternative ('use getInstagramPostInteractingUsers with interactionType="commenters" instead'), and concrete date-filter guidance ('OMIT startDate/endDate... ONLY pass if user explicitly requests'). Also explains when to use fast, paging, and CSV modes.

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 many behavioral traits beyond annotations: read-only nature, response modes, pagination flow, CSV export, trial limits, and cache fallback. However, it states '1000 users per page' for paging while the schema says '100/page,' an internal inconsistency that slightly undermines reliability despite overall strong transparency.

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

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

The description is long but well-structured with uppercase section headers and clear separation of fast/paging/trial concerns. It is front-loaded with the core purpose and avoids unnecessary filler, though the trial-access block could be considered tangential for tool selection and invocation.

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

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

For a complex tool with 14 parameters, no output schema, and multiple response modes, the description covers output profiles, pagination, optional fields, trial behavior, and cross-tool guidance. It provides sufficient context for an agent to select and invoke the tool correctly, including next steps like checkOperationStatus.

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?

Even though schema coverage is high, the description adds substantial semantic value: it explains limit capping (300 in fast mode), required postId format, field performance optimization, userPrompt's role in NLP optimization, and forceLatest's cost implications. This goes well beyond the schema descriptions.

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

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

The description opens with 'Get USER PROFILES of people who interacted with an Instagram post,' clearly identifying the verb, resource, and scope. It explicitly distinguishes this tool from getInstagramCommentsByPostId, and enumerates interaction types (commenters/likers), making the purpose unambiguous.

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

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

Provides explicit 'WHEN TO USE THIS TOOL' and 'WHEN TO USE getInstagramCommentsByPostId' sections, plus a 'NOT FOR COMMENT TEXT' warning. It also explains fast vs paging modes and trial limitations, giving strong guidance on when to choose this tool and how to obtain access.

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?

Description adds meaningful behavior beyond annotations: it explains the retrieval order ('First searches database, then external API for missing/stale data in parallel'), the omission of not-found IDs, trial limitations (5 cached results, no live fetching), and performance batching. It also confirms read-only safety consistent with readOnlyHint=true. 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 thorough and mostly front-loaded, but somewhat verbose with trial access instructions and multiple repetitions (e.g., 'Returns results directly' appears twice, performance emphasized in both the description and schema). Still, each major point is valuable; it could be tightened slightly.

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 8 parameters, no output schema, and a non-trivial data-fetching model, the description covers all critical aspects: request format, return shape, data-source behavior, performance, trial constraints, and parameter selection guidance. The absence of explanations for internal params (_isTrial, _requestId, _trialToken) is acceptable as they are implementation details.

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?

Despite moderate schema coverage (63%), the description significantly enhances parameter understanding. It explains the strong_id format with example, warns against using only media_id, details the fields parameter with defaults and available options, and clarifies forceLatest usage. This goes well beyond the raw 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 fetches multiple Instagram posts by IDs (1-100 per request), with explicit scope ('Get multiple Instagram posts by IDs'). It distinguishes from the sibling search tool: 'NOT for search - use getInstagramPostsByKeywords', and highlights it's more efficient than multiple single-ID calls.

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 ('Use when you have multiple exact post IDs'), when-not-to-use ('NOT for search'), and names the alternative tool (getInstagramPostsByKeywords). Also explains how to handle Instagram URLs by extracting shortcode and using keywords or asking for the ID, giving clear decision guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description reinforces this with 'safe, read-only tool.' It adds substantial behavioral context beyond annotations: database-first then external API fallback, auto API fallback for fresh data, async pagination via checkOperationStatus, CSV download polling, trial access limitations, and forceLatest cost warnings. 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 long but effectively structured with clear sections (response modes, query syntax, fields, trial access). While some repetition of the schema field list exists, the grouping adds value. Minor issues include a typo ('two response modes' instead of three) and an overly lengthy 'IMPORTANT!!!!!' note, but overall the length is justified given 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?

Despite having no output schema, the description covers all essential aspects: return fields (id, caption, username, createdAtDate), async patterns (operationId polling), CSV S3 link retrieval, trial limitations, and even a caution about current-year date miscalculation. This is complete enough for an agent to invoke correctly without external documentation.

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

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

With 67% schema coverage, the description significantly compensates. It adds meaning to responseType (three modes and their behaviors), limit (capped at 300 in fast mode, up to 500K in paging/CSV), query syntax (boolean operators, @handles, quoted phrases, forward slash handling), date filters (when to omit or pass), and fields (grouped into Core, Engagement, Media). This goes well beyond the schema descriptions.

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

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

The description clearly states 'Search Instagram posts by keywords' with a specific verb and resource, and goes further to distinguish from siblings by noting 'NOT for URL lookups or post ID lookups - use getInstagramPostsByIds instead.' It also explicitly describes the search scope (captions and video subtitles) and three response modes, making 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 provides explicit when-to-use guidance, including alternatives ('use getInstagramPostsByIds instead'), ideal use cases ('content analysis, hashtag trends, brand monitoring'), detailed response mode selection (FAST, PAGING, CSV), and date filter instructions ('OMIT startDate/endDate parameters by default'). This gives the agent clear decision-making criteria.

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

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

Adds extensive behavioral context beyond annotations: response mode limits, async polling, auto API fallback, trial restrictions, date filter warnings, and the 2026 year-check reminder. Read-only safety is reaffirmed and consistent with annotations. 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 excessively verbose, containing promotional trial signup information, redundant warnings, and an 'IMPORTANT!!!!!' section. It is front-loaded with the core purpose but lacks conciseness and contains a minor 'two vs three response modes' inconsistency.

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

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

For a complex tool with 16 parameters and no output schema, the description covers response modes, limits, default fields, date handling, and trial behavior. Some hidden params and authentication details beyond trial access are missing, but the essential usage is well documented.

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

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

The description adds meaningful semantics to key parameters (identifierType, responseType, limit, fields, startDate/endDate, tableName) beyond the schema. However, several internal params (_isTrial, _requestId, _trialToken) remain unexplained, and schema coverage is only 69%.

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 'Get posts from Instagram user by ID or username' with a specific verb, resource, and method of selection. It distinguishes itself from sibling tools like getInstagramPostsByKeywords by focusing on a single user. Minor inconsistency ('two response modes' while actually describing three) does not detract from overall clarity.

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

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

Provides clear context on when to use the tool ('Ideal for: engagement analysis, content trends, posting patterns') and guidance on choosing response modes (fast vs paging vs csv). It does not explicitly name alternative tools or exclusions, but the context is sufficient for 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 declare readOnlyHint and idempotentHint, and the description reinforces this with 'safe, read-only tool.' It goes beyond annotations by disclosing trial access behavior: 'Trial returns up to 5 cached results and never triggers live fetching,' which is unique behavioral information.

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

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

The description is quite long, with a large trial-access block that could be considered separate documentation. However, it is structured with clear sections and front-loads the main purpose. A more concise version could omit repeated safety phrasing.

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

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

For a tool with no output schema, the description lists the expected return fields ('userId, username, fullName...'), which is essential. It covers usage, alternatives, and trial limitations, making it reasonably complete despite omitting error handling.

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

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

The description covers identifierType semantics ('Use identifierType="id" for numeric user ID...') and explains the default and available fields for the fields parameter. Schema coverage is 67%, so the description adds some value but does not explain other parameters like userPrompt or forceLatest, which the schema already documents.

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

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

The description opens with a specific action: 'Get Instagram user profile by ID or username,' clearly naming the resource and method. It also distinguishes from sibling tool searchInstagramUsers for fuzzy searches, making the scope precise.

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 'Use ONLY when you have the precise username' and directs fuzzy search to searchInstagramUsers. Also notes optional fields for performance, giving clear when-to-use guidance.

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

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

Annotations already mark this as read-only, safe, and not destructive, but the description goes far beyond that: it explains auto API fallback, data freshness refresh (> 1 week), forceLatest bypassing cache at cost, trial limitations (only cached results, never live fetch), and the subtle totalRows vs totalDataCount distinction. This adds substantial behavioral insight without contradicting annotations.

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

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

The description is a long, dense wall of text with inline all-caps labels but no clear section breaks. It contains significant valuable content, but the trial-token API details, sign-up links, and extensive parameter examples make it overly verbose. It lacks the crisp structure of a well-organized description and would benefit from bullet points or headers.

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?

This is a complex tool with 14 parameters, two response modes, pagination, caching, trial limitations, and no output schema. The description covers all these aspects: fast vs paging behavior, polling via checkOperationStatus, data freshness, forceLatest trade-offs, trial behavior, and the crucial totalRows/totalDataCount caveat. It is exceptionally complete given the tool's complexity.

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

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

Schema coverage is high (79%), but the description enriches many parameters: it maps connectionType values to follower/following semantics, explains limit cap behavior in fast mode (300), details fields with examples, distinguishes fast/paging/CSV modes for responseType, warns about forceLatest cost/latency, and explains pageNumber/tableName/pagination semantics. This exceeds the schema's 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: 'Get Instagram user connections (followers or following).' It clearly distinguishes the two connection types via connectionType, making the tool's purpose unambiguous and differentiating it from other Instagram 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 context for when to use each responseType (fast vs paging), how to use limit, when to consider forceLatest, and critical guidelines about totalRows vs totalDataCount. It does not explicitly name alternative sibling tools, so it misses an explicit 'use this instead of X', but the decision context is well covered.

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

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

Beyond the readOnlyHint annotation, the description discloses paging behavior, caching semantics with forceLatest, trial limitations, query syntax quirks (e.g., forward-slashes as spaces, boolean operator requirements), and date handling pitfalls. It confirms read-only safety and clearly explains operational characteristics.

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 long but well-structured with clear section headers (USE CASE, RESPONSE MODES, QUERY SYNTAX, FILTERS, etc.) and front-loaded purpose. Some redundancy exists (e.g., query syntax repeated in schema and description), but the length is largely justified by tool 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 tool's complexity (15 parameters, multiple response modes, pagination, trial access, aggregation), the description is remarkably complete. It covers purpose, usage, query syntax, filters, fields, aggregates, pagination workflow, trial constraints, and expected return structure—all without an 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?

The description vastly enriches the parameter schema by explaining responseType modes in detail, listing available fields and aggregate fields, describing pagination parameter relationships, and clarifying query syntax nuances. It compensates for the 67% schema coverage and adds semantic depth beyond raw names.

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

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

The description clearly states 'Search for USERS who authored Instagram posts matching keywords' and emphasizes unique, deduplicated user profiles. This distinguishes it from sibling tools that search posts or platforms, and from user search tools without keyword-based post discovery.

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 a USE CASE and detailed guidance on response modes (fast, paging, csv) with explicit best-use scenarios. However, it does not explicitly state when to prefer this over sibling tools like searchInstagramUsers or getInstagramUsers, so exclusions are implied rather than 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, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral details: the database-then-API fallback with staleness threshold, trial-mode limits (database-only, no live fetching), and the effect of forceLatest. No contradiction with annotations, though some redundancy exists in "safe, read-only 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?

The description is front-loaded with a clear purpose, but it includes a lengthy trial-access paragraph that is tangential to the tool's core operation. Several details are useful, but the trial instructions (how to obtain a token, what headers to send, the sign-up link) could be condensed or moved to separate documentation. The structure is logical, but the length exceeds what is necessary.

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

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

With no output schema, the description appropriately summarizes the return shape: "single comment with id, body, author, parent ids, score, and timestamps." It also explains caching, forceLatest, trial constraints, and search exclusion. The main gap is not explaining _requestId or _isTrial directly, but these are minor and likely internal. Overall, the description provides a complete operational picture for a moderately complex 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?

The schema already describes commentId, fields, forceLatest, and feedback, but the description adds crucial context for the main parameter: the two accepted ID formats and how the ID is obtained (from sibling tools). It also clarifies the default set of fields and trial-token usage, which helps the agent understand parameters like _trialToken and _isTrial even though they are not individually detailed. Schema coverage is moderate (57%), but the description meaningfully supplements it.

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

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

The description opens with a specific verb and resource: "Get a single Reddit comment by its ID." It further clarifies acceptable ID formats, making the tool's scope unmistakable. It explicitly distinguishes this tool from sibling tools with "NOT for searching - use getRedditCommentsByKeywords for keyword 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 clearly states when to use this tool (when you have a Reddit comment ID) and explicitly names the alternative for keyword search. It also explains the data retrieval behavior (database first, then external API if missing/stale), which helps the agent decide when caching is acceptable versus when to use forceLatest.

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

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

Beyond the annotations (readOnlyHint=true, destructiveHint=false), the description adds essential behavioral context: 'Searches existing database records only' (no live fetch), async behavior for paging/csv modes with operationId polling, trial limitation of 5 cached results, and a warning about relative date calculations. These traits are critical for the agent to set expectations correctly and are not derivable from annotations alone.

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

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

The description is long but well-structured with clear section headers (FAST, PAGING, CSV, QUERY SYNTAX, FILTERS, TRIAL ACCESS). The detail is mostly necessary for correct invocation, but some portions, such as trial access instructions and the repeated 'IMPORTANT!!!!!' emphasis, could be tightened. Overall, it is efficiently organized for its 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?

Despite 14 parameters, 3 response modes, and no output schema, the description covers purpose, modes, query syntax, return fields, date handling, trial limits, and async polling. It states the default return fields (id, body, authorUsername, createdAtDate) and what to expect for paging and CSV modes. This is a complete operational guide for the tool.

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

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

With 64% schema description coverage, the description compensates extensively. It explains query syntax in depth (booleans, quoted phrases, parentheses, @handles, field operators stripped, forward slashes), clarifies how startDate/endDate should only be passed on explicit user request, and details how limit, fields, and responseType interact across modes. This adds significant meaning beyond the input schema fields.

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 'Search Reddit comments by keywords. Searches in comment body text,' specifying the action (search), resource (Reddit comments), and scope (comment body text). It distinguishes from sibling tools like getRedditPostsByKeywords and getRedditCommentById, 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?

Provides explicit guidance on when to use each response mode: FAST for direct results, PAGING for async pagination, CSV for full dataset download and code execution. It also describes ideal use cases (sentiment analysis, discussion trends) and advises on date filter usage ('OMIT startDate/endDate parameters by default'). However, it does not explicitly exclude alternatives or compare with sibling tools, though the mode guidance is strong.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds substantial behavioral context: 'First searches database, then external API if data is stale or missing', async behavior for paging/csv via operationId polling, trial mode returns only cached results, and auto API fallback. The 'safe, read-only tool' statement aligns with annotations. No contradiction detected.

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 long but highly structured with labeled sections (FAST, PAGING, CSV, QUERY SYNTAX, FILTERS, FIELDS, TRIAL ACCESS). It is front-loaded with core purpose and modes. While trial access and lengthy query syntax add bulk, they serve practical value for a complex 18-parameter tool; still, some trial/auth details could be trimmed without losing essential invocation guidance.

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

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

For a tool with no output schema, the description is exceptionally complete: it states default returned fields, response modes, async polling, filtering options, query syntax, authentication/trial constraints, and performance guidance. It covers all necessary operational aspects for an AI agent to invoke and interpret results, including the current-year date pitfall.

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 72%, but the description significantly enriches parameter understanding. It explains query syntax in detail (quoted phrases, boolean operators, parentheses, @handles, forward slashes), clarifies responseType semantics and limit caps, details the fields parameter with available field groups, and adds nuance for startDate/endDate and userPrompt. This goes well beyond the schema's field descriptions.

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

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

The description opens with 'Search Reddit posts by keywords with two response modes' and specifies that it searches 'post titles and selftext', giving a clear verb+resource+scope. It distinguishes from siblings (e.g., getRedditCommentsByKeywords, getRedditSubredditsByKeywords) by focusing on posts and keywords. It is specific and immediately understandable.

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 guidance: it names response modes (fast, paging, csv) and when to use them, states 'Ideal for: sentiment analysis, subreddit trends, community discussions', and explicitly warns about date handling ('ONLY pass these if user explicitly requests specific date range'). It also gives forceLatest sparingly and trial access context, making alternatives and boundaries 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?

The description goes well beyond the annotations (readOnlyHint, idempotentHint) by disclosing caching behavior ('First searches database... then external API if data is stale or missing'), paging side-effects (post data not returned on subsequent pages), and trial limitations (5 cached results, no live fetching). This adds substantial value beyond the structured hints.

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

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

The description is front-loaded with the core purpose and uses clear section headers (FAST, PAGING, RESPONSE STRUCTURE, etc.), making it navigable. However, it is quite verbose and partially redundant—the PAGING MODE DETAILS section repeats information from the earlier PAGING paragraph, and TRIAL ACCESS includes a full API request example that could be shortened.

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

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

With no output schema, the description compensates by explicitly stating the response shape: '{ results: { post: {...}, comments: [...] }, count, guidance }' and details paging operation polling. It also covers authentication via trial tokens, caching semantics, field selection, and safety, fully equipping an agent to use this complex 13-parameter tool correctly.

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

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

The schema already covers 77% of parameters, but the description enriches meaning by explaining interdependencies: limit's differing caps by mode, responseType determining synchronous vs async behavior, and the required pairing of pageNumber+tableName. It also clarifies performance implications of postFields/commentFields and warns about forceLatest cost.

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

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

The description opens with a specific verb+resource statement: 'Get Reddit post by ID with its comments.' This clearly identifies the tool's function and differentiates it from sibling tools like getRedditCommentById or getRedditPostsByKeywords by uniquely combining post ID lookup with comment retrieval.

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

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

The description provides clear operational guidance: it explains when to use 'fast' vs 'paging' response modes, how to paginate with tableName/pageNumber, and how to optimize fields. It does not explicitly contrast against alternative tools, but the specificity of 'by ID' and the inclusion of comments makes the intended use unambiguous.

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

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

Beyond the readOnly/openWorld/destructive annotations, the description discloses trial limits (5 cached results, 5-day validity), caching behavior (forceLatest trade-offs), async paging mechanics, query syntax quirks (boolean operators must have both sides, @handles, forward slashes become spaces), and the current-year warning for date calculations. It also explicitly states 'safe, read-only tool,' reinforcing annotations without contradiction.

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

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

The description is well-structured with headers (FAST, PAGING, QUERY SYNTAX, FILTERS, IMPORTANT, AGGREGATE FIELDS, TRIAL ACCESS) and front-loaded with the main purpose. It is long, but each section delivers useful operational detail. It does repeat some schema information (e.g., limit behavior, field defaults) which could be trimmed, but the overall structure makes it navigable.

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

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

For a complex 15-parameter tool with no output schema, this description is exceptionally complete. It covers all major operational facets: response modes, result limits, pagination, field selection, date filtering, query syntax, trial access, and the critical current-year date warning. It even provides authentication instructions for trial tokens, leaving little ambiguity about how to invoke the tool correctly.

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

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

Schema coverage is 80%, so schemas already document many parameters. The description adds meaning for query syntax not fully in the schema (e.g., AND/OR/NOT placement, @handles, field operators stripped), clarifies aggregation fields must be explicitly requested, and explains paging parameters (tableName/pageNumber) conventions. Some parameters like _isTrial and _trialToken remain unexplained in both schema and description, but overall the description adds substantial 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?

Description opens with a specific verb and resource: 'Search for SUBREDDITS where Reddit posts match keywords.' It clearly distinguishes this tool from siblings like getRedditPostsByKeywords (which returns posts) by stating that it returns unique, deduplicated subreddit profiles. This is a specific, well-scoped purpose.

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

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

The description gives clear context on when to use fast vs paging modes, when to use the limit parameter, and how filters/date handling work. However, it does not explicitly mention alternatives or when-not-to-use (e.g., 'if you need posts, use getRedditPostsByKeywords'). It lacks explicit sibling comparison but provides strong contextual usage guidance.

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

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

Annotations already mark it read-only, open-world, idempotent, and non-destructive; the description adds substantial behavior beyond this: automatic API fallback for fresh data, database-first lookup, async paging via operationId, trial token limits (5 cached results, no live fetching), and response structure. All claims align with annotations; 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 long but well structured with clear labels (FAST, PAGING, RESPONSE STRUCTURE, FIELD SELECTION, TRIAL ACCESS) and front-loaded purpose. Some parts, especially the trial access block, are verbose and could be condensed, but the organization makes the content scannable and each section 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 13 parameters, no output schema, and no sibling cross-reference, the description is fairly complete: it covers response modes, caching behavior, field selection, trial limits, and response shape. Minor gaps include lack of explicit CSV mode in the prose (left to the schema enum) and no mention of how stale data is determined, but these are not critical for a read-only tool.

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

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

Schema coverage is 77%, so most parameters are documented in the schema. The description adds meaningful semantics beyond the schema: fast mode caps at 300 posts, paging returns operationId for polling, field selection is for performance optimization, and pageNumber/tableName are required for subsequent pages. It does not describe every parameter, but the schema already covers them; the description complements rather than duplicates.

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

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

The description opens with a clear verb+resource: 'Get Reddit subreddit by name with its posts', naming the exact lookup method and result contents. It distinguishes itself from sibling search tools like getRedditSubredditsByKeywords and getRedditPostsByKeywords by emphasizing exact-name lookup with associated posts.

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 mode guidance: FAST vs PAGING, when to use limit, and when to use paging with checkOperationStatus. It explains the data-fetch strategy (database first, API fallback) and trial restrictions. However, it does not explicitly contrast this tool with sibling searches or state when NOT to use it, so it falls short of the full 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description's statement 'This is a safe, read-only tool' is redundant. However, the description adds concrete behavioral context beyond annotations: the trial access limitation (up to 5 cached results, never triggers live fetching) and the performance-oriented 'fields' parameter default. This gives the agent realistic expectations about response freshness and limits without contradicting 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 excessively long, primarily because it repeats a full enumeration of available fields that already exists in the schema's 'fields' parameter description. It also includes a large block of trial-access instructions (POST endpoint, request body, token validity) that is platform-level information rather than tool-specific guidance. The essential purpose and usage rules could be conveyed in two or three sentences. The first sentence is strong, but the subsequent detail is redundant and poorly structured, making it harder for an agent to quickly extract the key information.

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

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

Given that there is no output schema, the description does a good job of explaining the return structure (single user profile with id, username, karma metrics, account flags, profile details). It also covers the behavior of the 'fields' parameter and the trial restrictions, which are relevant for the agent to set expectations. Missing details like error handling or rate limits are not critical for basic tool selection and invocation. The completeness is adequate, though the redundancy with the schema reduces its efficiency.

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 63% of parameters with descriptions, including the key 'fields' parameter (with a full list of available fields, default value, and examples) and 'username' (with the no-prefix rule). The description repeats much of this information without adding new meaning. It does summarize the return format, which compensates for the absence of an output schema, but it does not explain the 'technical' parameters like `_isTrial`, `_requestId`, and `_trialToken` that are also undocumented in the schema. Thus, the description adds some value but does not fully compensate for the parameter documentation gaps.

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 'Get Reddit user profile by username,' which is a specific verb+resource pair that clearly differentiates this tool from sibling tools like getRedditUsersByKeywords (search by keywords) and getRedditSubredditWithPostsByName. It also states what the profile includes (karma breakdown, account status, profile info), providing a crisp one-line summary of the return value.

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 the important usage rule 'Use without u/ prefix' and notes trial constraints (5 cached results, no live fetching). However, it does not provide explicit when-to-use versus alternatives. With sibling tools such as getRedditUsersByKeywords and searchRedditUsers available, an agent would benefit from guidance like 'For searching by username fragments, use getRedditUsersByKeywords instead.' This guidance is implied but not stated, so the agent must infer the appropriate tool selection from the tool names.

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, and the description reinforces this: "This is a safe, read-only tool for analyzing searchable information." It adds substantial behavioral context beyond annotations: deduplication of users, async response modes with operation IDs, pagination cache/tableName mechanics, trial limitations (only 5 cached DB results, no live fetching), forceLatest cache-bypass warnings, and the "CURRENT YEAR IS 2026" relative-date pitfall warning. 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 information-dense but poorly structured — a wall of text with run-on sentences, ALL-CAPS emphasis ("IMPORTANT!!!!!", "CRITICAL FOR ACCURACY", "MUST BE EXPLICITLY REQUESTED"), and trial-access instructions mixed into tool behavior. It is front-loaded with purpose, and every sentence carries value, but the lack of clear section breaks and heavy over-capitalization make it harder to parse than it should be.

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 16 parameters, 3 response modes, async pagination, and no output schema, the description covers nearly every operational aspect: query syntax with boolean operators and quoting, field selection and aggregation requirements, filter semantics, response flow for all modes, pagination metadata (tableName, totalPages, totalRows), trial access limits, and date handling gotchas. It even warns about model year-miscalculation. This is exceptionally complete for a complex tool.

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

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

Schema coverage is high (81%), but the description adds significant meaning beyond the schema: it explains the responseType flow (fast vs paging vs csv, what to poll), the multi-call pagination protocol (first call omits tableName, subsequent pages require it, pageNumberEnd for bulk fetch), that aggregate fields MUST be explicitly requested in fields, the userPrompt accuracy requirement, and trial token authorization details. This far exceeds the baseline 3 for high schema coverage.

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

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

The first sentence states a specific verb+resource+scope: "Search for USERS who authored Reddit posts matching keywords." It clearly distinguishes from siblings like getRedditPostsByKeywords (returns posts) and getRedditUser (single user lookup). The USE CASE line reinforces the exact scenario this tool serves.

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 context on when to use the tool (find users who posted about topics), when to omit date filters ("OMIT by default, only use if user explicitly requests date range"), and which response mode fits which need ("Best for quick lookups", "Best for bulk export"). However, it does not explicitly name alternative sibling tools or state when NOT to use this tool in favor of another, so it stops short of a 5.

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

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

With annotations already marking readOnlyHint=true, destructiveHint=false, and openWorldHint=true, the description adds substantial behavioral context: response modes (fast, paging, csv), result limits, async polling via checkOperationStatus, caching behavior, auto API fallback, and trial access limitations. It also warns about forceLatest being 'USE SPARINGLY' and explains trial returns only cached results. This goes far beyond the annotations.

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

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

The description is quite long and includes details like full trial access instructions and an oddly placed 'CURRENT YEAR IS 2026' warning. While it is structured into clear sections (FAST, PAGING, CSV, Date filters, TRIAL ACCESS), it is not concise and contains some redundant or tangential content that could live elsewhere (e.g., auth docs).

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

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

Despite having no output schema and 15 parameters, the description covers response formats, paging, CSV download, date filter guidance, field selection, performance considerations, and trial limitations. It gives enough context for an agent to invoke the tool correctly in various scenarios, making it highly complete for its complexity.

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

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

Schema coverage is 67%, but the description enriches parameters by explaining responseType modes (fast/paging/csv), limit caps (300 fast, 500K export), field selection defaults, and the meaning of tableName/pageNumber in pagination. It also explains when to pass startDate/endDate and how to use the trial token. This adds value beyond the raw schema definitions.

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

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

The description opens with a specific verb and resource: 'Get COMMENT CONTENT (text, likes) for a Tiktok post.' It clearly distinguishes this tool from sibling comment tools like getInstagramCommentsByPostId or getTwitterPostComments by naming the platform and data type. It also states the use case: 'Use for reading what people said.'

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 ideal use cases: 'Ideal for: sentiment analysis, reading discussions, analyzing comment content, engagement patterns.' It also gives clear guidance on date filters: 'OMIT startDate/endDate by default. ONLY pass if user explicitly requests date range.' This helps the agent decide when to use the tool, though it does not explicitly compare it to alternative sibling tools.

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

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

Beyond annotations (readOnlyHint=true, destructiveHint=false), the description adds substantial behavioral context: response modes (fast, paging, csv), async polling for operations, caching behavior, trial limitations, and a warning about the current year to prevent date calculation errors. It explicitly confirms 'This is a safe, read-only tool' aligning 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 long but well-organized into logical sections (response modes, ideal use cases, exclusions, date handling, field options, trial access). It is front-loaded with the core purpose and mode explanation. Some redundancy exists (e.g., responseType is described both in description and schema), but the extra detail is useful.

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

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

Given the tool's complexity (15 params, 3 response modes, async operations, no output schema), the description covers all critical aspects: default return fields, pagination mechanics, CSV download flow, trial constraints, field selection, and date handling. It is thorough enough for an agent to understand 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 coverage is only 67%, but the description compensates well. It clarifies hashtag format (bare alphanumeric, no '#'), OR semantics, responseType modes, limit semantics, date format (YYYY-MM-DD), and field categories. It also explains undocumented params like startDate/endDate and _trialToken implicitly via trial access.

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 'Search Tiktok posts by hashtags' and specifies the resource (Tiktok posts) and the search field (hashtags column directly). It distinguishes from sibling tools by explicitly stating NOT for keyword/phrase search (use getTiktokPostsByKeywords) and NOT for URL/ID lookups (use getTiktokPostsByIds).

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: 'Ideal for: hashtag trend analysis, viral hashtag tracking, cross-hashtag content discovery.' It also gives clear exclusions and alternatives: 'NOT for keyword/phrase search in descriptions - use getTiktokPostsByKeywords instead' and 'NOT for URL or post ID lookups - use getTiktokPostsByIds instead.' It also advises when to omit date filters.

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 valuable context: it explains the internal caching mechanism (database first, then external API), the behavior of omitting not-found IDs, and the trial-specific limit (database-only results, never live fetch). This 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 bloated with a large trial-access block that is platform-wide and not specific to this tool. While the core function is front-loaded, the lengthy TRIAL ACCESS instructions and registration details detract from conciseness. A leaner tool-specific description would be more effective.

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

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

Despite having no output schema, the description covers the return structure (results array with fields) and key behavioral aspects like caching and trial limitations. It does not explain every parameter, but the schema provides those details. The description is sufficiently complete for an agent to invoke the tool correctly.

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

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

With schema coverage at 63%, the description compensates by explaining the 'fields' parameter with a concrete example and noting the default field set. It also clarifies the postIds range and result behavior. However, it doesn't mention forceLatest or userPrompt in the main description, leaving those to the schema. Overall, it adds meaning beyond the schema.

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

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

The description clearly states the tool's function: 'Get multiple Tiktok posts by IDs' with a specific 1-100 ID range. It differentiates from sibling tools by emphasizing ID-based lookup and the database-then-API fetch strategy, making it unambiguous when this tool is relevant.

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

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

The description implies usage for ID lookups and mentions performance optimization and trial limits, but it does not explicitly contrast with alternatives like getTiktokPostsByKeywords or getTiktokPostsByUser. There is no 'use this instead of X' guidance, so the context is implied rather than explicit.

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

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

Beyond the readOnlyHint=true annotation, the description adds rich behavioral details: three response modes and their async behavior (operationId, polling via checkOperationStatus), caching behavior (forceLatest, intelligent caching), trial limitations (up to 5 cached results, never live fetching), and the important warning about relative dates and the current year. This exceeds the annotation coverage.

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

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

The description is extremely long, covering almost every facet. While it is well-structured with clear topics (modes, query syntax, date filters, fields, trial access), the sheer length and repeated emphasis (IMPORTANT!!!!!, all-caps warnings) make it less concise than ideal. It could be trimmed without losing essential value, but the organization prevents it from being a wall of text.

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

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

Given the tool's complexity (15 params, no output schema), the description is remarkably complete: it states default return fields ('id, description, username, createdAtDate'), explains response modes and their outputs (operationId for async), covers field selection, trial limitations, and even provides authentication guidance. The agent has almost everything needed to invoke the tool correctly.

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

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

Schema coverage is 67%, but the description compensates heavily. It explains responseType modes in detail, the fields parameter categories (Core, Engagement, Media, Content), and query syntax (AND/OR/NOT, quotes, @handles, field operators, forward slashes). It also clarifies limit behavior across modes and date format expectations. This adds significant meaning beyond the raw 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 starts with a specific verb+resource: 'Search Tiktok posts by keywords with three response modes. Searches post descriptions and video transcripts.' It clearly distinguishes from siblings by explicitly stating 'NOT for URL lookups or post ID lookups - use getTiktokPostsByIds instead.'

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

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

The description provides explicit usage guidance: 'Ideal for: trend analysis, hashtag tracking, viral content discovery across Tiktok' and excludes alternative use cases ('NOT for URL lookups'). It also gives detailed date filter instructions and explains when to omit startDate/endDate. This clearly helps an agent decide when to use this tool vs alternatives.

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

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

Discloses detailed behavior: three response modes (fast/paging/csv), async operations via checkOperationStatus, default field returns, caching behavior, trial access limits, and safety ('This is a safe, read-only tool'). Aligns with and enriches annotations (readOnlyHint=true).

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 long but densely informative, with every section serving a purpose (response modes, exclusions, date filters, trial access). The IMPORTANT!!! warning about the current year is verbose but operationally useful. Slightly over-structured, but no wasted sentences.

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

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

Given no output schema and 15 parameters, the description covers the full workflow: obtaining soundId, choosing response mode, field selection, pagination, date handling, trial auth, and safety. It also gives explicit examples and warns about common pitfalls, making it self-sufficient for an agent.

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?

Adds significant context beyond the schema: explains responseType modes in plain language, clarifies limit caps and defaults, describes pagination parameters (tableName/pageNumber), and provides field grouping examples. Schema coverage is 67%, so description compensates for undocumented parameters reasonably well.

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

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

The description clearly states the tool's function: 'Get Tiktok posts that use a specific sound/music' with a specific verb and resource. It also distinguishes from siblings by explicitly saying 'NOT for keyword/phrase search - use getTiktokPostsByKeywords. NOT for hashtags - use getTiktokPostsByHashtags.'

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

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

Provides explicit when-to-use guidance: requires soundId from searchTiktokSounds, and states when NOT to use it with sibling alternatives. Also includes date filter best practices ('OMIT startDate/endDate by default. ONLY pass if user explicitly requests a date range').

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

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

The description goes well beyond the readOnlyHint/openWorldHint annotations, revealing trial access limits, cache-first then external API fallback behavior, async operationId polling, date filter caveats, and the current-year warning. It also explicitly calls the tool 'safe, read-only,' which aligns 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 long but well-structured, front-loading the core purpose and response modes before deeper details. The all-caps warnings are noisy but informative; every major section earns its place given 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?

With no output schema, the description thoroughly explains return defaults, response modes, polling requirements, CSV download flow, trial limitations, and caching behavior. It covers the high complexity of this 16-parameter tool effectively.

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

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

The description adds substantial meaning to key parameters: identifierType, responseType, limit, fields, startDate/endDate, pageNumber/tableName. It provides field categories and examples beyond the schema. Some schema-described parameters like forceLatest and pageNumberEnd are not covered in prose, but the schema already explains them well.

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

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

The description clearly states the tool retrieves posts from a TikTok user by ID or username, with three response modes. This specific verb+resource+identifier combination distinguishes it from sibling tools like getTiktokPostsByIds and getTiktokPostsByKeywords.

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

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

The description provides clear usage context: 'Ideal for: engagement analysis, content trends, viral video detection, processing thousands of posts.' It explains when to use each response mode and how to handle large datasets, though it does not explicitly name alternatives or state when not to use this tool.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds useful behavioral context about trial limitations: 'Trial returns up to 5 cached (database-only) results and never triggers live fetching.' It also states 'This is a safe, read-only tool' reinforcing the annotations. No contradiction, though it doesn't cover error scenarios or non-trial fetch behavior.

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

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

The description is front-loaded with purpose and usage, and the trial access block, while detailed, provides necessary auth steps. The 'Available fields' section is somewhat redundant with the schema but is concise. Overall it's efficient without excessive fluff.

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

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

For a tool with 9 parameters and no output schema, the description covers the core usage: identifier types, fields selection, return value ('Returns: single user profile'), and trial constraints. It omits details about forceLatest and userPrompt, but these are well documented in the schema. Given the complexity, this is reasonably complete.

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

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

Schema coverage is 67%, so the schema already documents most parameters. The description adds meaning for identifierType and fields, including default values and available fields, but this largely duplicates schema descriptions. It doesn't clarify auxiliary params like _isTrial, _trialToken, or _requestId, but those are self-explanatory. Baseline 3 is appropriate.

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

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

Description clearly states 'Get Tiktok user profile by ID or username' with a specific verb and resource. It explicitly distinguishes from searchTiktokUsers by noting 'For person names or fuzzy search, use searchTiktokUsers instead', which differentiates it from sibling tools.

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

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

Provides explicit when-to-use guidance: 'Use identifierType="id" for numeric user ID, identifierType="username" for username' and 'Use ONLY when you have the precise username.' It also names the alternative for fuzzy searches. Additionally, it explains when to use the fields parameter for performance.

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

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

Annotations declare readOnlyHint/destructiveHint, and the description reinforces this as a 'safe, read-only tool.' It goes beyond annotations by explaining trial restrictions (max 5 cached results, no live fetch), async operation mechanics, and the important current-year date correction. 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 long but well-organized into labeled sections (USE CASE, RESPONSE MODES, FILTERS, TRIAL ACCESS). Every section adds actionable detail. The 'IMPORTANT!!!!' year-reminder is somewhat tangential and adds no tool-specific value, but it is brief. Overall structured and effective despite verbosity.

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 15 parameters and no output schema, the description carries the burden of explaining return behavior. It covers all response modes, result limits, pagination/csv handling, field selection, trial limitations, and date filters. The description is comprehensive enough for an agent to invoke the tool correctly across scenarios.

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

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

The description adds substantial meaning beyond the schema: hashtags formatting ('do NOT include #'), OR semantics, default fields, aggregate fields requiring explicit request, responseType behavior with defaults and caps, trial token usage, and the critical userPrompt guidance. This far exceeds the schema's field descriptions and compensates for the 67% coverage gap.

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

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

The description opens with a specific verb+resource+scope: 'Search for USERS who authored Tiktok posts tagged with specific hashtags.' It clearly distinguishes from siblings by explicitly excluding keyword search and pointing to getTiktokUsersByKeywords. OR semantics and deduplication further clarify the tool's behavior.

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

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

Provides explicit use cases and response-mode selection guidance (fast vs paging vs csv), including when each is appropriate. It names the alternative tool for keyword searches and explains trial limitations. This gives an agent clear criteria for tool selection and 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?

Goes far beyond annotations by documenting response modes (fast/paging/csv), async pagination requirements, query syntax quirks (field operators stripped, slashes as spaces), and a critical warning about current year (2026) for relative dates. Reinforces read-only safety with a clear statement.

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

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

Front-loaded with purpose but extremely long and unstructured, mixing trial access, date warnings, and pagination details in a dense block. Contains redundant explanations and uses ALL CAPS, which hurts readability.

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 15 params and no output schema, this covers almost every aspect: response modes, pagination flow, query syntax, filters, field selection, trial access, and date accuracy. The only missing piece is error behavior, but the description is sufficient for correct invocation.

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

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

Description adds deep semantics for query, responseType, limit caps, fields defaults and aggregate fields, pagination parameters. However, _isTrial, _trialToken, and _requestId remain undocumented in both description and schema, leaving minor gaps.

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

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

Description uses specific verb 'Search' and resource 'USERS who authored Tiktok posts matching keywords', clearly distinguishing from sibling tools like getTiktokUsersByHashtags and searchTiktokUsers. The purpose is immediately 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?

Explicit USE CASE 'Find users who have posted content about specific topics' provides clear context for when to use. Does not name alternatives or exclusions, but the keyword-based focus is evident from the name and description.

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 by specifying the exact return fields (phrase, type, platform) and platform-specific type constraints (subreddit is Reddit-only, hashtag is TikTok-only), 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 two sentences, front-loaded with the core purpose, and every clause adds value. The return format and platform restrictions are conveyed with minimal words, making it easy to parse quickly.

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

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

For a simple read-only list tool with no output schema, the description adequately covers the return format and platform constraints. It does not mention potential edge cases (e.g., empty list, pagination), but given the low complexity and strong annotations, the description is sufficiently complete for an agent to invoke the tool correctly.

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

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

The input schema contains only generic internal parameters (_isTrial, feedback, _requestId, _trialToken) with no user-facing semantic parameters. Since there are no core parameters to document, the description's focus on return values is appropriate. The feedback parameter is already described in the schema, and the description adds clarity about the tool's output rather than 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 uses a specific verb+resource ('Get tracked keywords and users') and clearly states the return structure (phrase, type, platform). It differentiates from siblings like addTrackedItems and removeTrackedItems by focusing on reading the current tracking list, and the platform/type constraints further clarify scope.

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

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

The description implies this tool is for viewing tracked items, but it does not explicitly state when to use it versus alternatives (e.g., 'Use this to review what you're tracking before adding or removing items'). No exclusions or alternative tool references are provided, leaving usage somewhat implied.

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

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

Annotations already state readOnlyHint: true and destructiveHint: false, but the description adds rich, unannotated behavior: database-first lookup with API fallback for stale data, date filter omission rule, trial restrictions (up to 5 cached results, no live fetching), async polling via checkOperationStatus, and the explicit warning about the current year being 2026. It also reaffirms 'This is a safe, read-only tool,' aligning with annotations without contradiction.

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

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

The description is long but highly organized with uppercase section headers (FAST, PAGING, CSV, CODE EXECUTION) and front-loaded purpose. Every major section adds necessary detail for a complex tool, though the trial access instructions and current-year warning could arguably live in separate metadata. It avoids redundancy by referencing 'as described above,' but the overall length is high; still, it earns a 4 for structure and density.

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

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

Given the tool's complexity (14 parameters, three response modes, async operations), the description covers the full behavioral landscape: fast limits (300), paging (100/page, operationId polling), CSV S3 link, tableName reuse, field selection, date handling, trial constraints, and sibling differentiation. There is no output schema, so the description explains key return artifacts (operationId, tableName, S3 link). This is comprehensive for an agent operating in a real-world setting.

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 schema coverage is 71%, the description adds critical param guidance beyond the schema: 'OMIT startDate by default' and 'ONLY pass if user explicitly requests filtering,' the userPrompt field is marked 'CRITICAL FOR ACCURACY,' and the 'Current year is 2026' warning affects relative date calculations. It also clarifies responseType modes and paging semantics (pageNumber/tableName), adding value over the structured schema.

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

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

The description opens with a crisp statement, 'Get comments (replies) to specific post,' which clearly identifies the verb and resource. It distinguishes itself from siblings by explicitly stating 'NOT for quotes - use getTwitterPostQuotes,' and the sibling list includes related Twitter tools (getTwitterPostRetweets, getTwitterPostInteractingUsers), aiding differentiation. This exceeds a vague purpose statement.

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: 'Ideal for: sentiment analysis, discussion themes, community engagement analysis' and adds 'Use to analyze community response and discussion.' It also gives a clear exclusion: 'NOT for quotes - use getTwitterPostQuotes.' Mode selection guidance is extensive (fast vs paging vs csv), including when to use each and the recommendation to use code execution for csv mode.

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, and the description reinforces this with 'safe, read-only tool.' It also discloses many behavioral traits beyond annotations: fast mode caps at 300 results, automatic API fallback on stale data, data freshness checks (>1 week triggers refresh), forceLatest cost warning, async pagination details, CSV polling, and trial limitations. This is comprehensive and consistent with the annotations.

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

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

The description is well-structured with clear ALL-CAPS sections, but it is quite lengthy. It includes trial token instructions, signup links, and code execution suggestions that are not directly about invoking the tool, which dilutes conciseness. The front-loaded purpose and interaction types are good, but the overall size could 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 no output schema, the description thoroughly explains return behavior for each mode: fast returns up to 300 results, paging returns metadata like tableName/totalPages/totalRows, and CSV returns an operationId for polling. It also covers mode selection, data freshness, trial constraints, and parameter interdependencies, making it complete enough for reliable tool selection and invocation.

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

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

The description adds significant operational meaning to parameters: it explains pagination constraints ('Cannot pass pageNumber without tableName'), mode-specific limits, fields optimization, forceLatest trade-offs, and userPrompt importance. However, startDate and endDate are left completely undocumented in both schema and description, which is a minor gap given 16 total 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 clearly states the tool retrieves users who interacted with a Twitter post, specifying the three interaction types: commenters, quoters, and retweeters. This distinguishes it from sibling tools like getTwitterPostComments or getTwitterPostRetweets that return content or raw interactions rather than user lists.

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

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

The description provides explicit use cases ('Ideal for: audience analysis, engagement patterns, network graphs') and details when to choose fast, paging, or CSV modes. However, it does not explicitly contrast the tool with sibling tools such as getTwitterPostQuotes or getTwitterPostComments, so alternatives are not explicitly named.

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

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

Annotations declare readOnlyHint=true and destructiveHint=false, and the description reinforces 'This is a safe, read-only tool'. It adds beyond annotations: 'First searches database, then external API if data is stale (>10 days)', 'Auto API fallback for fresh data', async pagination/polling, trial limits (5 cached database-only results, no live fetching), and data freshness semantics. 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 lengthy and somewhat disorganized. It jumps from modes to code execution to ideal use cases to data source to a date/year warning to trial access. While the use of line breaks and capitalization helps, the 'IMPORTANT!!!!!: THE CURRENT YEAR IS 2026' block is a system-level reminder rather than tool-specific and adds noise. Front-loaded first sentence is clear, but overall conciseness suffers due to redundancy and tangential 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 complex tool with 14 parameters, multiple response modes, async operations, and no output schema, the description covers all major aspects: mode selection, parameter behavior, data freshness, trial vs full access, pagination, field customization, and use cases. It also references sibling tools where relevant. Its completeness is exceptional.

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 71%, but the description adds substantial meaning: it details the `fields` parameter with full field lists and examples, explains `responseType` modes with async behavior, clarifies `limit` caps across modes, warns on `forceLatest` ('USE SPARINGLY'), and stresses `userPrompt` as 'CRITICAL FOR ACCURACY'. It also gives guidance on `startDate` ('OMIT by default') and pagination params (`tableName`, `pageNumber`).

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 'Get quote posts of specific post', a specific verb+resource statement. It clearly distinguishes from siblings by explicitly stating 'NOT for retweets - use getTwitterPostRetweets' and framing it as analyzing commentary on a 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?

The description provides explicit when-to-use guidance: 'Ideal for: sentiment analysis on reactions, commentary patterns, viral spread analysis' and 'Use to analyze commentary on post. NOT for retweets - use getTwitterPostRetweets'. It also explains mode selection (fast/paging/csv) and when to use each, plus date filter usage and trial vs full access.

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 crucial behavioral details: 'Database-only' search, result limits (up to 300 in fast mode), async pagination via operationId, trial limits (up to 5 cached results), and a warning about year miscalculation. No contradictions with annotations; value is added beyond structured fields.

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

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

The description is long but well-structured and front-loaded with the core purpose. Every section (modes, date filter, current year warning, trial access) serves a practical purpose for an AI agent. Though verbose, it avoids fluff and organizes information logically.

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

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

Given the tool's complexity (14 params, multiple modes, no output schema), the description covers essential aspects: result limits, pagination mechanics, operationId polling, and trial constraints. It does not provide detailed response JSON structure, but the description is sufficiently complete for an agent to invoke correctly.

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

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

Schema coverage is 64%, and the description compensates for gaps. It clarifies postId requirements ('Do NOT pass tweet text, URLs, or usernames'), explains limit caps by mode, and describes startDate omission rules. It also highlights the 'fields' parameter for performance. This adds significant meaning beyond the raw 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's function: 'Get retweets of specific post.' It further distinguishes itself from siblings by explicitly noting 'NOT for quotes - use getTwitterPostQuotes.' The verb-resource pair is specific and 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 usage context: 'Use to analyze post amplification patterns.' It also gives clear alternatives ('NOT for quotes - use getTwitterPostQuotes'), mode selection guidance (fast vs paging), and critical date filter rules ('OMIT startDate by default... ONLY pass if user explicitly requests filtering'). This is exemplary 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?

Discloses read-only safety, database-then-API fallback, async polling via checkOperationStatus, trial limitations, and the current-year date pitfall. Consistent with annotations (readOnlyHint=true, destructiveHint=false) and adds substantial behavioral detail beyond them.

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

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

Long but well-organized into clear blocks (modes, date filters, fields, trial). Some redundancy with schema field lists, but front-loaded purpose and minimal 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 15 params, no output schema, async modes, and trial auth flow, the description covers essentially all operational aspects: modes, pagination, fields, date handling, polling, trial token, and safety. The only minor gap is not describing exact polling mechanics for checkOperationStatus, but it correctly points to that sibling 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?

Adds meaning beyond schema descriptions: explains responseType modes in detail, FAST cap of 300, date parameter handling with year 2026 warning, and field selection purpose. While schema covers 67% of params, description fills gaps and gives user-facing context like trial restrictions and limit max.

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

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

Description opens with 'Get posts from author by username with multiple response modes' — a specific verb, resource, and scope that clearly distinguishes from sibling tools like getTwitterPostsByKeywords or getTwitterUsers. The title 'Twitter: Get Posts by Author' reinforces the tool's specific purpose.

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

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

Provides explicit mode selection guidance (FAST, PAGING, CSV), date filter instructions, and code-execution recommendation for large analyses. Does not explicitly name alternative tools for when this tool is inappropriate, but the context of 'by author' and sibling names make that implicit.

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, idempotentHint, destructiveHint=false), the description reveals key behaviors: 'Returns only found tweets, omitting not-found IDs', 'First searches database, then external API for missing/stale data in parallel', and trial-specific limitations (up to 5 cached results, never triggers live fetching). This substantially enriches the agent's understanding of side effects and data freshness.

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 core purpose and usage, but becomes lengthy with trial access instructions, signup URLs, and a redundant 'safe, read-only tool' assertion. While it uses section-like uppercase labels (PERFORMANCE, TRIAL ACCESS), it's a single dense paragraph. It earns points for structure but loses for over-specification.

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 8 parameters and no output schema, the description provides a useful return format ('results array with id, text, authorId, createdAt, metrics...'), data-source behavior, performance notes, and trial constraints. It misses details like error handling and rate limits, but covers the essential context for an agent to call the tool effectively.

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

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

The description adds a small amount of parameter-level meaning: it illustrates the 'fields' parameter with an example array (["id", "text", "retweetCount"]) and notes the 1-100 ID limit. However, most parameter descriptions live in the schema (63% coverage), and the description does not compensate for the remaining undocumented parameters (_isTrial, _requestId, _trialToken) beyond what the schema already explains. It adds marginal value over the schema.

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

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

The description opens with a specific verb+resource: 'Get multiple Twitter posts by numeric IDs (1-100 IDs per request).' It clearly states the tool's scope and explicitly distinguishes it from search with 'NOT for search - use getTwitterPostsByKeywords', effectively differentiating it from sibling 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 explicit when-to-use guidance: 'Use when you have multiple exact post IDs' and contrasts with the alternative: 'NOT for search - use getTwitterPostsByKeywords.' It also provides context on efficiency ('Much more efficient than multiple single-ID calls') and the caching/API fallback strategy, which helps an agent decide when to invoke 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?

Although annotations already declare readOnlyHint and destructiveHint, the description adds substantial behavioral context: it explains the fast/paging/CSV modes, database-first search with external API fallback, the trial limitation to cached results, and the 'IMPORTANT' note about the current year to avoid date errors. It also explicitly states 'This is a safe, read-only tool', aligning with annotations without contradiction.

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

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

The description is extremely long and repeats much of what is already in the schema, such as query syntax, field lists, and responseType details. While it is front-loaded with core functionality, the extensive length and redundancy violate the 'every sentence earns its place' principle. Overly verbose, covering trial instructions and current-year reminders that could be moved to a separate guidance section.

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 21 parameters, no output schema, and three distinct response modes, the description is largely complete: it explains default return fields, async operationId polling, pagination pages, CSV download, field categories, filters, sorting, and date handling. It lacks a structured return object example, but given the absence of an output schema, it covers most critical operational details.

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 71%, and the description adds meaningful semantics for parameters like query syntax (quoted phrases, boolean operators, parentheses), responseType modes, sortBy, date format (YYYY-MM-DD), and field selection. It also mentions uncovered parameters like language and countryCode in the filter list. However, it does not explain underscore-prefixed parameters (_isTrial, _requestId, _trialToken), so it doesn't fully compensate for the 29% gap.

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

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

The description opens with 'Search posts by keywords' and immediately details the available response modes (fast, paging, CSV), making the tool's primary purpose explicit. It also differentiates from the sibling tool getTwitterPostsByIds by stating 'NOT for URL lookups - use getTwitterPostsByIds', which removes ambiguity.

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

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

The description goes beyond a simple 'when to use' by explicitly naming the alternative tool for URL lookups and providing use-case guidance ('Ideal for: sentiment analysis, trend detection, content analysis across thousands of posts'). It also explains when to choose each responseType, when to pass startDate/endDate, and when to use the trial access, covering both context and exclusions.

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

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

The description adds meaningful context beyond the annotations: it declares the tool safe and read-only (consistent with readOnlyHint=true), explains trial access limitations (up to 5 cached results, no live fetching), and warns about the correct field name "tweetCount". However, the "Returns" section lists snake_case fields like followers_count and authenticity_score that do not match the available fields list, creating potential confusion about the actual output structure.

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 quite long but is logically organized into purpose, usage, fields, returns, and trial access. However, it includes the full field list which is already present in the input schema, and the trial access instructions could be considered tangential to the tool's core function. Some redundancy and verbose blocks reduce conciseness.

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

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

Given no output schema, the description attempts to explain the return shape, but the mismatch between listed return fields and the available fields is a major gap in completeness. It also omits mention of several parameters like userPrompt, forceLatest, _trialToken, and feedback, which are present in the schema but not addressed in the description. For a tool with 9 parameters, the description covers the most critical ones but lacks thorough contextual coverage.

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

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

The description adds substantial meaning beyond the schema: it explains how to choose identifierType, gives concrete examples of valid usernames, enumerates the complete available fields for the fields parameter, clarifies the default value, and warns about the tweetCount vs statusesCount naming. This compensates well for the 67% schema description coverage.

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

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

The description opens with a clear verb and resource: "Get Twitter user profile by ID or username." It also distinguishes itself from the sibling tool searchTwitterUsers by specifying when to use that alternative, and the identifierType options are explicitly stated.

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

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

Explicit usage guidance is provided: "Use ONLY when you have the precise username" and "For person names or fuzzy search, use searchTwitterUsers instead." It also explains the default fields and the performance-oriented optional fields parameter, giving the agent clear criteria for 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?

The description discloses numerous non-obvious behaviors: automatic data age checks (>1 week refresh), forceLatest latency/cost implications, the totalRows vs totalDataCount partial-data caveat, async operationId polling, and trial limitations (cached-only, max 5 results). These go well beyond the readOnlyHint annotation and set clear 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?

While the description is organized into sections with headings, it is extremely long (over 400 words) and includes peripheral information like trial signup instructions and a feedback field. The core info is front-loaded, but it could be tightened without losing 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 the tool's complexity (3 response modes, async operations, caching) and the absence of an output schema, the description is remarkably complete. It explains pagination mechanics, CSV downloads, data freshness, partial data interpretation, and even code execution next steps. An agent can safely invoke this tool after reading the description.

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

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

The description elaborates on the most important parameters: connectionType semantics, responseType modes, limit caps, fields performance defaults, pageNumber/tableName paging, and forceLatest cost warning. This substantially enriches the 79% schema coverage, especially for the responseType and fields 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 opening sentence states the exact resource and action: getting Twitter user connections (followers or following). It goes beyond the title by clarifying the connectionType parameter and distinguishing itself from other Twitter tools like getTwitterUser or getTwitterUsers.

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

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

Provides explicit guidance on when to use each response mode (FAST/PAGING/CSV) and ideal use cases (network analysis, audience demographics). It also instructs on forceLatest usage ('USE SPARINGLY') and trial access, but does not formally name alternative tools or when-not conditions.

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