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?

The description adds substantial behavior beyond the annotations: exact return semantics, zero-default behavior, query syntax interpretation, slash handling, trial limits, and a warning about relative-date year miscalculations. It also reinforces the read-only, non-destructive nature captured by 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 core purpose is front-loaded, but the description is overloaded with side details like the full TRIAL ACCESS signup flow and a large 'IMPORTANT!!!!!' date warning. Valuable, but the structure is denser and less clean than it should be.

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

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

The tool has no output schema, yet the description clearly explains return behavior, query syntax, date defaults, filtering, authentication, and edge-case handling. An agent has enough to select and invoke the tool correctly in most real use cases.

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 63%, the description compensates well for the key parameters by explaining query syntax, date formats, defaults, @handle support, field operators, and trial token handling. However, parameters like _isTrial, _requestId, and _trialToken are not individually described in the prose.

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

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

The description starts with a specific verb and resource: 'Count tweets containing a specific phrase within a date range,' and clearly states the return value is a total integer count or zero. This distinctly separates it from sibling retrieval tools like getTwitterPostsByKeywords.

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

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

It explicitly says 'Use for analytics and trend analysis without retrieving full tweet data,' which tells the agent when to choose this tool. However, it does not explicitly name or exclude sibling alternatives, so the guidance is clear but not fully exhaustive.

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

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

Annotations already declare readOnlyHint=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?

Annotations already carry readOnlyHint=true and destructiveHint=false, and the description reinforces this by calling it 'a safe, read-only tool.' It adds meaningful behavior beyond annotations: fast mode returns up to 300 results, paging/csv are async and return an operationId polled via checkOperationStatus, and it disposes trial caching behavior and API fallback. It does not mention rate limits or all internal fallback conditions, but what is disclosed is consistent and useful.

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

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

The description is heavily packed, with useful headings-like blocktext sections for modes, parameters, trial access, and date handling. However, it is lengthy and includes non-essential promotional information about the trial token and an explicit repeated 'THE CURRENT YEAR IS 2026' warning that feels disconnected from the tool definition. It is structured but 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?

This is a complex 15-parameter tool with no output schema, so the description must compensate for that. It does so by listing returned comment fields, explaining all response modes, covering postId format, paging prerequisites, CSV handling, trial restrictions, and default date behavior. Minor gaps remain around services like _requestId and edge cases, but the description is enough for an agent to invoke the tool correctly in the intended cases.

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 definition is decent, and the description adds extra meaning: it stresses the postId strong_id format using the full 'id' value from other tools, recommends omitting date filters by default, clarifies field defaults, and clarifies responseType behavior. With no separate descriptions for startDate/endDate and _isTrial/_ requestId, the description fills important gaps for the main user-facing 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 COMMENT CONTENT (text, likes) for an Instagram post,' followed by the exact returned fields. It also explicitly differentiates itself from the sibling getInstagramPostInteractingUsers by stating that user profiles are NOT covered here, so an agent knows which tool to route profile-focused requests to.

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 text is explicit: use this for reading comments, not for user profiles, and it names the alternative (getInstagramPostInteractingUsers with interactionType='commenters'). It gives guidance on fast vs paging vs csv, tells the agent to omit date filters by default, and only pass them when the user explicitly asks. It also includes trial-mode expectations and an 'Ideal for: reading discussions, sentiment analysis' line.

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 communicate readOnlyHint=true, and the description reinforces the read-only safety profile. It adds meaningful behavioral detail beyond annotations: fast mode caps at 300 results, paging returns an operationId requiring a follow-up checkOperationStatus call, trial access returns only 5 cached results and never triggers live fetching, and CSV export is included. This gives the agent accurate expectations about side effects, limits, and follow-up 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 organized with clear section labels and front-loads the core purpose before diving into modes and access details. However, it is quite long and repeats information that already appears in the input schema, especially around responseType and fields. The trial-access instructions, while useful, add considerable length, so the description earns only a mid-range score for 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 14-parameter tool with no output schema, the description is notably complete. It explains returned user-profile fields, interaction types, response modes, pagination flow, trial constraints, and when to use the sibling tool. An agent has enough information to invoke the tool correctly and understand what comes back without opening additional 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?

Schema description coverage is roughly 79%, so the schema already documents most parameters well. The description adds some useful order-of-operation context, like 'use limit to reduce' and 'call checkOperationStatus IMMEDIATELY', but much of the parameter detail (postId format, responseType values, fields list, pagination requirements) is already present in the schema. The value added beyond the schema is real but not substantial enough to raise the score above the moderate baseline.

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

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

The description uses a specific verb and resource ('Get USER PROFILES of people who interacted with an Instagram post') and clarifies exactly what is returned. It also distinguishes the tool from getInstagramCommentsByPostId by contrasting 'WHO engaged' with 'what people wrote', making sibling differentiation explicit.

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

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

The description gives concrete scenarios for using this tool (demographics analysis, influencer discovery, audience profiling, network analysis) and explicitly names the alternative tool for comment-text/sentiment use cases. It also covers response modes and when to use paging vs fast mode, which is strong 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?

Adds rich behavioral context beyond the annotations: it searches the database first, then falls back to the external API for missing/stale data in parallel, omits not-found IDs, and clears DDC trial mode only returns cached results and never triggers live fetching. The read-only claim in the description is consistent with the annotations, so there is no contradiction.

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

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

The core behavior and usage guidance are front-loaded and highly informative. The description is longer than necessary, repeating some information that already exists in the schema and including a sizable TRIAL ACCESS block that is only tangentially relevant to tool selection or invocation. Still, almost every section adds practical 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 tool with no output schema, the description provides a reasonable summary of the return shape and important runtime behavior such as batching, database-first retrieval, and trial limits. It could be even more explicit about all possible returned fields and error cases, but the combination of description and detailed schema gives an agent enough context to call the tool correctly.

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

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

The description emphasizes the strong_id requirement and the optional fields parameter, which is helpful conceptually. However, most of that detail is already in the schema, and the description does not add much for undocumented internal parameters like _requestId or _isTrial beyond the trial token paragraph. With 63% schema coverage, the description is useful but not a major semantic contributor.

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 operation: get multiple Instagram posts by IDs (1-50 per request), and makes clear it is not a search tool. It also explicitly distinguishes itself from getInstagramPostsByKeywords, which helps an agent pick the right sibling tool easily.

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

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

Gives explicit usage guidance: 'Use when you have multiple exact post IDs' and 'NOT for search - use getInstagramPostsByKeywords.' It also covers the important URL-to-post-ID case, explaining what to do when given an instagram.com/p/... link rather than a post ID.

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

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

Beyond the annotations' readOnlyHint and destructiveHint, the description discloses meaningful behavior: 'First searches database, then external API if data is stale or missing,' mentions auto API fallback, polling via checkOperationStatus, CSV-to-S3 links, trial limitations of cached-only data, default return fields, and the forceLatest cost/latency warning. This is far more transparency than the annotation alone provides and helps the agent predict side effects and latency.

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

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

The description is front-loaded with the core search statement and response modes, and most sentences carry useful information. However, it is substantially over-written: trial-token setup details, repeated examples, all-caps calls like 'IMPORTANT!!!!!', and near-duplicate lists of fields and ideal use cases make it harder to scan quickly. It is more thorough than concise, so not every sentence earns its place.

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

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

There is no output schema, and this description compensates well by documenting default returned fields, response modes, polling via operationId, pagination semantics, limits, date handling, field groups, trusted use cases, and trial behavior. It also names the correct alternative tool for post ID and URL lookups. Given the tool's 15-parameter complexity, operationally important edge cases are covered comprehensively.

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 by explaining query syntax with AND/OR/NOT, quoted phrases, parentheses, @handles, forward-slash handling, and date parameter usage with YYYY-MM-DD. It also enriches responseType, limit, fields, tableName/pageNumber, and userPrompt beyond the schema. It loses a point because underscore-prefixed parameters such as _isTrial, _requestId, and _trialToken are only partially clarified, leaving a small but real ambiguity.

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

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

The description starts with a precise verb-plus-resource statement: 'Search Instagram posts by keywords with two response modes,' and specifies that it searches both captions and video subtitles. It clearly differentiates itself from the sibling tool for ID/URL lookups by stating 'NOT for URL lookups or post ID lookups - use getInstagramPostsByIds instead,' so an agent can distinguish selection with confidence.

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 via 'Ideal for: content analysis, hashtag trends, brand monitoring' and explicit alternatives/exclusions via 'NOT for URL lookups or post ID lookups - use getInstagramPostsByIds instead.' It also explains when each response mode is appropriate: fast, paging, and CSV, which is enough to route the agent to the correct behavior.

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 readOnlyHint and destructiveHint already in the annotations, the description's job is to add texture, and it delivers: async pagination with polling, the checkOperationStatus polling path, S3 links, auto API fallback for fresh data, trial-mode only cached results (no live fetching), and inclusion of date-accumulation advice about the year. There is a minor internal inconsistency about two-vs-three modes, but it does not amount to an annotation contradiction.

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

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

The description is a wall of dense text with over-capped keys (FAST, PAGING, CSV, FIELDS, TRIAL ACCESS), repetitive advice ('this is a safe, read-only tool' — already in annotations), unnecessary marketing ('Sign up at...'), and an advisory paragraph about code execution. It does front-load the main verb-resource-modes idea, but every sentence does not earn its place; the last paragraph with free trial details is far too long for a tool description.

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

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

For a tool with 16 parameters and no output schema, the description covers many of the behavior-heavy paths: response modes, pageNumber/tableName sequencing, payload tables, operationId polling, and range filtering. Yet it neglects to document the forceLatest parameter, shows no output format beyond the minimum default fields, and sidesteps how to obtain the API token for non-trial use, unnecessarily marked with openWorldHint and checkAccessKeyStatus siblings. Serviceable but incomplete.

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 does compensate for a chunk of that gap by explaining identifierType, responseType behavior, limit caps in each mode, the exact default fields (id, caption, username, createdAtDate), and the recommendation on startDate/endDate. However, it ignores the CRITICAL-for-accuracy userPrompt parameter that appears prominently in the schema, an earlier decision that leaves important meaning in the schema rather than up when required. The parameter explanations are helpful but not comprehensive.

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 posts from Instagram user by ID or username,' precisely states the verb, resource, and scope, distinguishing it from sibling tools focused on keywords, post IDs, or other platforms. However, the first paragraph trips over a factual slip — it claims 'two response modes' and then enumerates three (fast, paging, csv) — which slightly saps confidence from an otherwise clear purpose.

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

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

Inside-tool choices are well covered: the description tells when to use identifierType='id' vs 'username', when to use fast versus paging versus csv, and explicitly says to omit startDate/endDate unless the user requests a range. But there is no explicit guidance about tool selection across siblings (e.g., 'for posts by content, use getInstagramPostsByKeywords'), and no exclusion statements telling the agent when NOT to use this rather than an alternative.

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

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

Annotations declare readOnlyHint:true and are not contradicted — the description aligns ('safe, read-only'). Beyond annotations, it adds real behavioral details: trial tokens return only up to 5 cached database-only results without triggering live fetching, token validity is 5 days, and the fields/return shape is listed. Only failure/not-found behavior is omitted.

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 opening sentences are perfectly front-loaded: purpose, identifierType rule, when-to-use vs alternative. However, roughly a third of the text is a trial-signup tutorial (POST URL, headers, JSON body, validity, result limits) and the return-list duplicates the schema's fields catalog — meaningful signal lost in 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?

Since there is no output schema, the description provides a concrete return shape and covers the main decision axes: exact vs fuzzy lookup, numeric-id vs username, fields for perf, and trial caching. It doesn't mention userPrompt (CRITICAL per the schema) and omits not-found outcomes, but the invocation requirements are still reconstructable from it.

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

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

Schema coverage is 67% with thorough descriptions on the public core (identifier, identifierType, fields, userPrompt, forceLatest, feedback), so the baseline 3 applies. The description largely repeats the schema rather than adding meaning, and the three undocumented params (_isTrial, _requestId, _trialToken) are not clarified either.

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 pins down the exact action and resource: 'Get Instagram user profile by ID or username.' It also differentiates itself from sibling tools by explicitly stating that person-name or fuzzy lookups should go to searchInstagramUsers, so an agent can pick this tool vs. the search variant.

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 both an explicit precondition ('Use ONLY when you have the precise username') and an alternative (searchInstagramUsers for person names or fuzzy search). It also prescribes how to choose identifierType for numeric id vs username. That lands in explicit when-to-use/when-not-to-use territory.

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

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

Beyond the readOnlyHint, the description discloses important behavioral traits: automatic API fallback, 1-week data freshness checks, async paging, totalRows vs totalDataCount caveats, trial limitations, and cost increases from forceLatest. This gives an agent useful context about what the call can observe and when results may be partial.

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

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

The description is well-structured with labeled sections and front-loaded purpose, but it is quite long and includes product/trial documentation and a feedback-field explanation that go beyond the core tool behavior. It earns its length to some degree given the complexity, but it is not an example of concise writing.

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 many important invocation paths: fast vs paging, limits, fields, data freshness, forceLatest, trial restrictions, and the totalRows vs totalDataCount interpretation. It leaves some gaps such as the CSV response mode, but overall it is substantially complete for a complex, schema-rich tool with no output schema.

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

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

Schema description coverage is 79%, and most parameters such as connectionType, limit, fields, responseType, and forceLatest already have meaningful descriptions in the schema. The long description mostly reinforces those but does not add substantial new per-parameter semantics, so a score of 3 is appropriate.

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

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

The description states a specific verb and resource: 'Get Instagram user connections (followers or following)' and defines both connectionType values with clear semantics. It is easy to distinguish from sibling tools because it names the exact data source and the two relationship directions.

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 invocation guidance: choose fast vs. paging, use the limit parameter to reduce results, use the fields parameter for performance, and only pass forceLatest=true when the user explicitly wants fresh data. It does not explicitly name sibling tools or describe when not to use this tool, so it stops short of full alternative-selection 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?

It discloses read-only safety, paging/caching behavior, async operation IDs, CSV export flow, trial limitations, and important date-related context. These behavioral details go well beyond the annotations and help the agent predict side effects and response behavior. 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 front-loaded with the core purpose and then organized into labeled sections for modes, query syntax, filters, and fields. Though somewhat long, most sentences add value for a tool with 15 parameters and no output schema. Minor redundancy exists around uniqueness and returned data shapes.

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 the lack of an output schema, the description explains return shapes, async pagination workflow, operation IDs, uploading and CSV link behavior, and auth/trial constraints. For such a complex tool with many response modes, it gives an agent enough context to select and invoke it correctly in most cases.

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 expands on the schema with full query syntax, boolean examples, phrase handling, responseMode behavior, pagination mechanics, and available aggregated fields. The schema already covers 67% of parameters, but the description compensates with practical usage semantics and caveats such as default field lists and caps.

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 operation: finding USERS who authored Instagram posts matching keywords, with a clear USE CASE and the unique/deduplicated result type. This distinguishes it from post-returning siblings like getInstagramPostsByKeywords by emphasizing that returned entities are 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?

The description gives clear usage contexts: what the tool is for, which response mode to choose, when to omit date filters, and when to use forceLatest. It does not explicitly name alternative tools to prefer for other search types, so it has clear context but no explicit exclusions.

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

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

Annotations already declare read-only, idempotent, and non-destructive, but the description adds valuable context: it first searches the database and then fetches from the external API if missing or stale, trial access is limited to cached results, and live fetching is never triggered in trial. This exceeds what annotations alone provide.

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

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

The description is longer than average due to trial access and auth instructions, but it front-loads the core purpose, ID format, cache behavior, and exclusion. The trial block is clearly labeled and necessary for first-time use, so the length is justified despite some redundancy with annotations.

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

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

Without an output schema, the description provides adequate return-field expectations (id, body, author, parent ids, score, timestamps). It covers required parameter semantics, optional field selection, force-latest behavior, trial limitations, and authentication. No practical information needed to invoke this tool 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 moderate (57%), but the description adds meaning beyond the schema by specifying default field values, caching/force-latest semantics, and the difference between bare and t1_-prefixed IDs. The 3 undocumented parameters (_isTrial, _requestId, _trialToken) are not explained in the description either, though the trial token usage is addressed through the Bearer-token explanation.

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 a single Reddit comment by its ID'—states a specific verb and resource, and the description immediately disambiguates from the sibling keyword-search tool. It also clarifies accepted ID formats, leaving no ambiguity about what input the tool takes.

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 'NOT for searching - use getRedditCommentsByKeywords for keyword search', naming the alternative precisely. It also explains the cache/API fallback behavior and optional fields for performance, giving clear guidance on when and how to call this tool.

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

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

Goes well beyond the read-only and non-destructive annotations by disclosing database-only search behavior, trial caching without live fetch, result caps, async paging, operationId polling, CSV S3 output, and query operator stripping. This gives a clear picture of what actually happens beyond obvious read-only semantics.

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

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

The description is well-structured with labeled sections and front-loaded mode guidance. It is longer than necessary because portions of the query syntax are repeated in the schema, but most extra length earns its place by covering pagination, trials, and date handling.

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 14-parameter tool with no output schema, this description covers all important behavioral context: return behavior per mode, pagination details, CSV handling, default fields, query construction, date restrictions, and trial limitations. The coverage is remarkably 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?

At 64% schema coverage, the description compensates well by explaining date filter behavior, response modes, result caps, subreddit filtering, and default fields. Some internal parameters like _isTrial, _requestId, and _trialToken are not individually explained, though the surrounding trial prose makes their purpose inferable.

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 clear statement: 'Search Reddit comments by keywords' and adds that it searches comment body text. This distinguishes it from sibling tools like getRedditPostsByKeywords and getRedditCommentById without needing to inspect the schema.

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

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

Provides explicit guidance for choosing fast, paging, and CSV modes, advises when to omit date filters, and names ideal use cases such as sentiment analysis and trend analysis. It does not explicitly compare against sibling Reddit tools, so it stops short of fully ruling out alternatives.

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

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

The description adds substantial behavioral context beyond the readOnlyHint: it reads from database first, falls back to an external API when stale, supports async operationId polling, explains trial-mode cache-only results, and documents the limit/cost trade-offs of forceLatest. For a tool that is approachable, safe, read-only, it clearly tells the agent what happens under the hood without "surprising" side effects.

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 for an 18-parameter tool with three response modes and multiple advanced behaviors, almost every sentence carries operational value. It is not perfectly formatted — much of it is dense run-on text with very loud flags like 'IMPORTANT!' — but the key details (modes, date-current-year warning, trial access) are front-loaded and therefore functionally accessible.

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

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

There is no output schema, but the description defines default return fields, response modes, polling behavior, and async result limits. It also covers the auth/trial flow, query syntax, date pitfalls, subreddit filtering, and the cache/fallback path. For a tool of this complexity, all operational essentials are present.

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

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

Schema coverage is 72%, but the description compensates extensively with a full query syntax guide, boolean operators, quoted-phrase behavior, date-filter rules (YYYY-MM-DD), and precise guidance on when to omit startDate/endDate. It also explains hidden/trial token usage, tableName/pageNumber for pagination, and fields optimization. This is far more than the schema provides on its own.

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 posts by keywords' and identifies exactly what is searched (post titles and selftext). Among siblings like getRedditCommentsByKeywords or getRedditSubredditsByKeywords, the tool is clearly positioned as the Reddit-post-search entry point. The only small wrinkle is that it says 'two response modes' while actually listing three, but the core 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?

It gives concrete when-to-use guidance per response mode: FAST for direct results, paging for async and paginated access, CSV for full-dataset analysis with code execution. It also lists ideal use cases such as sentiment analysis and subreddit trends. It does not explicitly route away from sibling tools like getRedditCommentsByKeywords, but the mode-level guidance is strong and clear.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description credibly describes behaviors beyond that: 'First searches the local database for both post and comments, then external API if data is stale or missing', auto API fallback in fast mode, async paging returning an operationId for polling, and the internal side-effect of 'creates cached for comments'. It also discloses trial stage limits ('never triggers live fetching') and the cost/latency warns of for forceLatest. No contradictions with readOnly/external API hints.

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

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

The description is long, but it is well-structured: front-loaded purpose, capitalized mode blocks, dedicated sections for response structure, paging details, and trial access. There is some duplication between the earlier PAGING paragraph and the later 'FIRST CALL / SUBSEQUENT PAGES' section, but each section does add operational detail that earns its place given the lack of an output 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?

Despite the high parameter count (13), no output schema, and two response modes, the description covers the main operational surface: response structure ({ result: { post, comments }, count, guidance }), paging flows, field defaulting, and the auth/trial protocol. Gaps: the 'csv' responseType referenced in the schema is never explained in the description, and not every param (_isTrial, _requestId, feedback) has its behavior clarified. Still, an agent would successfully invoke the tool for typical fast and paging use cases.

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

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

Schema coverage is 77%, just below the high-coverage baseline, and the description compensates well: it gives field-selection examples with minimal vs content-analysis field sets, explains limit caps (300 fast vs 500K paged/CSV), details the tableName/pageNumber first-and-subsequent-page flow, and explains the trial token's lifecycle. A few internal parameters (_isTrial, _requestId) remain unexplained, and the CSV responseType is only described in the schema, not in the description.

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

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

The description states a specific verb and resource: 'Get Reddit post by ID with its comments' and adds the key fact that 'both the post data and comments' are returned in a single response. This clearly distinguishes it from sibling tools like getRedditCommentById (single comment) and getRedditPostsByKeywords (keyword search, not ID-based). The first sentence alone gives an agent everything needed to route correctly.

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?

Very explicit within-tool guidance: responseType defaults, when to use limit, when to use paging with pageNumber/tableName, and when NOT to use forceLatest ('USE SPARINGLY... Only use when explicitly required'). It does not, however, name sibling alternatives or state when to choose a sibling tool instead, so cross-tool selection guidance is implied rather than explicit.

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

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

It goes well beyond the readOnlyHint/destructiveHint annotations by documenting cache fallback, API fallback, pagination via operationId, the up-to-300 fast-mode limit, trial limitations, and the 'OMIT startDate/endDate by default' behavior. It also clearly calls it a safe, read-only tool, consistent with the annotations.

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

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

The description is well organized into labeled sections and front-loads the core behavior, but it is long and repeats query syntax, fields, limit, and responseType details already documented in the schema. The 'IMPORTANT!!!!!' and embedded tutorials for trial access add useful information but make the description heavier and less 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?

For a 15-parameter tool with no output schema, the description covers the key richness: response modes, pagination/polling, field selection, query grammar, filters, auth/trial, and caching caveats. Some internal parameters like _requestId and _isTrial remain unexplained, but the description gives enough context to invoke the tool successfully in the main scenarios.

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

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

The description adds meaningful parameter guidance beyond the schema's strong 80% coverage, especially the requirement that aggregate fields must be explicitly requested, the current-date/year warning, and the default behavior to omit date filters unless the user asks. The query-syntax section is largely repeated from the schema, so it adds less incremental value.

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

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

The description starts with a specific verb+resource: 'Search for SUBREDDITS where Reddit posts match keywords' and clarifies the output as 'unique, deduplicated subreddit profiles'. This distinguishes it clearly from sibling tools that return posts, comments, or users.

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 strong context for when to use the tool: keyword-based subreddit discovery with fast vs paging modes. However, it does not explicitly mention when NOT to use it or name alternatives such as searchRedditSubreddits, getRedditPostsByKeywords, or getRedditCommentsByKeywords, leaving some alternative-routing to the agent.

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

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

Beyond the annotations already declaring read-only, idempotent, and non-destructive behavior, the description adds substantial behavioral context that annotations cannot convey: cache-first lookup with external API fallback, fast mode's 300-result cap, async paging returning an operationId for polling, and trial-mode throttling (5 cached results, no live fetch). This is exactly the kind of behavior disclosure that helps an agent predict what calling the tool will do.

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

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

The description is well-structured with helpful section headers (FAST, PAGING, RESPONSE STRUCTURE, FIELD SELECTION, TRIAL ACCESS) and is front-loaded with the core statement. However, the TRIAL ACCESS block is lengthy product-pitch content that is platform-wide boilerplate rather than tool-specific information, making the description substantially longer than needed for the core call semantics.

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 13-parameter tool with no output schema, yet the description covers the essentials: the exact response shape ({ results: { subreddit, posts }, pagination }), both response modes with their limits, the pagination handshake, caching behavior, auth requirements for trial use, and performance optimization via field selection. Nothing an agent needs to know to call it correctly on its first attempt 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 already describes 77% of parameters in detail, including responseType and field selection, so the description's main added value is elsewhere: it explains the undocumented _trialToken parameter flow end-to-end (where to POST, what header to use, what the token looks like, validity window). It also synthesizes how limit, responseType, and the field parameters interact in a way the schema does not make obvious.

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 is a specific verb+resource statement — 'Get Reddit subreddit by name with its posts' — which precisely scopes the tool's function. It distinguishes itself from sibling tools like getRedditSubredditsByKeywords and getRedditPostWithCommentsById by making 'by name' and 'with posts' explicit from the outset.

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 strong usage guidance for selecting response modes: fast for direct results (with limit reduction), paging for async paginated retrieval, plus conditional warnings for forceLatest. It clearly implies when this tool is the right choice for Reddit data, but it never explicitly contrasts with sibling alternatives like getRedditSubredditsByKeywords, which would have been the missing final row.

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

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

Beyond the readOnly/idempotent annotations, the description adds valuable behavioral detail: trial requests return only cached database results, never trigger live fetches, and are limited to 5 results. It also explains token validity, Bearer token usage, and the need for sign-up to get full live data. This goes well beyond what the annotations already declare.

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

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

The core action and the most important usage rule are front-loaded, and the field list is organized into clear categories. The description is long, however, and much of the available-fields content also appears in the schema. The trial-access block is detailed and useful, but it makes the description feel 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?

With no output schema, the description compensates by stating the return shape: a single user profile with id, username, karma metrics, account flags, and profile details. It also covers default behavior, caching, trial limitations, authentication, and performance considerations such as forceLatest. There is enough context for an agent to invoke this tool correctly in both trial and full-access scenarios.

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

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

The description adds useful parameter-level guidance: what needs to be the default fields list, how to form the username, and what field categories are available (core, karma, status, profile, timestamps). It does not explain the undocumented internal parameters (_isTrial, _requestId, _trialToken), and some of the field lists are duplicated from the schema, so it falls short of 5.

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

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

The description starts with a specific verb and resource: 'Get Reddit user profile by username.' It goes on to describe what is returned (karma breakdown, account status, profile info), and it clarifies the correct username format by excluding the `u/` prefix. This makes the tool easy to distinguish from keyword-based Reddit searches and comment-level tools.

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

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

The description gives clear usage context: it is a single-user profile lookup, expects a username without the `u/` prefix, and supports an optional fields parameter for performance. It also explains trial-mode behavior. It does not explicitly name sibling alternatives like getRedditUsersByKeywords or searchRedditUsers or state when not to use this tool, which keeps it from being 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 heavily supplements the annotations by disclosing deduplication, the read-only safe nature, caching behavior, async paging with tableName mechanics, trial limitations (5 cached results), query operator stripping, and aggregate-field requirements. This far exceeds the minimal annotation hints and gives the agent accurate expectations for actual execution.

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 overwhelmingly long, mixing a utility manual with auth details, trial access instructions, and current-year warnings in ALL CAPS. While consistently organized with plain-text section headers, it is verbose and includes peripheral information (post URL for trial token) that an agent likely won't need during normal invocation unless handling auth. It should be trimmed significantly.

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 its verbosity, the description is technically complete for this complex tool: it covers query syntax, boolean logic, field operators, filters, response modes, paging protocol including first/subsequent/bulk calls, aggregate fields, and trial restrictions. Given the absence of an output schema, this degree of context lets an agent correctly call the tool and parse asynchronous operation IDs. No critical operational detail is missing.

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

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

Schema description coverage is 81%, so the baseline is 3. The description meaningfully improves upon the schema by explaining the relationship between limit and responseType caps (300 fast vs 500K paging/CSV), the requirement to explicitly request aggregate fields, the nuance of tableName/pageNumber/pageNumberEnd usage, and the subreddit filter's 'without r/' rule. It stops short of fully documenting internal params like _trialToken and _requestId, so it doesn't earn a 5.

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

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

The description opens with a specific verb-resource pair ('Search for USERS who authored Reddit posts matching keywords') and clearly distinguishes it from sibling tools like getRedditPostsByKeywords and getRedditUser by focusing on deduplicated user profiles rather than posts or single-user lookup. The use case statement reinforces what the 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 explicit guidance on when to use the response modes (fast='Best for quick lookups', csv='Best for bulk export'), when to omit date filters ('OMIT by default, only use if user explicitly requests date range'), and cautions about relative dates and current year. However, it does not explicitly contrast this tool with sibling alternatives like searchRedditUsers, so the usage guidance is clear but not fully exclusionary.

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 behavior beyond annotations: direct vs async pagination, CSV download flow, operation polling, auto API fallback for fresh data, trial-token limits, caching forceLatest caveats, and date filtering defaults. It also details the current-year hazard and explicitly reinforces the read-only nature, which complements the annotations without contradiction.

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

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

The description is front-loaded with the core purpose and provides useful sections, but it is long and repeats some information, such as return fields ('RETURNS COMMENT DATA' and 'Optional fields' listing the same fields), and the substantial trial/auth block could have been tightened. It's informative, not succinct.

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 complexity of 15 parameters, multiple response modes, async polling, and no output schema, this description is remarkably comprehensive. It covers result limits, pagination, CSV processing, date handling, auth, trial limitations, read-only behavior, and execution guidance, leaving few practical invocation details unstated.

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

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

The description adds meaning for responseType, explaining fast/paging/csv modes and their operational tradeoffs, and clarifies limit behavior across modes and the paging pageNumber/tableName relationship. It also explains field-usage defaults. With 67% schema coverage, the description offset the gaps but doesn't fully explain every undocumented internal parameter such as _isTrial or _requestId.

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

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

The description states a specific action and resource: 'Get COMMENT CONTENT ... for a Tiktok post' and clarifies it returns comment objects with text and metadata. It also names the exact data fields returned, and makes it obvious this is the comment-reading tool for TikTok posts rather than posts, users, or other platforms.

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, listing ideal use cases like sentiment analysis, reading discussions, and engagement analysis. It also explains response-mode selection (fast, paging, csv) and date-filter conditions. It doesn't explicitly name alternative tools to avoid, but the platform and resource scoping is clear enough from sibling names and the description.

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

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

Beyond the annotations, the description discloses concrete behavior: three response modes with specific caps and async operationId flows, pagination semantics, CSV download behavior, default returned fields, cached trial behavior, and the fact that trial results never trigger live fetching. It also explicitly says the tool is safe and read-only, which is fully aligned with the annotations.

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

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

The description is well-structured with labeled sections for each response mode, fields, date filters, and trial access, and it front-loads the core semantics. However, it is also very long and includes some tangentially exploitative details like trial token issuance and the CURRENT YEAR warning, so it is informative more 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 no output schema, the description still covers default return fields, async result handling, polling with operationId, paging behavior, CSV download flow, and the distinction from sibling tools. For 15 parameters and three modes, the description is complete enough for an agent to select and invoke this tool correctly without needing more 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 adds valuable parameter semantics: it explains responseType modes and their limits, hashtags syntax and OR logic, the meaning of the pageNumber/tableName interplay for paging, and the purpose of startDate/endDate with an explicit date format. Schema coverage is only 67%, so this contribution is important, though a few hidden or internal params like userPrompt, _trialToken, and _requestId are documented only in the schema.

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

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

The opening states a specific verb and resource—'Search Tiktok posts by hashtags'—and then narrows the exact scope: it searches the hashtags column directly, not post descriptions. It also explicitly distinguishes itself from getTiktokPostsByKeywords and getTiktokPostsByIds, so an agent knows exactly what this tool does and does not do.

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, including ideal use cases like hashtag trend analysis and viral hashtag tracking. It also gives explicit exclusions: 'NOT for keyword/phrase search... use getTiktokPostsByKeywords instead' and 'NOT for URL or post ID lookups... use getTiktokPostsByIds instead.' It additionally prescribes when to use fast, paging, CSV modes and when to pass date filters.

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

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds valuable behavior beyond that: it explains the database-first-then-API retrieval path, direct result return, performance options, and important trial behavior (cached-only results, no live fetching).

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

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

The core behavior is front-loaded and clearly structured, but a long trial-token and sign-up section is included. That is useful, yet it makes the description larger than necessary for agents that already have credentials.

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

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

There is no output schema, but the description lists the main returned result fields and behaviors, including cache fallback, performance tuning, and trial limits. This gives an agent enough context to correctly invoke the tool and interpret common results.

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

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

The schema already describes most parameters well, including `postIds`, `fields`, `forceLatest`, and `userPrompt`. The description reinforces the 1-100 ID limit and caching behavior but does little to fully explain internal parameters like `_isTrial`, `_requestId`, `_trialToken`, and `feedback` beyond their schema comments.

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 multiple Tiktok posts by IDs (1-100 IDs per request)'. It clearly identifies the batch-by-ID operation and distinguishes it from sibling tools that fetch by keywords, user, hashtag, or sound.

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 clear the intended use is supplying post IDs, and it explains when caching vs. live fetching will occur. It also warns about forceLatest and the trial-mode limitations, giving an agent enough context to decide when this tool is appropriate.

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

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

Annotations declare readOnlyHint=true and destructiveHint=false, and the description is consistent with those. It adds meaningful behavioral detail beyond the annotations: async paging and CSV behavior, CSV download via S3, trial requests returning up to 5 cached results without live fetching, and default result fields.

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

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

The description is well-organized in sections and front-loads the essential search/response behavior, but it is quite long and repeats some content already in the input schema, such as responseType mode descriptions and default return fields. It is not a wall of text, but it could be trimmed without losing essential guidance.

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

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

For a 15-parameter tool with only one required parameter and no output schema, the description is remarkably complete. It covers response modes, field choices, async polling, trial behavior, date caveats, and explicit exclusions. There are no major missing pieces that would prevent correct invocation and result interpretation.

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 parameter understanding beyond the schema. It explains boolean query syntax, quoted phrases, @handles, slash-to-space behavior, date format expectations, responseType modes, paging continuation via tableName/pageNumber, and field groups. Given the schema coverage is 67%, this level of supplementary detail is valuable and necessary.

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 and resource: 'Search Tiktok posts by keywords,' and adds that it also searches video transcripts. It explicitly distinguishes itself from getTiktokPostsByIds by stating it is NOT for URL or post ID lookups, making selection unambiguous.

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

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

The description gives strong usage guidance: when to use fast vs paging vs CSV modes, when to pass date filters, and which sibling tool to use instead for ID lookups. It also tells the agent to use code execution for CSV mode and explains trial limits, so an agent knows exactly when and how to use this tool.

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

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

Annotations already mark it as read-only, and the description reinforces that plus adds important behavioral context not visible from the schema: fast vs async paginated vs CSV download modes, operationId polling, caching and forceLatest behavior, and trial-mode restrictions that only return cached results. This goes well beyond what the annotations alone 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 information-dense and starts with the core purpose, but it is considerably longer than necessary and repeats field details that already exist in the schema. The all-caps 'IMPORTANT!!!!!' block and the trial-token signup instructions add length that would be better placed in more structured or platform-level guidance.

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

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

For a complex tool with 15 parameters, three response modes, async polling, and optional trial handling, the description covers the important operational contexts: how many results to expect, how pagination and CSV downloading work, default return fields, date caveats, and trial limitations. The lack of an output schema is partially offset by clearly pointing to checkOperationStatus for async 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?

The description adds genuinely useful meaning to the parameters: the limit cap of 300 in fast mode, default fields, field grouping (Core/Engagement/Media/Content), the source of soundId, and correct usage of startDate/endDate. It does not overdo it because the schema already covers many parameters, but one minor inaccuracy exists: the description lists 'transcriptsJson' under Content while the schema does not include that field.

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 clear verb (Get), a resource (TikTok posts), and a filter (by sound/music), then immediately lists the three response modes. The description also states what the tool is NOT for and names the sibling tools to use instead, so an agent can distinguish it from getTiktokPostsByKeywords and getTiktokPostsByHashtags.

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

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

The description provides explicit when-to-use guidance: it requires a soundId from searchTiktokSounds, warns against using it for keyword or hashtag searches and routes those to the correct siblings, explains when to pass date filters, and documents when to use fast, paging, or CSV response modes. It also gives a practical note about being careful with relative dates in 2026.

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 mark the tool read-only, the description substantially expands the behavioral contract: database-first and API fallback, forceLatest's cost/latency, async operation flow, trial limits, and the current-year date handling pitfall. These are non-obvious details an agent could not infer from the schema or 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 segmented into helpful sections—FAST, PAGING, CSV, FIELDS, TRIAL—and front-loaded with the core purpose. However, it is quite lengthy, repeats details already present in the schema, and includes nonessential trial-signup and date-warning paragraphs. It is organized but not tightly edited.

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

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

For a tool with 16 parameters and no output schema, this definition covers a great deal: modes, default fields, database/API fallback, async polling, trial restrictions, and date-response hints. The main missing piece is the exact JSON response shape, which would have strengthened completeness but does not prevent 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 description coverage is 69%, but the description adds important semantics beyond the schema: how to choose identifierType, what each response mode returns, how limit behaves in each mode, and when not to pass startDate/endDate. Some internal or auxiliary parameters like _requestId, _trialToken, and _isTrial remain unexplained, but the core user-facing parameters receive strong guidance.

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

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

The description opens with a clear verb-resource pair: 'Get posts from Tiktok user by ID or username'. It explicitly covers the two forms of identifier and clarifies the optional response modes, which distinguishes it from sibling tools such as getTiktokPostsByKeywords or getTiktokPostsByHashtags.

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

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

The description gives explicit mode-selection rules for FAST, PAGING, and CSV, including limit capping, polling, and CSV download behavior. It also states the important date-filter rule: omit startDate/endDate unless the user explicitly requests a range. It stops short of naming sibling tools to exclude, but the user-scoped lookup intent is clear.

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

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

Annotations already mark readOnlyHint, idempotentHint, openWorldHint, and no destructive hint. The description adds important behavioral specifics beyond annotations: it is explicitly 'read-only', trial access returns up to 5 cached database-only results and never triggers live fetching, and full result limits require signup. This is valuable contextual behavior an agent cannot infer from annotations alone.

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

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

The description is longer than average because it includes trial-token and signup instructions, but it is front-loaded with the core selection logic and adds meaningful operational details later. The length is justified by the important caching and access constraints, though some trial/setup information could arguably live outside the description.

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

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

Even though there is no output schema, the description specifies what is returned ('single user profile'), enumerates available fields, and explains cache/live-fetch behavior under trial conditions. For a read-only retrieval tool with this complexity, the description gives an agent enough context to invoke it correctly and understand the constraints on results.

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

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

The schema already provides detailed descriptions for many parameters, so the baseline is high. The description adds meaning beyond set: it names the default fields, lists available categories such as id, username, nickname, and engagement fields, and explains the performance trade-off for selecting fields. The internal-only parameters like _requestId and _trialToken remain undocumented, but the main operational parameters are well covered.

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

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

The description states a specific verb and resource: 'Get Tiktok user profile by ID or username.' It also differentiates itself from the fuzzy search sibling by saying 'For person names or fuzzy search, use searchTiktokUsers instead,' so an agent can select it correctly.

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

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

Provides explicit usage conditions: use identifierType 'id' for numeric IDs and 'username' for usernames, and says to use getTiktokUser only with a precise username, naming searchTiktokUsers as the alternative for fuzzy search. It also gives guidance for the fields and forceLatest parameters.

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

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

Annotations already declare the tool as read-only and non-destructive, and the description reinforces this with "safe, read-only tool." It adds substantial behavioral context: results are deduplicated, async modes return operation IDs, trial access is limited to 5 cached results, and forceLatest bypasses caching with increased cost.

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

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

The description is front-loaded with purpose and use case, which is good. However, it is quite long and includes repeated schema information, a calendar warning, trial-token acquisition steps, and several ALL-CAPS reminders that make it weighty. The density is useful, but not every sentence earns its place.

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

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

Given 15 parameters, no output schema, and many sibling tools, this description covers response modes, filtering, field selection, pagination, trial limitations, and when to call other tools. It explains return shapes at a useful level, including operation IDs and S3 links, so an agent can call it correctly without external guidance.

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 moderate, and the description adds meaningful parameter semantics beyond the schema: no leading '#', OR semantics for hashtags, cap behavior for fast vs paging modes, and a reminder that aggregate fields must be explicitly requested. It does not enrich every parameter, but the core parameters receive effective guidance.

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 immediately states a specific verb and resource: "Search for USERS who authored Tiktok posts tagged with specific hashtags." It clearly differentiates from sibling tools by adding "NOT for keyword/phrase search in descriptions - use getTiktokUsersByKeywords instead," making it easy for an agent to select the right tool.

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

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

The description gives explicit when-to-use guidance: quick lookups vs async paging vs CSV export. It also provides an explicit alternative tool for keyword-based searches. The response mode details further help the agent choose the correct invocation path for the user's scale and speed needs.

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

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

The description goes far beyond the annotations by revealing that results are deduplicated, response modes have different execution paths, pagination creates cached tables, forceLatest bypasses cache and increases cost, aggregate fields must be explicitly requested, and the trial mode returns only cache-only results. It also reassuringly confirms the safe read-only nature of the tool.

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

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

The description is highly structured and front-loaded, with bold section labels like USE CASE, RESPONSE MODES, and PAGING MODE DETAILS. However, it is extremely long and repeats many details already present in the parameter descriptions, such as responseType modes and query syntax. The "IMPORTANT!!!!!" year reminder is useful but could be phrased more concisely.

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?

Considering the complexity of 15 parameters and three response modes with no output schema, the description covers everything needed to invoke the tool properly: response mode selection, pagination, bulk fetching, query grammar, date filters, optimization fields, aggregate fields, trial limitations, and even the URL-required trial token. Very little is left to guesswork.

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

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

The description adds significant meaning beyond the input schema, especially for responseType, claiming in the paging mode, pageNumber/tableName coordination, date format YYYY-MM-DD, query boolean syntax, and the need to request aggregate fields. Even though the schema description coverage is 67%, the extra prose fills in critical gaps for parameters that otherwise have no consistent description or that require a sequence of calls.

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 'Search for USERS who authored Tiktok posts matching keywords,' which names the verb, the resource, and the scope. It also provides a USE CASE ('Find users who have posted content about specific topics') and the deduplication behavior. However, it does not explicitly contrast itself with sibling tools like searchTiktokUsers or getTiktokUsersByHashtags, so it stops short of full 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?

There is a clear USE CASE that tells an agent when to select this tool: when users who authored posts on a specific topic are needed. The description also gives mode-level guidance (fast for quick lookups, paging for large sets, CSV for bulk exports). It does not explicitly exclude alternatives, 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, 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?

Beyond the readOnlyHint and destructiveHint annotations, the description discloses important behavioral traits: fast vs paging/csv execution, dependency on the external API fallback when stale, that trial mode returns cached data only, and that startDate should generally be omitted. It also warns about relative-date year errors. This gives the agent a rich picture of what the tool does.

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 verbose but well-structured with clear sections for FAST, PAGING, CSV, date handling, and trial access. Every main mode is explained directly and the important warnings are called out. Some looser elements like the long trial-access instructions and social media signup details could be trimmed without loss, but overall the organization makes the complexity navigable for an agent.

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

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

Given the high complexity (14 parameters, three response modes, no output schema), the description addresses all relevant use points: how the fallback works, date filters, paging mechanics, CSV flow, limit handling, and trial restrictions. It should be sufficient for an agent to call correctly in most realistic 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?

While the schema itself covers 71% of the parameters, the description adds substantial meaning beyond raw names and types. It explains responseType modes, limit caps, when to pass startDate, forceLatest behavior, paging parameters, and the userPrompt emphasis. The description also clarifies that 'fields' can optimize performance and lists examples, going well beyond the schema-provided 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 'Get comments (replies) to specific post' with a specific verb and resource. It further differentiates itself by explicitly saying 'NOT for quotes - use getTwitterPostQuotes', making it easy for an agent to choose correctly even among similar Twitter scoring 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 thorough usage context: ideal use cases like sentiment analysis, discussion themes, and community engagement, and explicitly contrasts with getTwitterPostQuotes. It also explains mode selection (fast, paging, csv), caching behavior, and date-filter instructions, so an agent knows exactly when to use this tool vs alternatives.

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

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

The description openly discloses substantial behavioral context beyond the given annotations: automatic DB-freshness checks with API refresh, auto API fallback, async operationId/polling semantics, cached-table paging behavior, trial limitations, and the latency/cost trade-off of forceLatest. Everything aligns with the annotations (readOnlyHint=true, destructiveHint=false), including the explicit statement 'This is a safe, read-only tool'.

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

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

The description is long (primarily due to genuinely complex 3-mode semantics) but highly structured with labeled sections (FAST/PAGING/CSV, PAGING MODE DETAILS, FORCE LATEST, TRIAL ACCESS) that make it easy for scan. It loses a point because 'Ideal for' and 'Use for' are redundant restatements and the trial-access paragraph is auxiliary boilerplate.

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

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

For a tool with 16 parameters, three response modes, asynchronous polling, and no output schema, the description is remarkably complete: it explains the first-call response (page 1 plus metadata tableName/totalPages/totalRows), subsequent-page requirements, the optional bulk fetch via pageNumberEnd, the polling route for csv (S3 link), and the 300 vs 500K limits. Only the exact data shape gar of fast-mode results is left implicit, and the openWorldHint + field list mitigates that.

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 69% schema coverage, the description meaningfully fills gaps: it clarifies interactionType enum semantics and responseType enum differences, the pagination contract among tableName/pageNumber/pageNumberEnd, and the per-mode limit cap (300 fast vs 500K paging/CSV). Some internal/housekeeping parameters (_isTrial, _requestId, startDate, endDate) remain opaque, and it slightly repeats the schema's field meaning, so it falls short of a 5.

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

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

States a specific verb+resource ('Get users who interacted with a specific Twitter post') with three enumerated interaction types, each clearly defined. The framing 'users who interacted' helps distinguish this from sibling tools that return interaction content itself (getTwitterPostComments/Quotes/Retweets).

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 extensive mode-selection guidance (fast vs paging vs csv) with explicit conditions, and states intended use cases (audience analysis, engagement patterns, reach, network graphs). It also clarifies when forceLatest should and should not be used. The one gap: it never explicitly says when to prefer a sibling tool over this one, so exclusion guidance is missing.

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 important behavioral traits beyond the annotations: it searches the database first and falls back to an external API only when data is stale (>10 days), returns operationIds for async modes, supports polling via checkOperationStatus, and notes trial-mode limitations. It also aligns with the readOnlyHint by stating it is a safe, read-only tool, with no contradiction to 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 long, but its length is justified by the tool's 14 parameters and three response modes. It front-loads the key modes and distinction from retweets, then organizes detail internally with headers/uppercase labels. Some trial-access and sign-up commentary is tangential, which keeps this from a perfect conciseness 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 no output schema and strong sibling overlap, the description covers the full context: input requirements, performance optimizations, paging/CSV behavior, caching and staleness, date handling, trial constraints, and relationships to sibling tools. An agent has enough information to select and invoke the tool correctly in fast, paging, or CSV mode.

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 71% schema coverage, the description adds meaningful parameter semantics: limit has mode-specific caps, startDate should be omitted by default unless explicitly requested, responseType maps directly to behavior, and forceLatest is documented with warning about latency and cost. It also provides field examples and clarifies that postId must be numeric, with specific examples like limit=5.

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

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

The description clearly states the tool's function: 'Get quote posts of specific post' and identifies the resource being retrieved. It also distinguishes itself from a likely sibling by adding 'NOT for retweets - use getTwitterPostRetweets', which confirms purpose while preventing confusion.

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 tells the agent exactly when to use this tool, such as 'Use to analyze commentary on post' versus retweets, and provides detailed selection guidance for the three response modes: fast, paging, and CSV. It also gives concrete usage context like omitting startDate unless explicitly requested and reserving forceLatest for explicit recency needs.

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

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

Annotations already indicate read-only and non-destructive behavior, but the description adds meaningful operational detail beyond them: fast mode returns up to 300 results, paging returns 100 per page via operationId polling, database-only means no live fetching, and trial mode returns up to 5 cached results. It also explains the limit cap and the fallback to full mode, giving the agent realistic expectations.

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

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

The description is front-loaded with the core modes and usefully warns about current-year mistakes, but it is longer than necessary and has redundancy: 'Database-only' is repeated, trial instructions are lengthy, and some phrases like 'Use to analyze post amplification patterns' and 'safe, read-only tool' repeat concepts already implied by annotations or earlier sentences. It is informational but not tightly structured.

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

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

Given the tool's complexity, no output schema, and 1 required parameter plus 13 optional parameters, the description does a strong job of covering fast mode, paging, result caps, date filtering, trial behavior, and the difference from quotes. Gaps remain around exact response shape and a few internal params like endDate, _requestId, and _isTrial, but the most important operational decisions are fully covered.

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 64%, so the input schema partially handles parameter semantics. The description compensates by clarifying startDate behavior with an explicit YYYY-MM-DD format, reconfirming the roles of limit, responseType, and fields, and explaining the relationship between paging, pageNumber, and tableName. It still leaves some private parameters like _isTrial and _requestId unexplained, so it is not a perfect 5.

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

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

Opening sentence states exactly what it does: 'Get retweets of specific post.' It also scopes the resource by saying 'Use to analyze post amplification patterns' and distances itself from a sibling tool with 'NOT for quotes - use getTwitterPostQuotes.' An agent can confidently select this tool for retrieving retweets of a post without conflating it with comments, quotes, or posts search.

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

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

The description gives explicit usage guidance: fast mode is the default, paging is for async retrieval, database-only search is for historical retweet data, and startDate should be omitted unless the user explicitly requests date filtering. It also clearly names the alternative for quotes and mentions the intended analytical use case.

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 delivers substantial behavioral context beyond the basic `readOnlyHint` annotation. It reveals database-first fetching with automatic API fallback, cache staleness behavior, response mode differences, trial limitations (5 cached DB-only results, no live fetching), and cost/latency warnings for `forceLatest`. This level of disclosure gives an agent realistic expectations about execution outcomes.

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

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

The description is information-dense and well organized in paragraph form, but it is quite long and repetitive. The JSON-fields categories appear both in the description and the schema description, and the all-caps warnings about the current year and trial access add operational noise. Each section has intent, but the structure could be tighter for agent consumption.

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

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

There is no output schema, so the description carries the responsibility of explaining not only the call behavior but also the return format and fallback. It covers this well by specifying default fields, direct-response behavior, paging/CSV workflow and polling, and the async operation orchestration. An agent has enough information to choose, invoke, and interpret the result of this tool in almost any supported use case.

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

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

Like schema coverage is moderate at 67%, but the description compensates with non-obvious parameter guidance. It explains why date filters should be omitted by default, how `limit` differs across response modes, how `fields` relate to analysis goals, and the requirement for userPrompt for accuracy. These are essential usage-specific semantics that the raw schema does not convey enough to evoke correct invocation 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 opens with a specific verb and resource: 'Get posts from author by username,' which makes the tool's scope concrete and easily distinguishable from the many keyword/ID-based sibling tools. It also surfaces the key concept of response modes and default return fields. However, it does not explicitly name or contrast sibling tools, so an agent must rely on the tool name for some disambiguation.

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 practical guidance on when to use each response mode: FAST for direct results up to 300, PAGING for async pagination, and CSV for single-file analysis. It includes explicit conditional rules like 'OMIT startDate/endDate by default' and flags `forceLatest` as 'use sparingly,' which gives operational direction. It does not explicitly state when to prefer `getTwitterPostsByAuthor` over `getTwitterPostsByKeywords` or `getTwitterPostsByIds`, so alternative-selection guidance is incomplete.

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 well covered. The description adds valuable behavioral details: searches database first then fetches external API in parallel, omits not-found IDs, returns only found tweets, and notes trial returns up to 5 cached results. It also discloses performance implications for forceLatest. Minor credit deducted because return format details are partially redundant with what is in the description already, but overall it adds meaningful 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 front-loaded with the core action and constraints, then proceeds through usage guidance, performance, returns, and trial access. Every sentence adds relevant information; however there is a minor repetition of the 'Returns only found tweets' statement (also in the schema) and the trial token instructions are extensive. Still, it is well-organized for an agent needing to decide and invoke the 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?

With a rich schema that documents most parameters and no output schema, the description covers the essentials: batch scope, fallback to external API, omitted not-found IDs, trial limits, auth requirements, and performance characteristics. It doesn't specify exact pagination or error codes, but these are less critical given the detailed schema. The description plus schema give a clear and complete picture for correct invocation.

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

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

Schema description coverage is 63%, and the description adds trial token usage, performance notes for the fields parameter, and clarifies that the response only includes found tweets. The description also enriches the fields parameter semantics by giving examples and listing categories of available fields. The postIds parameter rationale is reinforced, although the schema already documents it well. There is no significant incompleteness given the schema's strong coverage.

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

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

The description explicitly states 'Get multiple Twitter posts by numeric IDs (1-100 IDs per request)' with a specific verb and resource. It clearly distinguishes from search by saying 'NOT for search - use getTwitterPostsByKeywords'. The description also notes it returns results directly and omits not-found IDs, making scope and behavior 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 explicit usage guidance: 'Use when you have multiple exact post IDs' and instructs 'NOT for search - use getTwitterPostsByKeywords'. It also explains performance advantages over multiple single-ID calls and warns about forceLatest usage. Trial access conditions and limitations are clearly stated, covering both when and how to use the tool.

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

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

Even though the annotations mark readOnlyHint=true and destructiveHint=false, the description goes far beyond them by disclosing the database-first-then-API fallback behavior, async polling requirements for paging/CSV, caching behavior, forceLatest cost implications, and that trial mode only returns cached results. It also explicitly concludes 'This is a safe, read-only tool', reinforcing the annotation without contradicting it.

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

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

The description is long but heavily structured with clear sections for modes, query syntax, sorting, fields, and trial access. It is front-loaded with the core behavior and then branches into detail. Some redundancy with the schema descriptions and the large trial-access block could be tightened, but the usable organization makes it more effective than most tool descriptions.

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

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

For a tool with 21 parameters, no output schema, and complex multi-mode behavior, the description covers the essential operational knowledge: result caps, polling via checkOperationStatus, default return fields, filtering philosophy, the date-year trap, and even trial auth flow. An agent has enough contextual guidance to select, invoke, and interpret results correctly.

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

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

With schema coverage at 71%, the description substantially compensates by explaining the responseType modes, query syntax rules such as boolean operators and handled handles, default returned fields, the fields parameter categories, date formatting, and the meaning of relative date pitfalls. It adds real meaning beyond what the JSON schema alone provides, especially for query construction and mode selection.

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 posts by keywords.' It clearly differentiates this tool from its Twitter sibling getTwitterPostsByIds by stating 'NOT for URL lookups - use getTwitterPostsByIds.' Given the large sibling list, this immediate distinction is highly valuable.

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 identifies when this tool is appropriate and when it is not, including the URL lookup exclusion and the explicit alternative tool. It also gives mode-selection guidance for fast, paging, and CSV, ideal use cases such as sentiment analysis or content analysis, and clear instructions about when to pass dates ('ONLY pass if user explicitly requests specific date range'). This gives an agent concrete decision rules.

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

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

Beyond the readOnly/idempotent annotations, the description discloses trial token auth, 5-day expiration, the 5-cached-result limit, no live fetching on trial, and the returned single-profile shape. It also corrects potential field-name confusion ('tweetCount' not 'statusesCount'). These are real behavioral details an agent would otherwise not know.

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

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

The description is front-loaded with the primary purpose, then organized into identifier choice, fields, return shape, and trial access. It is effective but somewhat repetitive because the field list and default behavior largely duplicate the input schema, and the trial-access section adds considerable 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?

For a 9-parameter tool with no output schema, the description is unusually complete: it covers identifier semantics, field selection, returned fields, auth, caching limitations, and read-only safety. The main ambiguity is the mismatch between the camelCase 'available fields' and the snake_case return-field names, which could confuse agents relying on exact field names.

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 clarifies required parameters with concrete examples, explains the default fields, and enumerates selectable fields beyond the schema's basic documentation. It also resolves ambiguity with the 'statusesCount' deprecation. It does not deeply describe all optional params, but the schema already covers most of them at 67% coverage.

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

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

The description clearly states 'Get Twitter user profile by ID or username', giving a specific verb, resource, and identifier mode. It also distinguishes itself from searchTwitterUsers for 'person names or fuzzy search', and the 'Returns: single user profile' line separates it from multi-user sibling tools.

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

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

It explicitly instructs when to use identifierType='id' vs 'username', and says to only use this tool for exact usernames. It explicitly names searchTwitterUsers as the alternative for person names or fuzzy lookups, giving the agent a clear selection rule.

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

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

Annotations already set readOnlyHint=true and destructiveHint=false, and the description reinforces 'safe, read-only tool'. It adds valuable behavioral nuance beyond annotations: data freshness refresh rule (>1 week triggers API refetch), the critical totalRows vs totalDataCount warning about partial database-only data, cost/latency impact of forceLatest, trial limits (5 cached results, no live fetching), and the 'CSV/S3 link' async pattern. However, it internally contradicts the schema on paging page size ('1000/page with default fields' in description vs '100/page' in schema responseType), which weakens trust in the 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 organized into recognizable labeled sections (FAST, PAGING, CSV, CODE EXECUTION, DATA FRESHNESS, CRITICAL, TOTAL). However, it is very long, repeats details that live in the schema, and the trial-access block reads like onboarding marketing rather than tool usage guidance. Front-loaded core purpose is good, but several sentences could be cut without loss.

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 params, three response modes, async-polled results, and no output schema, this is a rich contextfult description: it explains return shapes (300 results direct, operationId for polling, S3 link for CSV), the async flow via checkOperationStatus, the totalRows vs totalDataCount distinction, and the trial limits. The gaps are modest: it doesn't detail the polling workflow output fields, and the inconsistent paging page size introduces the complete picture.

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

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

At 79% schema coverage, the schema already documents most parameters, so the description's job is to add nuance. It meaningfully adds direction semantics for connectionType, clarifies the responseType modes (fast up to 300 results, async operationId for paging, S3 link for csv), and explains performance tradeoffs of the fields parameter. This is genuinely additive over the schema without fully compensating for the remaining ~20% (e.g., _isTrial, _requestId, _trialToken) which are left unexplained in both places.

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 Twitter user connections') and immediately clarifies the two connection directions: connectionType='followers' for users who follow them, connectionType='following' for users they follow. This unambiguously differentiates it from siblings like getTwitterUser, getTwitterPostsByAuthor, and the Instagram/TikTok connection tools without needing to open the schema.

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

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

Provides strong usage context: 'Ideal for: network analysis, audience demographics, engagement patterns', plus explicit guidance on when to pick fast vs paging vs csv mode (e.g., csv + code execution for full dataset analysis), and a warning to use forceLatest sparingly. It does not explicitly name sibling alternatives or exclusion conditions, leaving some selection work to the agent.

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