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

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

Annotations already signal the tool is not read-only, not destructive, and idempotent. The description adds a useful behavioral detail—error on plan-limit exceedance—and platform/type validation rules. However, it does not describe the success return format or what happens when duplicate items are added, though the idempotentHint does partially mitigate duplication concerns.

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 only three short sentences, each adding value: the primary action, the accepted shape, and the most relevant failure mode. It is front-loaded with the verb and subject, and contains no filler or tautological content.

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

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

The tool is a simple add operation with a small schema, and annotations cover mutability and idempotency. The description supplies the core semantics and the plan-limit error. Yet with no output schema, the description would be stronger if it mentioned success information (e.g., what is returned on a successful add, whether item creation is reflected immediately), so the agent can confirm the call succeeded.

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 low (40%), and the description helps by surfacing the key enum values and platform/type constraints in a compact form. However, it mostly restates what the nested schema already provides and omits any explanation of _isTrial, _requestId, and _trialToken, which are not otherwise described. Still, the required items parameter gets sufficient treatment.

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 begins with a clear verb and resource: 'Add keywords/users to track.' It expands on scope by listing the exact item types and platforms, making the operation unambiguous. The name and description clearly distinguish it from getTrackedItems and removeTrackedItems, which are the only close siblings.

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

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

The description implies the intended use by stating it adds items, and it gives explicit platform restrictions: 'Subreddit is Reddit-only, hashtag is TikTok-only.' It does not explicitly say 'use getTrackedItems to view current items' or 'use removeTrackedItems to delete', but these are clear from naming and context. Slight gap is the lack of when-not-to-use or alternatives guidance beyond naming.

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 (idempotentHint=true, destructiveHint=false), the description adds genuine behavioral context by stating it gracefully stops operation at next checkpoint, implying a non-immediate, non-destructive cancellation, and returns confirmation. These details align with the annotations rather than contradicting them.

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

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

The five short sentences are aggressively front-loaded: purpose, required input, mechanism, return, and follow-up all appear in order with zero filler. Every clause earns its place.

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

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

For a simple async cancellation tool, the description covers the essential contract: what is required, how the stop behaves (at next checkpoint), what is returned (confirmation), and what to do next. With no output schema, the exact shape of the confirmation is still vague, and error cases (such as operation not found) are unaddressed, but nothing critical blocks 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?

The schema already documents operationId (The operation ID) and the feedback field in detail, giving roughly 67% coverage. The description restates that operationId is required but adds little semantic meaning, and _requestId remains unexplained.

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?

Cancel running operation states a specific verb (cancel) and resource (a running operation) in a single clear clause. The closing sentence explicitly routes the agent to checkOperationStatus, distinguishing this tool from its closest sibling without opening any schemas.

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

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

The description names the required operationId as a precondition and gives a concrete working flow: cancel, then use checkOperationStatus to verify. However, it gives no explicit when-not-to-use guidance, such as avoiding cancelling already-completed 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 base safety profile is covered. The description adds meaningful behavioral context beyond annotations: the key is never revealed, and authentication is required. This goes beyond what the annotations state and is relevant for an agent deciding whether this operation is safe and how it behaves.

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 compact two-sentence structure: one sentence for the operation and key constraint, one for requirements and return values. Every element earns its place and the core behavioral point is front-loaded.

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

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

For a tool with no required parameters and no output schema, the description covers the essentials: what it does, the key security constraint, the authentication prerequisite, and the high-level return contents. The only minor gap is that 'metadata' and 'status' are not elaborated, so an agent may not know exactly what statuses/metadata to expect; still, the description is complete enough 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 description coverage is 50%, with only the generic feedback field documented and _requestId left undocumented. The tool description itself adds no parameter-level meaning. However, both parameters are generic platform plumbing rather than tool-specific operation parameters, so the description's silence is not very costly. This is a marginal case and the extra context is not 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 clearly identifies the action ('check'), the resource ('access key'), and the specific outcome ('without revealing key'). The 'without revealing key' clause distinguishes it from the sibling tool getUserAccessKey, making it a genuine 5 rather than merely a standard read operation.

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

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

The description implies when to use the tool: whenever an agent needs access key status without exposing the key itself. It also states the prerequisite of authentication. However, it does not explicitly state what conditions would favor this tool over the closely related getUserAccessKey or other sibling tools, so usage guidance is implied rather than clearly articulated.

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 provide the safety profile (readOnlyHint=true, not destructive), but the description adds substantial behavioral context: the exact 5-second wait polling loop, the mandatory continuation until success/no_data/error/cancelled, the wire-level ResponseStatus values, and the distinct return contracts for queries vs exports. This is exactly the kind of non-obvious behavior an agent needs disclosed.

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

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

The description is dense but every section earns its place: purpose, usage trigger, type dispatch, polling loop, return contract. It is front-loaded with the core action and the strongest guidance first. Slight redundancy exists — "DO NOT stop until..." and "Only stop when operation is finished" restate the same rule — so it's not perfectly tight.

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 fully covers the return contract for both operation types (paginated results + dataDumpExportOperationId vs downloadUrl/fileName/totalRows). It also resolved the missing pieces not present in annotations or schema: poll cadence, termination conditions, status vocabulary, and how to distinguish query operations from export operations. Nothing an agent needs to call it correctly is missing.

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

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

The schema only documents operationId as "The operation ID" (and _requestId not at all, coverage 67%), so the description carries the semantic load: it explains that operationId comes from responseType="paging"/"csv" calls, distinguishes the two ID formats, and states it is required. The feedback and _requestId parameters are peripheral to operation, so the mild incompleteness of coverage on them is not costly.

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 names a specific verb-resource pair — "poll an async operation and retrieve its results or CSV download URL" — which is unambiguous and distinct from siblings like cancelOperation and checkAccessKeyStatus. The description goes further by explaining the two operation types (op_toolname_xxx vs op_datadump_xxx), making the tool's scope fully concrete.

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, actionable when-to guidance: "Use this after any tool call made with responseType=paging or responseType=csv", plus background job status checks and S3 link retrieval. It does not name direct alternatives/exclusions — notably cancelOperation is never mentioned as when NOT to use this — so it stops short of a 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, openWorldHint, idempotentHint, and destructiveHint=false. The description adds meaningful behavior beyond those: returns an int directly, returns zero when no matches, applies date defaults (startDate=6 months ago), treats slashes as spaces, strips field operators, and warns about year miscalculation for relative dates. 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 organized: purpose and return behavior are front-loaded, followed by query syntax, date filters, defaults, and use case. The query-syntax block is dense but earns its place given the complexity of the phrase parameter. The 'IMPORTANT!!!!!' year warning is verbose but serves a real accuracy purpose.

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

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

The description covers return type, zero-case behavior, query syntax, date range, defaults, and safety, which is sufficient for a read-only count tool with no output schema. Minor gaps remain: no explicit mention of error behavior, rate limits, or named sibling alternatives, but nothing critical is missing for correct invocation.

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

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

Schema coverage is 63%, but the description substantially enriches the key 'phrase' parameter with detailed query syntax: boolean operators, quoted phrases, handles, parenthesized groups, and field-operator stripping. It also clarifies date format and defaults for startDate/endDate. Internal metadata parameters like feedback and userPrompt are already described in the schema, so the description does not need to repeat them.

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

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

The description states a specific verb and resource: 'Count tweets containing a specific phrase within a date range.' It also clarifies the return type and distinguishes itself from sibling Twitter retrieval tools by emphasizing analytics/trend analysis 'without 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 gives clear usage context: 'Use for analytics and trend analysis without retrieving full tweet data,' which implies when to choose this tool over post-retrieval alternatives. However, it does not explicitly name sibling tools or list specific when-not-to-use conditions, so it stops short of full alternative routing.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is established without the description. The description adds genuine context beyond those hints: authentication is a precondition, the billing node is null for Free-plan users, and the response is a nested plan/billing/usage object. No statement contradicts the annotations.

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

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

Roughly three sentences pack the primary verb and scope, an itemized breakdown of return contents, a null-case note, an authentication requirement, and the overall return shape. There is no filler, and the main action is front-loaded before the detail clauses.

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 carries the burden of describing the return value and does so thoroughly, including the Free-plan null case and nested structure. Minor omissions – such as explicit error/expired-auth behavior or rate-limit notes – are not critical for a read-only account details fetcher, and the interaction scope is fully visible.

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% – feedback is well-documented in the schema, while _requestId is not, and the description adds no per-parameter detail. This is mitigated because both parameters are auxiliary metadata (an optional feedback string and a request tracer) and neither steers the operation; the tool effectively takes zero functional parameters, so the parameter burden is minimal.

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

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

Opens with a specific verb-resource pair ('Get authenticated user's account details') and enumerates the exact content areas: plan (name, features), billing (period, renewal; null for Free plan), and usage (subscription credits, extra credits, extra tracked items). This makes it unmistakably distinct from the sibling social-media content tools, which all fetch third-party data rather than the caller's own account.

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

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

The description makes the context clear: it is the endpoint for inspecting the authenticated user's own plan/billing/usage state, and it states the authentication precondition. It does not explicitly name alternative tools or spell out when-not-to-use it, but given the sibling set is dominated by content-fetch tools, the scope stated is sufficient to steer an agent.

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

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

Annotations already mark it read-only, idempotent, and non-destructive. The description adds useful context beyond annotations: the tool requires authentication and returns time-series buckets with named fields such as subscriptionUsed, extraUsed, totalUsed, and extraPurchased. There is 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 compact and front-loaded with the core purpose, then summarizes parameters, return structure, and the alternative tool. There is slight redundancy between 'for analyzing usage patterns' and 'Use for trend analysis and spotting usage spikes,' but overall every part 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?

Since there is no output schema, the description compensates by naming the return shape (time-series buckets for credits and exportRows with the relevant fields). It also covers authorization, default behavior, and the related sibling tool. Nothing critical is missing for this read-only usage-history tool.

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

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

Schema description coverage is 75%, and the schema already documents range, granularity, and feedback. The description mostly repeats the range/granularity enums and defaults without adding new meaning, and it omits the feedback and _requestId parameters entirely. This falls at the baseline for schema-covered 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 names a specific action and resource: get the authenticated user's credits and export-rows usage over time. It clearly frames this as a trend-analysis tool and explicitly contrasts it with getAccountDetails, which handles current remaining balances.

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 says when to use the tool ('Use for trend analysis and spotting usage spikes') and when not to use it ('For current remaining balances, use getAccountDetails instead'). It also documents the range and granularity choices so the agent can decide appropriate calls.

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 provided annotations (readOnlyHint, destructiveHint), the description thoroughly explains behavior: response modes (fast, paging, csv), async polling via checkOperationStatus, automatic API fallback for fresh data, caching caveats, and S3 links for CSV exports. It also reinforces that this is a safe read-only operation, which is consistent 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 and uses headers to organize fast/paging/csv modes, but it does repeat some schema-level details (responseType descriptions, limit caps) and includes a verbose current-date warning. Still, every section adds value, and the beginning front-loads the core purpose before diving into edge cases.

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

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

Given no output schema, the description fully defines expected fields, available response modes, pagination and polling details, and a performance/usage strategy. It covers fallback behavior and when to omit parameters, leaving little for an agent to guess. This completeness outweighs the tool's large parameter surface.

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 many parameters, but the description adds meaningful nuance: it clarifies the postId strong_id requirement ('use the full id, NOT just media_id'), explains response modes in context, and provides default/conditional behavior for startDate/endDate and limit. It doesn't cover every parameter (e.g., _requestId, feedback) but the important ones get added meaning.

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

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

The description clearly states the action (get), the resource (Instagram post comments), and the returned data (id, text, username, etc.). It also distinguishes itself from the sibling tool for fetching commenter profiles, telling the agent exactly what it is and what it is not for.

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

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

The description explicitly says when to use this tool ('Use for reading what people said') and when NOT to use it, directing agents to getInstagramPostInteractingUsers for user profiles. It also gives concrete suggestions: omit startDate/endDate by default, only pass forceLatest when explicitly asked for latest data, and use userPrompt for accuracy.

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?

Even though annotations already include readOnlyHint=true and destructiveHint=false, the description adds substantial behavioral detail: 'FAST (default, omit responseType or responseType="fast"): Returns up to 300 results...', 'PAGING (responseType="paging"): Async paginated results... returns operationId - IMMEDIATELY call checkOperationStatus', and mentions 'Auto API fallback for commenters when stale'. These go well beyond what annotations convey, giving the agent a clear picture of output modes and asynchronous 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 thorough and well-structured with section headings (RETURNS, NOT FOR, INTERACTION TYPES, WHEN TO USE, FAST, PAGING), which makes it layout navigate. However, it is verbose and repeats some details (e.g., field lists appear both in the description and in the schema), and the use of ALL-CAPS and sentence-length chunks makes it less concise than an ideal description. Still front-loaded with purpose and sibling differentiation, so barely loses a point.

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

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

For a complex tool with 14 parameters, no output schema, and multiple response modes, the description covers output content, pagination, operationId polling, CSV export, default fields, and formatting requirements. It even gives examples of fields and explicitly states 'This is a safe, read-only tool for analyzing searchable information', ensuring an agent has enough context to call it correctly. The only minor omission is an explicit response structure for Python data, but the description lists the returned fields, which largely compensates.

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 79%, the description significantly supplements the schema by clarifying a strong format for postId (specifying the underscore-separated media_id + user_id and warning against only media_id), explaining the fast/paging/csv responseType modes, specifying default fields and that the limit is capped at 300 in fast mode, and listing available fields and examples. This is far more informative than the schema alone and provides the agent with necessary context to set parameters correctly.

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

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

The description explicitly states the verb and resource ('Get USER PROFILES of people who interacted with an Instagram post') and enumerates the returned fields (id, username, fullName, biography, followerCount, etc.). It also differentiates from the sibling getInstagramCommentsByPostId by stating 'NOT FOR COMMENT TEXT' and routing to the other tool, making the purpose unmistakable.

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

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

The description contains explicit 'WHEN TO USE THIS TOOL' and 'WHEN TO USE getInstagramCommentsByPostId' sections, giving the agent clear criteria for selecting between the two tools. It also explains the distinction between commenters and likers via the interactionType parameter, so the agent knows exactly when to call this tool versus the comment-text alternative.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, and the description reinforces them ('This is a safe, read-only tool'). Beyond the annotations it adds real behavioral context: omitting not-found IDs, searching the database first then the external API in parallel for stale data, and the strong_id format requirement. 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 information-dense, and each sentence earns its place - scoping, performance, the format caveat, URL handling, and return format are all marked with labels (PERFORMANCE, IMPORTANT, Returns). It could be tightened slightly, but the structure front-loads the purpose and keeps high-value warnings prominent.

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

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

Covers what it does, when to use it, format requirements, URL shortcode handling, performance trade-offs, and the return shape - filling the gap left by the missing output schema. For a batch read tool whose safety profile is already declared in annotations, nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 63% (middle range), and the description adds meaningful value: it clarifies the postIds strong_id format beyond the schema pattern ('use the full id value, NOT just the media_id'), explains the purpose of the optional fields parameter with concrete examples, and since there is no output schema, it documents the return shape (id, caption, userId, username, createdAtDate, engagement metrics, count, dataSource).

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

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

States a specific verb and resource ('Get multiple Instagram posts by IDs') with an explicit scope bound (1-50 IDs per request). It distinguishes itself from siblings by name ('NOT for search - use getInstagramPostsByKeywords') and by batch-vs-single-ID behavior, so an agent can select it correctly without opening other schemas.

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

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

Gives explicit when-to-use ('Use when you have multiple exact post IDs') and when-not-to ('NOT for search'), names the alternative tool, and covers the edge case of extracting a shortcode from an Instagram URL - telling the agent to route to getInstagramPostsByKeywords or ask the user. Performance guidance ('more efficient than multiple single-ID calls') reinforces the choice.

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 indicate readOnlyHint=true and destructiveHint=false, which the description aligns with. However, the description adds many behavioral details: database-first then API fallback, query syntax nuances, and the year warning. But it does not disclose potential rate limits, quotes costs, or what happens when API fails. It also implies async operations but doesn't specify polling behavior in detail. Given the annotations cover safety, the description does add context, but significant gaps remain around error handling and rate limits, so a 2 seems harsh but the bar is high due to 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 very long and dense, with significant redundancy (e.g., repeating response mode details in both the main text and the responseType parameter description). It front-loads the key action and response modes, but the volume of text may overwhelm agents. Several sections, like the repeated year warning and lengthy FIELDS enumeration, could be streamlined.

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 (multiple response modes, query syntax, 15 parameters), the description covers nearly everything an agent needs: query syntax, field options, date handling, and mode selection. It also notes the current year to avoid date errors. There is no output schema, so description must explain returns, which it does by listing default fields. This is complete.

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

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

Schema description coverage is 67%, so the schema already documents many parameters. The description adds meaning for key parameters: responseType modes, limit cap, fields categories and examples, date filter rules, and userPrompt importance. However, it does not detail pageNumberEnd, tableName, or forceLatest beyond what the schema says elsewhere. Overall, it supplements the schema meaningfully but not fully.

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

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

The description clearly states the tool searches Instagram posts by keywords with multiple response modes, and explicitly differentiates it from getInstagramPostsByIds for URL/post ID lookups. It names sibling alternatives like getInstagramPostsByIds and getInstagramPostsByUser, ensuring no ambiguity. The verb 'Search' and resource 'Instagram posts' are specific.

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

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

The description provides explicit guidance on when to use fast vs paging vs csv modes, when to omit date parameters, and when not to use the tool (URL/post ID lookups). It also instructs on query syntax and handling relative dates with a warning about the current year. This is comprehensive and actionable.

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

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

The description significantly expands on the annotations. Beyond readOnlyHint=true and destructiveHint=false, it discloses the safety profile ('This is a safe, read-only tool'), the auto API fallback that can pull fresh data, the async polling behavior via checkOperationStatus for paging/CSV modes, the caching behavior and forceLatest bypass option, and the critical current-year miscalculation pitfall when users ask for relative dates. The current-year warning is behavioral context an agent genuinely needs. No contradiction with annotations; readOnlyHint matches the stated read-only nature.

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

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

The description is substantially over-long — roughly a wall of text covering modes, date guidance, the current-year warning, fields, and safety. The front-loading is good (purpose first, then modes), but it rambles in the middle, and the 'IMPORTANT!!!!!' block with multiple exclamation points and ALL-CAPS is unprofessional and wastes space. The fields enumeration partially duplicates what the schema already documents (e.g., 'id, postType, userId, username, fullName, caption, createdAt, createdAtTimestamp, createdAtDate' is repeated in both places). Several sentences could be trimmed without losing meaning.

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

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

This is a complex 16-parameter tool with no output schema and only 69% schema coverage, and the description covers nearly everything an agent needs: identifier mode selection, all three response modes with their async contracts, date filtering rules, the current-year pitfall, default and available fields, performance via the fields parameter and limit, code-execution guidance for CSV, and the safety profile. It also dispatches the pagination flow via checkOperationStatus. The only minor omission is explicit pagination details for the pageNumberEnd parameter, but the description does reference '100/page' and the checking contract. For its complexity, the description is effectively 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 69%, and the description compensates substantially. It explains responseType semantics (fast default returns up to 300, paging is async 100/page with operationId, csv is async single download), the identifierType meaning (numeric id vs username), the date filter semantics (omit by default, only include on explicit date-range request with YYYY-MM-DD format), fields parameter categories (Core/Engagement/Media with their field names), and the tableName/pageNumber pagination contract. The userPrompt guidance is especially valuable — it explains why the parameter exists and the consequences of omitting it. All of this goes well beyond what the schema's property descriptions provide.

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, unambiguous statement: 'Get posts from Instagram user by ID or username.' It names the resource (Instagram user) and the operation (get posts), with two identifier modes. The field list and default fields (id, caption, username, createdAtDate) further disambiguate it from sibling tools like getInstagramPostsByIds (which fetches specific post IDs) and getInstagramPostsByKeywords (which searches by keyword). An agent can immediately tell what this tool is for.

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

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

The description gives clear when-to-use guidance: the identifierType selection rule, the three response modes with explicit trade-offs, date filter handling ('OMIT startDate/endDate parameters by default... ONLY pass these if user explicitly requests'), and the fields parameter optimization. It also states ideal use cases ('engagement analysis, content trends, posting patterns'). However, it never explicitly contrasts with sibling tools — it doesn't say 'use getInstagramPostsByKeywords instead for keyword-based search' — so the differentiation from alternatives is left 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 declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description reinforces safety by saying 'This is a safe, read-only tool for analyzing searchable information.' It also adds context about performance optimization via the 'fields' parameter and default values, which is beyond annotations. However, it doesn't mention caching behavior or potential rate limits, but annotations cover the core safety profile.

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

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

The description is reasonably concise, with key information front-loaded (purpose and identifier types). It includes examples and a safety note, all in about 4 sentences. It could be tightened slightly, but it's efficient and each sentence adds value.

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

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

Given the tool's complexity (9 params, 2 required) and high schema coverage (67%), the description covers the core decision points (ID vs username, search vs get), the main optional parameter (fields), and the safety profile. It also mentions the return fields. No essential information is missing for an agent to call it correctly.

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

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

Schema description coverage is 67%, so the description partially helps. The description adds some value by explaining the identifierType parameter and the default for fields, but the schema already provides detailed descriptions for 'fields' and 'identifierType'. The description does not add detail to other parameters like userPrompt or forceLatest, which are already described in the schema. Thus, the description adds marginal value over the schema, aligning with the baseline of 3.

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

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

The description clearly states the tool's purpose: 'Get Instagram user profile by ID or username.' It specifies the two identifier types and provides examples for each, which is specific. It also distinguishes itself from a sibling tool (searchInstagramUsers) by noting when to use that instead, showing strong differentiation.

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

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

The description explicitly tells when to use this tool (exact username or ID) and when not to (fuzzy search or person names → use searchInstagramUsers). It also explains the optional 'fields' parameter and its default, giving clear guidance on how to use the tool effectively.

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

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

Goes well beyond the readOnlyHint annotation, disclosing cache freshness rules (data > 1 week triggers refresh), API fallback behavior, pagination lifecycle (operationId, checkOperationStatus), cost implications of forceLatest, and the crucial limitation of partial database data (totalRows vs totalDataCount). This is exactly the kind of context annotations cannot convey.

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

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

The description is long, but it is internally structured with mode/table sections and front-loaded with the essential purpose and connectionType. Some schema repetition exists (e.g., 'limit=5' and 'Returns up to 300 results' are echoed), yet the high information density justifies the length for an AI agent that must make correct calls.

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, 14 parameters, async pagination, and cache semantics, this description covers most critical operational aspects: data freshness, paging workflow, field selection, and the totalDataCount trap. It does not describe the 'csv' response mode in the main flow or a sample result shape, but it covers the safety and correctness essentials sufficiently 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?

With 79% schema coverage, a baseline of 3 applies, but the description adds meaningful semantics beyond the schema: it explains that limit is capped at 300 in fast mode but can export up to 500K in paging/CSV modes, enumerates useful field examples, and explains the critical totalRows/totalDataCount interpretation. It does not, however, add semantics for userPrompt, _isTrial, _requestId, or _trialToken (undocumented or hidden 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 opens with a specific verb and resource ('Get Instagram user connections') and immediately clarifies the core distinction between 'followers' and 'following' via connectionType. That differentiates the tool from its siblings (getInstagramUser, getInstagramPostInteractingUsers, etc.) without opening schemas.

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

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

Provides clear context for the fast vs paging modes, when to use forceLatest, and how to interpret totalDataCount vs totalRows. However, it omits the 'csv' response mode that the schema's enum includes, and it does not explicitly say when to prefer this tool over sibling tools (e.g., 'use getInstagramUser for a single profile')—leaving a notable gap for an agent facing many siblings.

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

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

The description goes well beyond the annotations (readOnlyHint=true, destructiveHint=false) by explicitly stating 'This is a safe, read-only tool'. It discloses critical behaviors: response modes (fast/paging/csv) and their async nature, pagination mechanics (cached table, pageNumber/tableName), query syntax limitations (forward slashes as spaces, no column operators), and the 2026 date warning. These are not inferable from annotations and significantly reduce risk of misuse.

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

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

The description is lengthy but well-structured with clear sections (USE CASE, RESPONSE MODES, PAGING MODE DETAILS, QUERY SYNTAX, FILTERS, IMPORTANT, AGGREGATE FIELDS). It is front-loaded with the core purpose. Some redundancy exists (e.g., response mode details repeated in the main text and in schema parameter descriptions), and the date warning could be tightened, but the complexity of the tool justifies the length. It remains readable and organized.

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 parameters, three response modes, and complex query syntax, the description is remarkably complete. It covers return structure ('results array of unique user profiles, count', pagination object, operation IDs), field selection behavior, date filtering, and edge cases (forward slashes, boolean operator requirements). No output schema exists, so the description carries the full burden, and it does so 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?

Despite 67% schema coverage, the description adds substantial parameter meaning: it explains responseType options in depth, clarifies that limit caps differ by mode, details the interplay of pageNumber/tableName/pageNumberEnd, warns about forceLatest cost, and emphasizes userPrompt's role in NLP optimization. It also elaborates on aggregate fields semantics (from matching posts, not all posts). This far exceeds the schema's 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 for USERS who authored Instagram posts matching keywords' – a specific verb, resource, and scope. It distinguishes this user-focused search from sibling tools like getInstagramPostsByKeywords by clarifying it returns unique user profiles, and from searchInstagramUsers by the keyword-matching mechanism. The purpose is unambiguous and immediately clear.

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

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

Provides an explicit USE CASE and detailed guidance on when to use each response mode (fast vs paging vs csv), with conditions like 'Best for quick lookups' and 'Best for bulk export'. It also instructs on when to omit date filters ('only use if user explicitly requests date range') and warns about year miscalculation. However, it does not explicitly name alternative sibling tools or state 'use this instead of X', so it falls short of a full 5 but is highly actionable.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: the database-first then API-fallback logic, the staleness threshold (>1 week), the default fields, and the explicit 'safe, read-only' statement. It doesn't detail error cases or rate limits, but the annotations plus description cover the key behavioral traits well.

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

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

The description is well-structured: it starts with the core purpose, then input format, then behavior, then exclusions, then performance options, then return summary. It is slightly dense but every sentence adds value. The 'NOT for searching' sentence is a strong disambiguator. It could be slightly shorter, but the density is justified by the tool's complexity.

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

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

For a single-comment fetch tool with rich annotations and a detailed schema, the description covers the essential context: what it returns, how it caches, when to use forceLatest, and how it differs from search. There is no output schema, but the description lists the return fields. The main gap is not describing error behavior (e.g., what happens if the comment doesn't exist), but that is a minor omission given the overall completeness.

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

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

Schema description coverage is 57%, so the schema documents several parameters (commentId, fields, forceLatest) in detail. The description adds meaning by explaining the ID forms, the default fields, and the performance purpose of the fields parameter. It doesn't need to repeat the full field list since the schema already provides it. The description compensates for the undocumented parameters (_isTrial, _requestId, _trialToken) by not needing to explain them—they are internal/plumbing parameters.

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

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

The description states a specific verb ('Get'), a specific resource ('a single Reddit comment by its ID'), and explicitly distinguishes itself from the search tool ('NOT for searching - use getRedditCommentsByKeywords for keyword search'). It also clarifies the accepted ID forms, which removes ambiguity about what input is expected.

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

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

The description explicitly says when to use this tool (fetch a single comment by ID) and when not to (keyword search), naming the alternative tool. It also explains the caching/fallback behavior (database first, then external API if missing or stale), which helps an agent decide whether to use this tool or force a fresh fetch.

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=true, destructiveHint=false) by adding critical behavioral details: it states the tool is safe and read-only, explains async polling for paging and csv modes, notes database-only scope, and includes the year-2026 caveat. 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 overly long and repetitive, with ALL-CAPS emphasis and exclamation marks that reduce readability. It repeats schema content (e.g., query examples) and packs multiple sections into a single paragraph. While it is structured with section breaks, the verbosity undermines 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?

For a tool with 14 parameters, multiple response modes, complex query syntax, and date handling, the description is remarkably complete. It covers all modes, filtering, fields, date defaults, relative date pitfalls, and even provides guidance on using code execution for CSV analysis. No essential aspect is missing.

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

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

With 64% schema coverage, the description compensates substantially. It explains query syntax (boolean operators, exact phrases, parentheses, @handles, field operators), the subreddit filter, field selection options, and mode-specific limit behavior. This adds meaning beyond the schema's descriptions, making parameter usage unambiguous.

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: 'Search Reddit comments by keywords' and clarifies it searches comment body text. This immediately distinguishes it from siblings like getRedditPostsByKeywords or getRedditCommentById, leaving no ambiguity about the tool's role.

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

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

It provides explicit guidance on when to use each response mode (fast, paging, csv), the default omission of date filters, and a strong warning about relative dates with the current year (2026). While it doesn't name alternative tools directly, the scope and conditions are clearly stated, enabling correct usage decisions.

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

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

The description discloses that the tool first searches a database then falls back to an external API, mentions auto API fallback for fresh data, describes async behavior for paging/CSV, warns about the current year 2026 and date calculation pitfalls, and explicitly states it is a safe, read-only tool. These details go beyond the annotations (readOnlyHint, openWorldHint) and provide valuable operational context.

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

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

The description is lengthy but well-structured with clear sections (QUERY SYNTAX, FILTERS, FIELDS, response modes). It front-loads the core purpose and response modes, and each section is dense with necessary detail given the tool's complexity. While it could be trimmed, the length is justified by the 18-parameter tool and the need to cover async modes, query language, and field options.

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

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

The description covers all critical aspects: response modes, query syntax, field selection, date filtering with a warning about the current year, pagination details, CSV handling, and the need to poll via checkOperationStatus. Since there is no output schema, the description compensates by listing default fields and providing examples. It is comprehensive for an agent to use the tool correctly.

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

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

Despite the schema having 72% coverage, the description adds substantial parameter semantics: it explains query syntax with examples (quotes, boolean operators, parentheses), clarifies the behavior of limit in different modes, describes the fields parameter with a full list and examples, and gives usage guidance for date parameters, subreddit, and forceLatest. This significantly enhances understanding beyond the schema.

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

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

The description clearly states the tool searches Reddit posts by keywords, explicitly mentions it searches titles and selftext, and lists the default fields and response modes. It distinguishes from sibling tools like getRedditCommentsByKeywords and getRedditSubredditsByKeywords by focusing on posts and providing a detailed query syntax and filter set.

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

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

The description provides extensive usage guidance, including when to use each response mode (fast, paging, csv), how to handle date filters (omit by default, pass only on explicit request), and the recommendation to use code execution for CSV mode. It also explains the query syntax and field selection. However, it does not explicitly compare with sibling tools or state when not to use this tool, which would elevate it to a 5.

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

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

The description transparently explains cache-first behavior with automatic API fallback, the fast vs. paginated execution modes, pagination mechanics (tableName, pageNumber, pageNumberEnd), and the fact that subsequent pages return only comments, not the post. It also explicitly states the operation is read-only and safe, going beyond the annotations. This gives an agent a realistic model of what happens when the tool is invoked.

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 it's well-structured with clear section headers (FAST vs PAGING, RESPONSE STRUCTURE, FIELD SELECTION) that front-load the most important operational distinctions. While some redundancy exists (mode names repeated in several places), the dense information density justifies the length for such a multi-mode tool.

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

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

Given the tool's complexity — 13 parameters, two distinct usage modes, pagination state, and field selection — the description covers all critical aspects: mode selection, result caps, pagination flow, available fields, response shape, and safety guarantees. The only minor gap is the lack of explicit mention of rate limits or error conditions, but this is acceptable given the annotations and detailed parameter docs.

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 substantially enriches the schema. It explains the limit parameter's behavior in fast mode (300 cap) vs paging modes, details how postFields and commentFields control returned data with full field lists, and clarifies the interplay between tableName, pageNumber, and pageNumberEnd. This goes well beyond the schema's basic property descriptions, adding meaning that would otherwise be opaque.

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 statement: 'Get Reddit post with its comments by postId', specifying the exact resource and operation. The title further clarifies the domain (Reddit: Get Post with Comments by ID), and the sibling tool names (e.g., getRedditCommentById, getRedditPostsByKeywords) confirm this tool's distinct role. An agent can immediately recognize what this tool does and how it differs from related tools.

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

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

The description provides strong guidance on when to use fast mode versus paging mode, and clarifies how to paginate (omit tableName/pageNumber for first call, include them for subsequent pages). It also mentions fallback behavior for fresh data. However, it doesn't explicitly discuss when to prefer alternative sibling tools (e.g., getRedditCommentById) for narrower use cases, so a small gap in mode-selectivity advice remains.

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

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

Beyond readOnlyHint/destructiveHint annotations, it discloses deduplication, auto API fallback, async pagination with operationId polling, treatment of forward slashes and field-operator stripping, and caching behavior via forceLatest. The 'safe, read-only' line is consistent with annotations and the description adds substantial behavioral context.

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

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

The description is densely organized into FAST/PAGING, QUERY SYNTAX, FILTERS, and FIELDS sections, front-loading the core purpose. It is verbose and includes an over-emphatic 'IMPORTANT!!!!!' year-check aside and some redundancy with schema descriptions, but the complexity of the tool justifies most of the length.

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

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

With no output schema, the description carries the burden of describing response modes, and it does: fast results, paging operationId, and field-level control. Combined with the schema for param details, an agent has everything needed to select and invoke it; only internal/experimental params are left to schema docs.

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 query syntax rules, the 300-result fast cap, aggregate field requirements, date formatting, and field selection performance guidance that are not in the schema descriptions. Even though schema coverage is 80%, the description goes well beyond the structured field docs.

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

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

The opening sentence, 'Search for SUBREDDITS where Reddit posts match keywords. Returns unique, deduplicated subreddit profiles,' clearly identifies a specific verb, resource, and result semantics. However, it never contrasts itself with related siblings like searchRedditSubreddits or getRedditPostsByKeywords, so the differentiation burden is on the reader.

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 operational context: fast vs paging modes, when to use date filters ('OMIT by default, only use if user explicitly requests date range'), and detailed query syntax. It does not explicitly state when to prefer this tool over sibling search/Reddit tools, 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?

The description is exceptionally transparent: it states it's a read-only safe tool (matching the annotation), describes the two modes with their outputs, mentions polling for pagination, and explicitly warns about forceLatest cache bypass and its cost. This far exceeds baseline.

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?

Information-dense and front-loads the key decision (fast vs paging). Slightly long, but every sentence carries distinct value and the field-listing section is a deliberate tradeoff for a data-fetching tool.

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

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

For an agent this covers everything: what it returns, how to switch response modes, how to paginate, how to limit fields/volume, and the cache caveat. The only minor gap is no explicit return-format example, but the mode descriptions compensate.

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

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

Schema covers 77% of parameters, but the description adds significant meaning beyond it: explains the default fast mode cap of 300, pagination semantics (tableName/pageNumber), field selection defaults, and CSV mode export caps. Slight deduction because some schema entities like _isTrial and feedback are not mentioned in the description, but these are minor.

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

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

The description states a specific verb ('Get') and resource ('Reddit subreddit with posts'), and clearly differentiates itself from sibling tools by focusing on a single subreddit with its 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?

It explains the two response modes (fast default vs paging), how to fetch subsequent pages, and mentions field customization. It does not explicitly exclude alternatives or state when to prefer this over e.g. getRedditPostWithCommentsById or getRedditPostsByKeywords, so it loses one point.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description's 'safe, read-only' language reinforces these, and the statement that it handles searchable information adds a little context. It does not, however, disclose any additional behavioral nuances beyond the annotations, such as caching behavior, rate limits, or data freshness details.

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 organized with a succinct overview, usage note, field list, return summary, and safety statement. The long flat list of available fields duplicates the schema's fields description, though for a wide field set this tradeoff is acceptable. It's under 200 words and front-loads the core purpose.

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

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

For a read-only get-by-id tool with no output schema, the description covers the key return shape (single user profile with karma metrics, account flags, profile details), the default field behavior, and the username format requirement. The remaining params such as userPrompt, _requestId, and forceLatest serve the schema-visible infrastructure and don't materially affect completeness here.

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

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

Schema description coverage is 63%, and the schema already documents the available 'fields' options, the default list, and the 'without u/ prefix' rule for username. The description restates the default and available fields in a categorized manner but adds little new meaning beyond the schema; the duplicated list is mostly redundant with the fields property description.

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

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

The description states a specific verb ('Get') and resource ('Reddit user profile by username') and details the core returns: karma breakdown, account status, and profile info. It does not explicitly name sibling tools to differentiate, but the 'by username' and 'u/ prefix' phrasing makes the single-user-by-username intent clear relative to getRedditUsersByKeywords and searchRedditUsers.

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 operational guidance: omit the u/ prefix, optional fields for performance, and flags the tool as safe/read-only. It provides context for how to call correctly, but no explicit instructions when to prefer this tool over sibling alternatives like getRedditUsersByKeywords or searchRedditUsers, nor conditions for when not to use it.

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

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

The description substantially exceeds what annotations declare. Beyond the read-only/destructive hints, it discloses async behavior (paging/csv return operation IDs requiring checkOperationStatus polling), caching side effects (creates cached table on first paging call), query transformations (field operators stripped, forward slashes treated as spaces), and the requirement that aggregate fields be explicitly requested. The final line 'This is a safe, read-only tool' is consistent with readOnlyHint=true and destructiveHint=false. No contradiction; it adds rich behavioral context beyond structured data.

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 with labeled sections (USE CASE, RESPONSE MODES, PAGING MODE DETAILS, QUERY SYNTAX, FILTERS, AGGREGATE FIELDS) and is front-loaded with the core purpose. There is some redundancy with the schema — the query syntax is explained both in the description and in the query parameter's schema text — and the 'IMPORTANT!!!!!' year warning is noisy. Given 16 params and 3 response modes, the density is largely justified; it earns most of its 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?

For a 16-parameter tool with no output schema, the description is remarkably complete. It covers all three response modes and their return behavior (up to 300 results, operation IDs for paging, S3 link for CSV), the full paging lifecycle, query syntax with boolean operators and @handles, all filter semantics including the date behavior and year-verification caveat, and aggregate field requirements. The only minor gap is no explicit pagination default behavior statement, but this is covered. Nothing an agent needs to invoke it correctly across modes is missing.

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

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

With 81% schema coverage, the baseline is 3, and the schema already documents query, fields, limit, responseType, and paging params thoroughly. The description adds genuine value beyond the schema by explaining the paging workflow (omit pageNumber/tableName on first call, use returned tableName for subsequent pages, pageNumberEnd for bulk fetch) and clarifying aggregate fields (aggRelevance, relevantPostsCount) that must be explicitly requested. It does not repeat param names but explains their interaction, which is the useful complement.

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

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

The description states a specific verb+resource: 'Search for USERS who authored Reddit posts matching keywords.' It clearly differentiates from siblings like getRedditPostsByKeywords and getRedditCommentsByKeywords by emphasizing 'USERS who authored' and 'Returns unique, deduplicated user profiles.' The use case is stated explicitly and the scope (users, not posts/comments/subreddits) is unambiguous.

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

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

The description provides a clear USE CASE ('Find users who have posted content about specific topics') and detailed operational guidance on response modes, filters, and paging. However, it never explicitly routes the agent away from alternatives like getRedditPostsByKeywords or searchRedditUsers, so exclusions are left to the agent to infer. It has clear context but no explicit when-not-to-use guidance, matching the 'clear context, no exclusions' level.

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: response modes (fast, paging, csv), pagination mechanics with operationId polling, CSV download flow, auto API fallback, caching behavior with forceLatest, and a warning about year miscalculation. This goes well beyond the annotations and fully discloses operational nuances.

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 meticulously organized into sections (FAST, PAGING, CSV, CODE EXECUTION, date filters) with clear headers. It front-loads the core purpose and returns data, then provides mode-specific details. Each sentence serves a purpose, including the current-year warning which prevents common errors. No redundant filler.

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

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

Given the tool's complexity (15 parameters, multiple response modes, no output schema), the description is exceptionally complete. It covers return fields, all response modes, pagination and CSV workflows, caching, performance, and date handling. It also explains how to analyze CSV data via code execution. Nothing an agent needs to call it correctly is missing.

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

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

Despite 67% schema coverage, the description enriches almost every parameter. It explains limit caps per mode, provides field examples and performance optimization, details responseType modes, warns about forceLatest latency/cost, explains pageNumber/tableName for pagination, and clarifies date filter defaults. This compensates for any schema gaps and adds meaningful semantics beyond the raw property descriptions.

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

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

The description clearly states the tool retrieves comment content (text, likes) for a TikTok post, returning specific fields (id, text, username, createdAtDate, likeCount). It is unambiguous and distinct from sibling tools like getTwitterPostComments or getInstagramCommentsByPostId due to the platform-specific naming and content focus.

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: 'Use for reading what people said' and lists ideal use cases like sentiment analysis and engagement patterns. It also gives clear directives on date filters ('OMIT startDate/endDate by default. ONLY pass if user explicitly requests date range'). However, it does not name alternative tools for different platforms or contexts, so it stops short of explicit exclusions relative to siblings.

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

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

While annotations already declare readOnlyHint=true, the description adds substantial behavioral context: OR semantics, response mode behaviors (fast vs async paging/CSV), limit constraints, date filter cautions, a warning about year miscalculation, and a note about field defaults. This goes far beyond the annotations and prepares the agent for real-world usage.

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 packed with essential information for a complex tool. It is front-loaded with the core purpose, then systematically covers modes, exclusions, date handling, and field selection. It could be slightly tightened, but every sentence serves a purpose.

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

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

Given the tool's complexity (15 parameters, three response modes, async operations, and multiple field categories), the description is exceptionally complete. It covers response modes, async polling, field defaults, date filters, and usage exclusions. Nothing critical is missing, and it even includes a time-sensitive year warning.

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 explains the semantics of key parameters that the schema only partially covers (67% coverage). It clarifies responseType modes, limit behavior per mode, how paging/tableName/pageNumber work together, and the fields parameter options. This adds meaning 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 clearly states the tool searches TikTok posts by hashtags, specifies that it searches the hashtags column directly (not descriptions), and distinguishes it from getTiktokPostsByKeywords and getTiktokPostsByIds. This gives the agent a precise understanding of its function and 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 explicitly lists when to use this tool (hashtag trend analysis, viral tracking, cross-hashtag discovery) and when not to (keyword/phrase search, URL/post ID lookups), naming the alternatives. It also provides detailed guidance on response modes, date filters, and field selection, leaving no ambiguity.

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

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

The description explains that results are fetched from database first with external API fallback for missing/stale data, and that results are 'returned directly'. It also confirms the read-only, safe nature consistent with the 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?

Three concise sentences; key info (what, limits, behavior) is front-loaded. Some redundancy with annotations ('safe, read-only') but not bloated.

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

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

The description explains the two-tier fetch (DB then external API), return shape (results array, fields), and the optional fields parameter – useful given no output schema. It doesn't cover rate limits or auth, but for a read-only fetch tool 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 63%, with the `fields` and `postIds` params well described in the schema itself. Description adds that fields is for performance and that the return includes specific fields (id, description, userId, username, etc.), which is somewhat useful. The remaining params (_isTrial, feedback) aren't covered but are boilerplate.

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

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

The description states a specific action ('Get multiple Tiktok posts by IDs') with a clear resource and scope (1-100 IDs), which is immediately understandable. It does not explicitly compare to sibling tools like getInstagramPostsByIds, but the TikTok + IDs scope is unambiguous.

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

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

It explains the retrieval flow ('database, then external API for missing/stale data') and mentions the fields parameter for performance. However, it does not specify when to prefer this over sibling tools like getTiktokPostsByKeywords, and offers no cost/latency guidance despite a multi-step fetch strategy.

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 destructiveHint, and the description reinforces this ('safe, read-only tool'). It adds comprehensive behavioral detail: async modes, polling via operationId, query syntax handling (AND/OR/NOT, @handles, quote handling), and the 2026 year warning. This significantly exceeds annotation coverage, providing context an agent needs to use it correctly.

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 structured with bold headers and logical sections (modes, query syntax, fields, warnings). It front-loads the main modes and then provides necessary details. It could be trimmed slightly (e.g., the repeated year warning is lengthy), but the density of useful information justifies the length. 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?

For a tool with 15 parameters, this description is remarkably complete. It covers all response modes, pagination, CSV download, field selection, query syntax, date handling, and performance notes. The absence of an output schema is mitigated by listing default return fields. Everything an agent needs to call this tool correctly is addressed.

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

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

Schema coverage is 67%, and the description compensates richly. It explains the meaning and usage of responseType, limit caps, fields available, date filtering best practices, tableName/pageNumber for paging, and the userPrompt advice. It adds meaning well beyond the schema's parameter descriptions, especially for responseType and 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?

Clearly states it searches TikTok posts by keywords, distinguishes itself from getTiktokPostsByIds, and describes the three response modes. The verb 'search' and resource 'TikTok posts' are specific, and it explicitly says what it is not for, making it distinguishable from siblings.

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

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

Explicitly gives when-to-use guidance: use getTiktokPostsByIds for URL/ID lookups, explains when to use CSV mode with code execution, and provides detailed query syntax rules. Also gives date-filtering advice and warns about the current year. Clear exclusions and alternatives are present.

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 behavioral context beyond annotations: async modes require polling via checkOperationStatus, caching behavior with forceLatest (in schema), and a critical warning about the current year 2026 to prevent date miscalculations. 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 every section earns its place: purpose is front-loaded, modes are clearly separated, warnings are highlighted, and field groups are organized. It is efficiently structured for a tool with 15 parameters and three response modes, avoiding 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?

Given the tool's complexity (async modes, pagination, caching, multiple parameter groups), the description covers all necessary operational aspects: required input, mode selection, pagination mechanics, field selection, date handling, and explicit exclusions. It also provides the current-year context to prevent common errors. No output schema exists, but the description adequately conveys expected return data via field groups.

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 significantly enriches parameter meaning: it explains responseType modes and defaults, limit capping per mode, the fields parameter with grouped options and examples, date filter usage, and the userPrompt field's role. It also clarifies soundId format and origin. This goes well beyond the schema's raw 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 explicitly states the tool retrieves TikTok posts by a specific sound/music ID, and clearly distinguishes from siblings by naming getTiktokPostsByKeywords and getTiktokPostsByHashtags as alternatives for different query types. The required parameter soundId is defined with origin instructions.

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, details three response modes (fast, paging, csv) with defaults and polling instructions, and gives negative guidance (not for keywords/hashtags) pointing to specific siblings. Also instructs on date filters, saying to omit by default and only pass when explicitly requested.

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?

Explicitly states it is safe/read-only, searches the database first with API fallback, supports async paging, and warns about relative-date mistakes. Annotations declare readOnly, openWorld, not destructive; 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?

Mostly well structured but somewhat bloated: the ALL-CAPS date warning and repeated listing of modes/fields duplicate information already in the schemaais. The opening sentence is clear nest package; value is high but density harms 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?

Covers defaults, response modes, field options, date handling, and safety. Missing explicit output shape and error conditions, but enough for agent to call correctly.

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

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

The schema already has detailed parameter descriptions; the description adds meaningful default behavior (default field set, 300-row fast mode, fields groups, date semantics). This goes beyond simply restating 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 opens with 'Get TikTok posts by user ID or username' and immediately distinguishes the three response modes prospecting behavior from sibling tools such as getTiktokPostsByKeywords or getTiktokPostsBySound. The tool's purpose is unambiguous.

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

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

Provides strong operational guidance: how to choose identifierType, when to use paging/CSV modes, how to use fields, and when to pass date parameters. It does not explicitly compare against alternative post-fetching siblings, but gives enough context for an agent to select and use this tool correctly.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds 'This is a safe, read-only tool' and mentions the performance optimization via the fields parameter, which adds a bit of context. However, it largely repeats the read-only annotation without disclosing any new behavioral traits like rate limits or authentication requirements, so the added value is modest.

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

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

The description is well-structured and front-loaded with the core purpose. It uses concise sentences and includes necessary usage details without excessive verbosity. The inclusion of a fields list is informative but slightly lengthy; however, it earns its place by guiding parameter selection. Overall, it is efficient and easy to parse.

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

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

For a single-user lookup tool with no output schema, the description provides adequate context. It explicitly states the return type ('single user profile') and, combined with the schema's fields description, gives enough detail for an agent to request specific fields. It does not cover error cases or rate limits, but given the simple read-only nature and existing annotations, the description is sufficiently complete 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?

The description adds meaning beyond the schema by explaining the identifierType parameter ('Use identifierType="id" for numeric user ID, identifierType="username" for username') and elaborating on the fields parameter with a default and a list of available fields. While schema description coverage is 67%, the description fills important gaps for the two required parameters and the performance-oriented fields parameter, making it more actionable than schema alone.

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

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

The description states a clear verb and resource: 'Get Tiktok user profile by ID or username.' It also distinguishes itself from the sibling searchTiktokUsers by clarifying that it is for exact identifiers, not fuzzy search. This makes the purpose unambiguous and differentiates it from related 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 explicitly specifies when to use it: 'Use identifierType="id" for numeric user ID' and 'Use ONLY when you have the precise username.' It also gives an exclusion: 'For person names or fuzzy search, use searchTiktokUsers instead.' This provides clear, actionable guidance and names the alternative tool.

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

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

Beyond annotations already declaring readOnly and non-destructive hints, the description adds useful behavioral context: deduplicated results, OR semantics, async pagination with operation IDs, and CSV export via checkOperationStatus. It does not address auth/rate-limit details, but for a read-only tool with this much annotation support, only a small gap remains.

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 content is front-loaded and organized, but the description is dense and redundant in places, restating hashtag format and response modes that already exist in the schema. The 'CURRENT YEAR IS 2026' instruction adds context but feels time-sensitive and non-tool-specific, making the description heavier than necessary.

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

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

Given no output schema and the tool's complexity, the description covers the essential decision points: response modes, pagination/CSV output, field selection, aggregate fields, date ranges, and keyword-search alternatives. It would be stronger with a clearer statement of the user-profile result shape, but it is otherwise 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?

The description adds meaning beyond the schema for hashtags, response modes, date formats, default fields, and aggregate fields, and it gives concrete examples. It does duplicate some schema content and leaves the more internal parameters like pageNumberEnd and userPrompt to the schema, but the main operational parameters are substantially clarified.

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 clearly states the operation: search for user profiles who authored TikTok posts tagged with specific hashtags. It also distinguishes the tool from its close sibling by explicitly directing keyword/phrase searches to getTiktokUsersByKeywords.

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 an explicit use case, explains when each responseType mode is appropriate, and explicitly names the alternative tool for keyword-based search. An agent can confidently select this tool versus getTiktokUsersByKeywords and choose fast, paging, or CSV mode based on the task.

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

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

Annotations include readOnlyHint=true and destructiveHint=false, so the agent already knows it's read-only. Description adds: deduplication behavior ('unique, deduplicated results'), pagination/operation ID behavior in paging mode, and 2026 date caveat. However, it doesn't explain what happens to the cached table, how long operation results persist, rate limits, or default max of 300 shown in schema. The description aligns with annotations (no contradiction). It adds moderate value 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 very long (over 300 words) with dense formatting. It front-loads the purpose but then buries crucial warnings (schema type mismatch, date caveat) in a wall of text at the end. The description mixes usage modes, query syntax examples, and safety warnings without clear hierarchy. Could be structured with bullet points or headings. Every sentence does not earn its place - some details are duplicated in the schema.

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?

Complexity is high: 15 params, multiple response modes, pagination, conditional params (pageNumber requires tableName). No output schema, so description must cover response shapes. It does cover: fast returns up to 300 results, paging returns 100/page with tableName, csv returns S3 link. But missing: what fields are in the returned user profiles (beyond the param list), error handling, rate limits, how 'query' interacts with 'queryType' (if that exists). Given the complexity, the description is fairly complete but not comprehensive.

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

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

Schema description coverage is high (most params have descriptions with examples: query boolean syntax, limit default of 300, responseType modes, etc.). The description adds pagination details (how to use tableName for subsequent pages, max 500K) not fully explained in schema. But many descriptive elements are duplicated between description and schema. The main added meaning is the responseType behavior and the warning that @handles are stripped and forward slashes treated as spaces.

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

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

The description states a specific verb and resource: 'Search for USERS who authored Tiktok posts' and notes deduplication, clearly distinguishing it from sibling tools like getTiktokPostsByKeywords. It also explicitly names the use case (find users matching keywords). Loses a point because 'Tiktok' vs 'TikTok' naming and the scope of 'users' versus 'post authors' could be slightly more explicit upfront.

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 detailed when-to-use guidance: covers all three response modes (fast, paging, csv), explains first-call vs subsequent-pagination flow, specifies defaults (300 fast results, 100/page), and names sibling tools like getTiktokPostsByKeywords. It also explicitly notes this tool searches users, not posts, distinguishing it from siblings. The 'verify current date' note for 2026 is operational guidance that helps usage.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is clear. The description adds value by disclosing the exact return fields and the platform-type restrictions (subreddit is Reddit-only, hashtag is TikTok-only), which goes beyond the annotation metadata.

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 composed of two tight sentences with no filler. The first sentence names the operation, and the second gives the essential return fields and constraints in an easy-to-parse format. Every sentence adds value.

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

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

For a simple read-only retrieval tool with no output schema, the description covers the key question of what is returned and the allowable platform/type combinations. It does not explicitly state that the result is a list/array, but that is safely inferable from 'Returns: phrase, type, platform.'

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

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

Schema description coverage is only 25%, and the description does not compensate by explaining any parameters. The parameters are optional and internal (`_isTrial`, `feedback`, `_requestId`, `_trialToken`), but the description neither acknowledges that nor clarifies whether any parameter affects behavior.

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 resource ('tracked items') and the retrieval verb 'Get'. It also gives enough detail about the returned phrase, type, and platform to differentiate the tool from sibling content-retrieval tools that fetch posts/users by keyword.

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

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

No explicit guidance is given about when to use this tool versus alternatives like addTrackedItems, removeTrackedItems, or the many data-fetching getters. The phrase 'tracked' implies it is about the user's saved items, but the description does not state this directly or set exclusions.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description reinforces this ('This is a safe, read-only tool'). It adds substantial behavioral context beyond annotations: database-first lookup with external API fallback if data is stale (>10 days), async operationId/polling semantics for paging and CSV modes, the date-filter requirement to OMIT startDate unless explicitly requested, and the 2026 year-calculation warning that protects against common agent date errors. All of this aligns with, and enriches, 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 mode-based structure is front-loaded and logical, but the description is a sprawling wall of text with loud labels ('IMPORTANT!!!!!', 'CODE EXECUTION:'), some redundancy between 'Ideal for' and 'Use to analyze community response', and repeated emphasis. The information earns its keep, but it could be tightened into structured bullets 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 14 parameters, no output schema, and no schema, the description is remarkably complete. It explains the return shape for each mode (direct results for fast, operationId polling for paging, S3 link for CSV), caching authenticity, staleness threshold, an SQL prompt that is important for relative dates, and the included code-execution suggestion which is actually missing from the schema. An agent has what it needs 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 description coverage is 71%, so the description carries meaningful weight, and it delivers. It explains limit semantics (capped at 300 in fast mode, default: 300), elaborates each responseType mode beyond the enum, gives field-selection performance guidance with examples, provides a rule for startDate in the schema, and cautions to pass the rule that userPrompt is 'CRITICAL FOR ACCURACY'. This adds real decision-making value on top of 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 opening sentence 'Get comments (replies) to specific post' names a specific verb and resource with explicit scope. It differentiates from siblings by explicitly stating 'NOT for quotes - use getTwitterPostQuotes', and the Twitter-prefix plus comment/reply semantics separate it from the retweet and interacting-users siblings.

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

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

The description gives clear context for when to use the tool ('Use to analyze community response and discussion', 'Ideal for: sentiment analysis, discussion themes, community engagement analysis') and an explicit exclusion with an alternative ('NOT for quotes - use getTwitterPostQuotes'). It does not address when to choose this over getTwitterPostRetweets or getTwitterPostInteractingUsers, so the guidance is strong but not fully comprehensive across siblings.

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

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

With no annotations provided, the description carries the full burden. It discloses important behavioral traits: caching behavior (DB data stale -> API fallback), async pagination mechanics, concurrency limits (429 errors), rate limits (200 req/min), and result size limits (500 max for fast mode). Not all edge cases covered (e.g., exact rate limit details, error handling), but substantial transparency. Minor deduction for not mentioning what happens to cached data freshness or whether results are sorted.

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-structured with clear section headers (FAST, PAGING, CSV, INTERACTION TYPES). Some redundancy exists (paging mechanics repeated in 'PAGING MODE DETAILS'), and the description is dense. Every sentence earns its place, but could be tightened.

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

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

Covers purpose, mode selection, behavioral traits (caching, rate limits, async patterns), parameter semantics, and explicitly names the alternative tool. Self-contained for an agent to invoke correctly without additional context.

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

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

The description explains parameter behavior beyond the schema: how limit defaults to 10 and caps at 100, how sortBy affects ordering, how cursor-based pagination works, and the relationship between maxResults and total counts. Schema coverage is good but the description adds contextual meaning (paging mechanics, field behavior) that the schema alone doesn't convey.

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

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

States a specific verb ('Get'), object ('users who interacted with a specific Twitter post'), and explicitly enumerates the interaction types (commenters, quoters, retweeters), leaving no ambiguity about scope. Clearly distinguishes from profile-analysis tools by noting it is not for analyzing individual user profiles.

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 vs paging vs csv) with concrete thresholds, tells users when to use each mode ('Use code execution to analyze the full dataset'), and names the alternative tool for a different use case ('Use getTwitterUser instead'). Also gives rate limit and concurrency guidance.

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

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

The description transparently discloses key behaviors: database-then-API fallback for freshness (>10 days), async behaviors for both paging and CSV modes, the need to poll for an operationId, and recommended follow-up action (code execution for CSV analysis). This is beyond what the readOnlyHint/destructiveHint annotations already convey. It doesn't mention rate limits or pagination details for the user, but the main behavioral profile is well covered.

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

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

The description is dense and covers multiple modes, but it's presented as a single long block with mixed concerns (mode selection, date guidance, ideal-use cases, cross-tool routing) and uses inconsistent formatting (ALL CAPS emphasis, casual punctuation). Every sentence does carry information, so it's not padded, but it's not broken into scannable sections for an agent 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?

The description covers response modes, caching behavior, date handling, alternatives, and performance optimization. No output schema exists, so the tool's async behavior (operationId, polling via checkOperationStatus) and CSV/paging flow are explained. Misses rate limits and tableName/pageNumber specifics, but schema covers parameter semantics.

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 is very detailed with full descriptions for responseType, limit, fields, startDate, tableName, pageNumber, userPrompt. The description adds complementary usage guidance (fast vs paging vs csv tradeoffs, when to use each, code execution suggestion for CSV) and clarifies the default responseType and how to poll for async results. The description also emphasizes the `fields` parameter for performance, which is a strong semantic addition 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 verb and resource: 'Get quote posts' for a specific Twitter post, with distinct modes (fast, paging, csv). It explicitly distinguishes itself from getTwitterPostRetweets, which eliminates ambiguity for an agent deciding between sibling tools. The purpose is unmistakable.

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

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

The description explicitly says when to use fast vs paging vs csv modesebb, provides a concrete alternative ('use getTwitterPostRetweets' for retweets), and explains when to invoke CSV mode with code execution for analysis. It also gives date-filter guidance and warns about the current year. This is comprehensive 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 declare readOnlyHint=true and destructiveHint=false, and the description reinforces this with 'safe, read-only tool.' It further discloses database-only access, the 300-result cap, async polling via operationId, the requirement to omit startDate unless explicitly requested, and the 2026 date-never-before behavior. This adds substantial behavioral context beyond the annotations.

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

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

The description is well-organized into FAST/PAGING sections and front-loads the core purpose, but it is quite verbose. The all-caps 'IMPORTANT!!!!!' and the unhelpful phrase 'Results include guidance for full mode' add noise. Still, most sentences earn their place by conveying necessary operational detail.

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

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

Despite having 14 parameters and no output schema, the description covers both execution modes, return mechanics (direct results vs. operationId), pagination, date-filter rules, and the sibling tool to avoid. An agent has everything needed to invoke the tool correctly in both simple and multi-page 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?

With schema description coverage at 64%, the description compensates by explaining how limit works ('use limit=5'), when to use responseType='paging', the meaning of tableName/pageNumber for subsequent pages, and the critical postId constraint (numeric string, not URL). The optional fields performance tip and date-format warning also go 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 begins with a specific verb and resource ('Get retweets of specific post') and immediately distinguishes the tool from a sibling ('NOT for quotes - use getTwitterPostQuotes'). It also frames the use case ('analyze post amplification patterns'), so an agent can tell exactly what this tool does and what it is not for.

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

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

It explicitly names the alternative for quotes (getTwitterPostQuotes) and states the condition for using that instead. It also provides clear guidance on fast vs. paging modes, when to pass startDate, and how to handle relative dates with a current-year check. This is far beyond a generic 'use this for retweets' statement.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description aligns by stating 'This is a safe, read-only tool.' It adds valuable behavioral detail: the fallback from database to external API, async behavior for paging/csv, and the auto API fallback for fresh data. This goes beyond the annotations, providing meaningful context about how the tool operates internally.

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 sections (FAST, PAGING, CSV, CODE EXECUTION, FIELDS, IMPORTANT note). It front-loads the core purpose and modes, and each section adds necessary detail for a complex tool. While verbose, it avoids redundancy and earns its length given the 15 parameters and three response modes.

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 parameters, three response modes, async behavior, and no output schema, the description covers all critical aspects: how to get data, what fields are returned by default, how to request more fields, date handling, safety, and fallback logic. An agent has everything needed to invoke it correctly across all modes.

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

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

Schema coverage is 67%, and the description compensates thoroughly. It explains responseType modes, limit caps, fields categories with examples, date filtering (omission vs explicit), userPrompt importance, forceLatest warnings, pageNumber/tableName mechanics, and pageNumberEnd. Every parameter is either covered by the schema or elaborated here, giving the agent full understanding of how to use them.

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 posts from author by username') and immediately distinguishes the three response modes. It clearly differentiates from sibling tools like getTwitterPostsByKeywords and getTwitterPostsByIds by focusing on author-based retrieval. The purpose is unambiguous and action-oriented.

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

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

The description provides explicit guidance on when to use each response mode (fast for direct results, paging for large datasets, csv for bulk analysis) and when to use code execution. It also gives date-handling instructions (omit for all posts, only pass explicit ranges) and warns about year miscalculation. It doesn't explicitly contrast with alternative tools like getTwitterPostsByKeywords, but the context is clear enough for correct 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, openWorldHint, idempotentHint, and destructiveHint=false, covering safety. The description adds valuable behavioral context beyond those annotations: it explains the lookup order (database first, then external API in parallel), that not-found IDs are omitted, and that results are returned directly. This enriches the agent's understanding 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 lengthy but well-structured, with the core purpose front-loaded and performance/usage notes clearly separated. While it could be trimmed, every section adds meaningful guidance (e.g., field choices, safe-read confirmation). It is dense but not redundant.

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

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

Given there is no output schema, the description adequately covers return structure (results array with id, text, authorId, createdAt, metrics), data source behavior, and the omission of not-found IDs. It does not detail error cases or rate limiting, but the provided information is sufficient for an agent to decide and invoke correctly.

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

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

Schema description coverage is 63%, and the description adds little beyond what the schema already documents. The postIds and fields parameters have detailed descriptions in the schema highlighting behavior and available options; the description repeats these rather than extending them. Undocumented params like _isTrial, _requestId, _trialToken remain unexplained, and the description does not compensate for those 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 clearly states the tool gets multiple Twitter posts by numeric IDs, specifies the quantity range (1-100), and explicitly differentiates from getTwitterPostsByKeywords by stating 'NOT for search'. This makes the purpose and boundary distinct.

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

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

It provides explicit when-to-use guidance ('Use when you have multiple exact post IDs'), explicitly excludes search ('NOT for search - use getTwitterPostsByKeywords'), and even suggests performance benefits over multiple single-ID calls. This fully informs the agent's choice.

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 far beyond the annotations by explaining internal behavior: first searching the database and then falling back to the external API, returning operation IDs for async operations, supporting different response modes, and handling date filters (including a warning about the current year 2026). It also discloses that query operators like from: and lang: are stripped, and that the tool is safe and read-only, consistent 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 with headers for each area (response modes, query syntax, sort, filters, fields, and special notes). The length is justified by the tool's complexity, and it uses pros/delimiter examples. However, some details (e.g., query syntax restrictions) are repeated from the schema, and the 'IMPORTANT current year' block adds a slight diversion from the tool's core behavior, so it's more comprehensive than concise.

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 the tool has 21 parameters, multiple asynchronous modes, and no output schema, the description is extremely thorough. It covers the default return fields, the available field categories, how to paginate via pageNumber/tableName and checkOperationStatus, how to handle CSV output (download and analyze via code execution), and clear disclaimers about safety/read-only. Almost everything an agent needs to correctly invoke it is explained.

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 not present in the input schema: the effect of the `limit` parameter varies by responseType (cap for fast mode, total export cap for paging/CSV), query syntax nuances (forward slashes become spaces, AND/OR/NOT must have terms on both sides), the FIELDS parameter grouping, and the guidance to pass `startDate`/`endDate` only when the user explicitly requests a date range. These are practical, non-schema-derived semantics.

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

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

The description opens with a clear, specific goal: 'Search posts by keywords.' It also explicitly disambiguates from the sibling getTwitterPostsByIds ('NOT for URL lookups - use getTwitterPostsByIds.'), making the tool's scope immediately distinguishable.

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 describes when to use each responseType (fast, paging, csv), suggests code execution for CSV analysis, and names the alternative tool for URL lookups. It also states ideal use cases (sentiment analysis, trend detection, content analysis), giving agents clear conditional guidance. The only small gap is not specifying when other siblings like getTwitterPostsByAuthor might be preferred, but the main routing 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds the return shape with notable fields like authenticity_score and inauthentic_type, and warns about 'tweetCount' not 'statusesCount,' but it doesn't mention rate limits, caching details, or authorization requirements, which prevents a 5.

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

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

The description front-loads the core purpose and usage guidance well, but then the field list is nearly duplicated from the schema, making the text longer than needed. It remains structured and the important bits are first, but the repeated field enumeration costs it a higher score.

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 (2 required), no output schema, and many siblings, the description covers the essential purpose, identifier handling, field selection, and return content. It doesn't explain internal params like _trialToken or _requestId, but those are not critical for an agent to call the tool correctly. The absence of an output schema is partially mitigated by the return-field note.

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

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

Schema description coverage is 67%, so the description must compensate. It clarifies the two supported identifier types and their context, lists all available fields and default fields, and pinpoints the 'tweetCount' naming pitfall. It doesn't detail userPrompt or forceLatest, but those are already well-descriptive in the schema.

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

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

The description clearly states the verb+resource: 'Get Twitter user profile by ID or username.' It explicitly explains identifierType and directly distinguishes itself from the sibling tool searchTwitterUsers by saying to use the latter for fuzzy searches or person names. This avoids ambiguity and establishes its place among siblings.

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

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

It gives explicit when-to-use conditions: when you have a precise username or numeric ID, use this tool; for fuzzy names, switch to searchTwitterUsers. It also explains when to use the fields parameter and the default behavior, so the agent knows exactly when to invoke and how to tailor the call.

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

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

The description adds substantial behavioral detail beyond the annotations: result caps, async polling, CSV/S3 flow, cache freshness threshold, forceLatest costs, and the critical totalRows vs totalDataCount interpretation. These are consistent with the readOnlyHint/destructiveHint annotations and materially reduce agent mis-inference.

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 an overlong wall of ampersands and uppercase labels, longer than necessary for the information added. It interleaves critical caveats with general prose, and much of the field documentation duplicates what the schema already declares. Bulleted sections or a shorter mode table would make it much easier to scan.

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

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

For a tool with 14 parameters and no output schema, the description addresses key questions: default mode, result caps, polling, CSV/S3 path, and how to reason about totals. It does so without covering the full return shape or error conditions, and the paging size inconsistency is a small but confusing 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?

With schema coverage at 79%, the input schema already carries most parameter meaning; the tool description usefully adds data-freshness behavior, partial-result semantics, and the totalRows/totalDataCount warning. The value is tempered by a page-size conflict: the description says 1000/page with default fields, but the schema says paging returns 100/page.

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 line is a clear, specific verb+resource declaration: 'Get Twitter user connections (followers or following).' It immediately distinguishes the tool from sibling Twitter tools (e.g., getTwitterUser, getTwitterPostsByKeywords) by stating the relationship direction.

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 supplies clear usage context via the 'Ideal for: network analysis, audience demographics, engagement patterns' sentence and through explicit mode guidance (fast vs paging vs csv), including when to use forceLatest sparingly. It does not explicitly contrast this tool with nearby siblings like getTwitterUser or getTwitterPostInteractingUsers, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint and idempotentHint. Description adds that not-found identifiers are omitted, return format includes count and dataSource, and performance characteristics (can take time for many users). It also notes the field naming correction ('tweetCount' not 'statusesCount'). 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?

Well-structured with sections and front-loaded core purpose. The field list is repeated from the schema, making it somewhat verbose, but each sentence contributes value (e.g., performance notes, alternative routing). Efficient overall despite length.

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