Viral Outliers

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

Annotations already declare readOnlyHint and idempotentHint. The description adds valuable behavioral details: unresolved profiles return in a notFound list instead of failing, the call costs 2 credits, and it is 'Pure lookup, fast.' This goes beyond what annotations provide, earning a 4.

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

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

The description is three sentences, front-loaded with the main action and scope. It includes only useful details: output stats, error behavior, and cost. No fluff or redundancy.

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

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

For a read-only tool with no output schema, the description covers inputs (profile id or platform+handle), outputs (stats fields and ranking), error handling (notFound), and cost. It does not clarify whether both handles and profileIds can be mixed, but overall it is complete enough for an agent to invoke correctly.

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

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

The schema descriptions already cover both parameters 100% ('Handle pairs to resolve; 2–5 profiles total across both fields' and 'Profile ids to compare'). The description repeats the identifier types and the 2–5 limit but does not add new parameter semantics, so baseline 3 is appropriate.

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

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

The description clearly states the tool 'Compares 2–5 tracked profiles' and specifies the outputs: stats (follower count, average views/likes, engagement rate) and a computed ranking. This specific verb+resource distinguishes it from siblings like get_profile or search_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 clearly implies the use case: comparing multiple (2–5) tracked profiles. It notes 'Pure lookup, fast' and error handling for unresolved profiles, but does not explicitly name alternatives or say when not to use it. Clear context without exclusions warrants a 4.

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 only indicate non-read-only, non-idempotent, and open-world. The description adds significant behavioral disclosures: asynchronous processing, job reference return, no charge for already-tracked profiles, automatic refund on failure, and cost of 40 credits. 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 primary action and scope in the first sentence. Each subsequent sentence adds essential operational detail (async, return type, duplicate handling, refunds, cost) without extraneous words.

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 the crawling scope, asynchronous job reference, duplicate behavior, cost, and failure refunds. The only minor gap is not specifying what exactly is returned when the profile is already tracked, but the overall information is sufficient for a complex tool.

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

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

The input schema has bare properties (handle, platform) with no descriptions, and schema description coverage is 0%. The description provides no additional meaning for the handle format or platform choices beyond the enum, failing to compensate for the lack of schema documentation.

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

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

The description clearly states a specific action ('Submits a public profile for crawling') and defines what is included: profile metadata, recent posts, stats, and thumbnails. It also distinguishes the tool by explaining the post-crawl behavior (stays tracked and appears in searches), setting it apart from siblings like get_profile or track_profile.

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

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

The description provides clear context: asynchronous execution, use with get_job_status, immediate return for already-tracked profiles, and credit cost. It does not explicitly name alternative tools for scenarios like simply fetching a profile, but the use case is well implied.

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

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

Beyond the annotations, the description discloses a rate limit (5 links/hour), link validity (24 hours), credit arrival timing (within seconds), and cost (free). These are critical behavioral details that help an agent anticipate the tool's consequences. The description aligns with the annotations (readOnlyHint=false, openWorldHint=true) and adds practical constraints.

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

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

The description is concise and front-loaded, opening with the primary action. Each sentence provides distinct value: purpose, use case, behavior (credits and validity), rate limit, and pack reference. There is no filler or redundancy that undermines clarity.

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

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

For a single-parameter tool with a fully covered schema and useful annotations, this description is sufficiently complete. It explains what the tool creates, when to use it, rate limit, validity, timing of credits, and cost. The return value (a link) is implied and no output schema exists, so no further detail is necessary.

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

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

The input schema already fully covers the only parameter packId with an enum and a description pointing to get_credit_balance/docs. The description only repeats the 'see docs' guidance and does not add new meaning or syntax beyond the schema. With 100% schema coverage, the baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose with a specific verb and resource: 'Creates a Stripe Checkout link for a credit pack.' It also differentiates from sibling tools by tying the action to a concrete scenario (balance running out mid-task) and the benefit of providing a one-click payment link instead of manual instructions.

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

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

The description explicitly identifies when to use this tool: 'when the balance runs out mid-task.' It also suggests an alternative to using the tool (giving instructions), offering practical guidance. However, it doesn't explicitly name sibling tools for comparing balance or exclude other scenarios, so it doesn't fully earn a 5.

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

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

Annotations indicate readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false. The description adds significant context beyond these hints: it discloses the on-demand fetch queue with ~90 second readiness, jobRef polling, CDN URL expiration, YouTube's thumbnail-only return, and credit cost. It also warns about legal responsibility, which is valuable operational context.

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

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

The description is appropriately sized for the tool's complexity, front-loaded with the primary purpose. It covers necessary caveats (CDN expiration, YouTube thumbnail, legal, cost) without fluff. While dense, every sentence carries relevant information.

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

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

No output schema exists, so the description must explain return behavior. It mentions direct media URLs, jobRef for polling, and thumbnail for YouTube. It also covers the fetch flow and credit cost. It could explicitly describe the response structure for media URLs, but the description gives sufficient operational detail for an agent to use the tool correctly.

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

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

Schema description coverage is 100%, with both parameters already described in the schema. The description repeats the alternative nature of url/postId but adds no new meaning beyond the schema. Baseline 3 applies because the schema does the heavy lifting.

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

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

The description clearly states the tool returns direct media URLs for a tracked post, video file, or slideshow images with positions. It uses a specific verb ('returns') and resource ('media URLs') and distinguishes from sibling tools like get_post by focusing on media download.

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 explains when to use the tool: to get media for a tracked post, accepting either a public URL or internal post ID. It also describes the on-demand fetch flow and advises to call again once complete. However, it does not explicitly mention alternatives or exclusions, though the context implies the tool is for media downloading rather than general post retrieval.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds 'Free to call' and usage guidance (check before batch jobs, handle insufficient credits), which is useful but modest. 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 brief but includes redundancy: 'Free to call' and 'Cost: free' say the same thing. The second sentence is somewhat long but contains actionable guidance. Overall, it could be tightened without losing meaning.

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

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

For a simple zero-parameter read-only tool with strong annotations, the description provides the core return value (credit balance), usage context, and error handling. It is missing an explicit return format (e.g., number, currency), but this is not critical given the simplicity and the annotations.

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

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

The tool has zero parameters, and the schema is empty with 100% coverage. Per baseline, a description need not explain parameters. It does not need to add detail beyond what the schema already provides.

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

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

The description clearly states the tool returns the current API credit balance for the authenticated account, using a specific verb ('Returns') and resource. It distinguishes itself from all sibling tools, none of which are balance-related.

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

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

The description explicitly instructs agents to check the balance before starting large batch jobs and to surface insufficient_credits errors with a top-up link. This gives a clear when-to-use context, though it does not name the alternative tool create_topup_link directly or state when not to use it.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds critical context: the call is free, credits are never consumed, and jobs typically complete in minutes. 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?

Three short sentences each add unique value: purpose/statuses, cost guarantee, and poll timing. No redundant or vague wording.

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

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

For a simple polling tool with no output schema, the description covers the return statuses, typical latency, and cost. It lacks explicit return structure but the status values are sufficiently self-explanatory.

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 specifies a required string jobRef with no description. The description adds that the job is started by crawl_profile or request_transcript, implying jobRef is the job identifier from those tools. However, it doesn't explicitly describe its format or where to obtain it, leaving some 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 clearly states it returns the status of an asynchronous job and names the specific source tools (crawl_profile, request_transcript), along with the possible statuses. This distinguishes it from sibling tools that perform other operations.

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

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

It explicitly states polling is free and recommends a 10–30 second interval with typical completion time, giving the agent clear guidance on when and how to call. It does not mention alternative tools, but no alternative exists for this purpose.

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

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

Annotations already mark the tool as read-only and idempotent, but the description adds valuable behavioral context: it automatically includes existing transcripts/visual analysis at no extra cost, does not generate new ones (implying request_transcript is needed), and discloses the cost of 1 credit per call. This goes well beyond the annotation 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 tightly written in three sentences. The first sentence front-loads the main purpose and return fields, the second clarifies the inclusion of cached analyses, and the third adds usage context and cost. No wasted words.

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

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

For a read-only tool with three simple parameters and no output schema, the description sufficiently covers the return contents, cost, usage flow, and relationship to request_transcript and search_outliers. It provides enough for an agent to use the tool correctly in context.

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

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

The schema already provides 100% parameter coverage with descriptions for all three parameters (postId, includeTranscript, includeVisualAnalysis). The description does not add additional parameter-specific semantics beyond what the schema states, so it sits at the baseline for full schema coverage.

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

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

The description clearly states 'Fetch a single post by id' and enumerates the returned data (views, likes, comments, engagement rate, outlier scores, thumbnail, owning profile). It distinguishes itself from sibling tools by specifying 'single post' and referencing 'search_outliers' for search, making it unambiguous.

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

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

Explicit usage guidance is provided: 'Use after search_outliers to deep-dive a result.' It also directs users to 'request_transcript' for generating new transcripts, contrasting with this tool's behavior of including only cached ones. This gives clear when-to-use and alternative context.

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

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

Annotations already declare read-only and idempotent hints, but the description adds valuable behavioral context: it requires the profile to be 'tracked', it costs 1 credit per call, and it clarifies that the averages serve as the baseline for outlier scores. This goes beyond the annotations without contradicting them.

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

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

The description is three sentences: purpose, content details, and workflow/cost. Every sentence is useful and front-loaded, with no filler or repetition.

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

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

For a read-only single-profile fetch, the description covers what data is returned (followers, bio, averages, recent posts), explains the meaning of averages, and includes cost and the prerequisite search step. It lacks details on time window definitions and post count limits, but these are minor for a fetch operation 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 descriptions cover platform and profileId clearly, and the description reinforces that profileId comes from search results. However, the handle parameter has no schema description and the tool description doesn't clarify its semantics beyond the workflow note. With 67% schema coverage, the description partially compensates but not fully.

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

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

The description opens with 'Fetch one tracked profile by id', which is a specific verb+resource that clearly states the tool's function. It distinguishes itself from siblings like list_tracked_profiles by focusing on a single profile and from search_profiles by being the post-search retrieval step, reinforced by the direct instruction to use search_profiles first.

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

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

The description gives an explicit workflow ('Use search_profiles first to resolve a handle to an id') and mentions the cost per call, which helps decide when to invoke it. However, it does not explicitly contrast with alternative tools like list_tracked_profiles for bulk operations or note when not to use this tool.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description doesn't need to restate safety. It adds context by listing what the result contains and mentioning the web app visibility, plus confirming zero cost. This is sufficient value beyond annotations.

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

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

Three concise sentences front-load the purpose, then add workflow and cost. Every sentence adds information, with no waste or redundancy.

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

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

With one simple parameter and no output schema, the description still explains what the return contains, the prerequisite workflow, and cost. It fully covers the context needed to invoke the tool correctly.

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

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

The schema already provides a complete description of the single parameter jobRef, including that it comes from remix_post. The description text adds only the phrase 'pipeline jobRef,' which is marginal. With 100% schema coverage, a baseline of 3 is appropriate.

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

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

The description clearly states the tool returns a finished remix for a remix_post job, listing the exact components (adapted title, description, script segments, checklist). This specific verb+resource phrasing distinguishes it from siblings like get_job_status and remix_post.

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

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

Explicit workflow guidance is provided: poll get_job_status until completed, then fetch here. This tells the agent exactly when to use this tool and how it relates to the job pipeline. The note 'Free to call' also helps with usage decisions.

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

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

The description explicitly states each call advances a per-profile cursor so subsequent calls return only posts crawled after it, directly contradicting the idempotentHint=true annotation. It also describes results changing as scheduled crawls run, contradicting openWorldHint=false. Per the rubric, a contradiction with annotations mandates a score of 1.

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

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

The description is well-structured and front-loaded, with each sentence adding useful context about the feed behavior, refresh cadence, result shape, and cap. However, it repeats the 'free' cost information ('Free to call' and 'Cost: free'), which is redundant and prevents a perfect 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 one parameter and no output schema, the description adequately covers the non-trivial feed semantics, cursor behavior, refresh cadence, result shape, and response cap. It references search_outliers for the exact shape, which is somewhat indirect but combines with the given fields to provide a usable 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?

Schema coverage is 100% and the schema already documents the limit parameter including default and range. The description adds the phrase 'Total posts are capped' and repeats the range, providing minimal new semantic value beyond the schema.

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

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

The description clearly states it returns posts newly discovered since your last check across all monitored profiles, using a specific verb and scope. It distinguishes itself from sibling tools like list_tracked_profiles (which lists profiles) and search_outliers (which searches).

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

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

The description provides clear context for when to use it—to get new posts from all monitored profiles as a feed—and explains refresh cadence tied to track_profile. It does not explicitly name alternative tools or exclusions, but the feed vs re-scan distinction and 'across all profiles' imply appropriate usage.

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

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

Annotations already declare read-only, idempotent, and non-destructive. Description adds rate-limit per IP, ~2h caching, and deduplication behavior, providing useful operational context beyond annotations.

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

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

Description is mostly concise and front-loaded with the main purpose. Minor redundancy: 'Free' appears twice (in sentence 2 and 'Cost: free'), and 'A taste of the database' is somewhat vague but adds qualitative context.

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 parameters and no output schema, the description covers the tool's functionality, platform scope, deduplication, caching, rate limits, and authentication model, plus pointers to more advanced features. This is sufficiently complete for a simple read-only tool.

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

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

The tool has zero parameters, so schema coverage is trivially 100%. Baseline for 0 params is 4; description adds context about the returned data but nothing parameter-related is 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?

Description clearly states it returns current top trending outlier posts across TikTok, Instagram, and YouTube, deduplicated per creator. This specific verb+resource scope distinguishes it from sibling tools like search_outliers and niche_trends.

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

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

Explicitly notes it is free and unauthenticated, contrasting with filtered search, transcripts, and on-demand crawling which require an API key, implying alternative tools for those use cases. However, it doesn't name specific sibling tools, leaving some ambiguity.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds value by disclosing cost ('Free to call'), output fields, and paused-reason context, which go beyond the annotations. No contradiction.

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

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

The first sentence is a long run-on listing many fields, and cost is mentioned twice ('Free to call' and 'Cost: free'), creating redundancy. It is structured but could be tightened.

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

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

For a parameterless tool with no output schema, the description thoroughly covers what is returned, why to use it, and cost. It fully equips an agent to select and invoke this tool.

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

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

The tool has zero parameters, so the baseline is 4. The description adds meaning by enumerating the return fields, though it does not need to explain parameters that do not exist.

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

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

The description clearly states the tool returns every monitored profile with specific fields, and the focus on profile list distinguishes it from siblings like get_tracked_updates. The verb 'Returns' and resource 'every profile you are currently monitoring' are specific and unambiguous.

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

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

It provides explicit use cases: auditing refresh status/cost and grabbing a profileId for untrack_profile. However, it does not mention alternatives or when not to use it, such as differentiating from get_tracked_updates.

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 description's read-only nature is already covered. The description adds value by disclosing the default time window (one week), the cost of 2 credits per call, and the return structure (breakdown by content types and creators), which are not present in annotations or schema.

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

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

The description is four terse sentences covering purpose, filtering, usage workflow, and cost. Every sentence carries useful information without redundancy, and the main purpose is front-loaded in the first sentence.

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 read-only, idempotent nature (from annotations), optional parameters, and lack of output schema, the description sufficiently covers the return breakdown, default behavior, cost, and typical usage scenario. It could be slightly clearer about what 'overperforming' means and how limit applies, but overall it is comprehensive enough for an agent to select and invoke the tool effectively.

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

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

Schema description coverage is 50% (query and timeFrame are described; limit and platforms are not). The description adds meaning for platforms by mentioning 'Filter by keyword and platform' and confirms the default window for timeFrame, but it does not explain the 'limit' parameter's semantics or interaction with the result set. This is partial compensation but leaves a gap for limit.

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

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

The description states a specific verb ('Returns') and resource ('top overperforming posts in a niche'), and further specifies the output includes a breakdown by content type and creators. This clearly distinguishes it from sibling tools like 'get_trending_outliers' or 'search_outliers' by focusing on niche-level trends rather than generic outliers or profile comparisons.

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 positions the tool as 'Great as the first call in a content-research loop' and suggests follow-ups like deep-diving or remixing winners, providing clear contextual guidance. It does not name alternatives or state explicit exclusions, but the usage context is unambiguous and helpful.

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 only indicate non-read-only, open-world, non-idempotent, non-destructive. The description adds critical context: asynchronous execution (1–3 min), jobRef return value, polling contract, video-specific auto-transcript/analysis generation, automatic credit refund on failure, and 20-credit cost. This far exceeds annotation coverage.

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

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

The description is dense but well-organized: purpose first, then async behavior, video handling, refunds, and cost. Every clause adds operational value, though the length is slightly above minimal. It is appropriately front-loaded for a tool with this complexity.

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

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

With no output schema, the description compensates by naming the result components (title, description, script, checklist), the jobRef polling mechanism, and the combined status+result from get_remix_result. It omits exact JSON field names but gives enough for an agent to use the tool successfully.

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

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

Schema covers all 4 parameters at 100%, so the baseline is 3, but the description adds relational meaning: url and postId are alternatives (public vs internal), and targetNiche is clarified as niche/brand/audience. The tone parameter is not mentioned in the description, but the schema already explains it adequately.

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: takes a post (via URL or ID) plus a target niche and produces an adapted content idea with specific deliverables (rewritten title/description, script, checklist). It distinguishes itself from the sibling polling tool get_remix_result by framing this as the initiating async call that returns a jobRef.

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 operational guidance: pass either a public URL or internal post ID, provide a target niche, and then poll get_remix_result. It also notes video posts are handled automatically. However, it doesn't explicitly state when to prefer this over alternate siblings, so it stops short of full 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 annotations (which are all false), the description discloses cost ('Free', 'never spend credits'), that reports 'go straight to the team', and the email notification behavior via wantsUpdate. This adds meaningful context about side effects and behavior not captured in annotations.

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

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

The description is slightly longer than necessary but well-structured: purpose first, then scenarios, cost, instructions, and email option. Every sentence contributes useful information, with no filler.

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

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

For a simple reporting tool with no output schema, the description covers key aspects: when to use, what to include, cost, and optional email update. It doesn't discuss rate limits or response behavior, but those are less critical for this type of tool.

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

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

Schema coverage is 100%, so the description doesn't need to add much. It does restate the message content and the wantsUpdate behavior, but adds no new technical detail beyond the schema. The 'skill' parameter is implied but not explicitly mapped.

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

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

The description clearly states the tool's purpose: 'Report a problem with any skill' – a specific verb and resource. It distinguishes from siblings by covering error reporting, data issues, and missing API capabilities, which no sibling tool addresses.

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 lists scenarios for use (errors, stale data, missing capabilities) and gives instructions on what to include ('what you called, what you expected and what happened'). It doesn't name alternative tools, but the context makes it clear this is the dedicated reporting tool.

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

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

Beyond the annotations, the description discloses the asynchronous job lifecycle, job reference polling, attachment to get_post, credit charging on queueing, automatic refund on failure, and the exact cost (10 credits). This significantly enriches behavioral understanding beyond the readOnly/idempotent/destructive 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 compact and front-loaded, using only 3-5 sentences to cover purpose, input format, async behavior, cost, and refund policy. Every sentence adds necessary information without unnecessary elaboration.

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 lack of output schema, the description adequately compensates by explaining the async flow, how to poll status, where results appear, and cost implications. It fully covers the operation's key aspects, making it complete for an agent to decide and invoke confidently.

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

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

Schema coverage is 100% with both url and postId described. The description restates the URL vs. postId relationship but adds no new semantic information about parameters beyond what the schema already provides, so a baseline 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 clearly states it queues AI transcription for a post, with specific scope (spoken audio vs slideshows). It distinguishes from siblings like get_post by noting the transcript attaches to get_post responses, and from remix_post by focusing on transcription.

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

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

The description provides clear context: use for transcribing post audio, and explicitly mentions slideshows use on-screen text extraction instead. It also guides the follow-up flow by directing to poll get_job_status and noting the transcript appears in get_post responses, though it doesn't name an alternative tool for transcription.

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 the description adds significant beyond annotations: cost per call, found:true/false semantics, and short link handling. 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?

Three sentences, front-loaded with the main action, and every sentence provides unique information: platform scope, return semantics, alternative actions, and cost. No waste.

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

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

For a single-parameter tool with no output schema, the description fully covers expected behavior, edge cases (short links), next steps after found:true/false, and cost. Genuinely complete.

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

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

Schema describes url as 'Public post URL (canonical, not a short link)' with 100% coverage. The description adds supported platforms and reiterates the canonical requirement, providing mild added meaning beyond schema.

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

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

The description uses 'resolves' to a tracked post, specifying it is the entry point for link inputs and distinguishing it from sibling tools like get_post and crawl_profile. It clearly lists supported platforms (TikTok, Instagram, YouTube) and the returned postId.

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

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

Explicitly states when to use: 'the entry point when your input is a link'. Provides conditional guidance: found:false indicates whether to call crawl_profile or just that the post is missing. Also warns about short link expansion requirements.

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, and the description adds valuable context about data freshness, deleted/deactivated posts, frozen stats, filtering options, and cost per call.

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

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

The description is lengthy but every sentence contributes context: purpose, filters, output, use case, data caveats, and cost. It is well-structured and front-loaded with the core function.

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 the tool's purpose, filters, output type (post metadata, stats, thumbnails), data quality issues, and cost. However, it does not mention pagination or the presence of optional parameters like minOutlierScore/maxOutlierScore.

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

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

Schema coverage is only 13%, and while the description enumerates filter categories (platform, keyword, content type, views, follower count, engagement rate, time window), it omits outlier score range filters and pagination parameters, leaving the agent to infer min/max semantics.

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

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

The description explicitly states the tool searches a continuously-crawled database of social media posts ranked by outlier score, with a clear explanation of outlier score. It differentiates from sibling tools like get_trending_outliers by emphasizing search and filtering capabilities.

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

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

The description provides a direct use case ('Use this to find proven viral formats in any niche before creating content'), but does not explicitly mention when not to use it or name alternative tools.

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

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

Even with readOnlyHint and idempotentHint annotations, the description adds substantial behavioral details: deactivated profiles are included with frozen stats, duplicate rows for handle changes, and the cost of 1 credit per call. These go beyond the annotations.

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

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

The description is four sentences with no fluff. It front-loads the main action, then returns, use cases, edge cases, and cost. Every sentence adds value and the structure is logical.

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

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

Given no output schema, the description explains return content (metadata, follower counts, average performance stats). It covers edge cases and cost. Only pagination is implicit, but this does not detract from overall completeness.

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

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

Schema coverage is only 25% (only query has a description). The description adds meaning for query ('handle or name') and platforms ('filtered by platform'), but does not explain page/pageSize. With low coverage, it partially compensates but leaves pagination unaddressed.

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 'Search tracked social media profiles by handle or name, filtered by platform' with a specific verb and resource. It distinguishes from siblings like get_profile (single profile) and list_tracked_profiles by emphasizing search and handle resolution.

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 provides use cases: 'resolve a handle to a profile id before fetching stats or posts' and 'discover creators in the database'. It does not name alternatives or explicitly state when not to use, but the context is clear enough.

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 annotations only indicate non-read-only, open-world, non-idempotent, non-destructive. The description adds rich context: credit costs (10 per refresh), auto-pause if balance runs out, resume on top-up, the prerequisite that the profile must exist, and idempotent-update behavior for repeat calls. This goes well beyond the structured annotations.

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

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

The description is dense and front-loaded with the core function, then covers cost, prerequisites, update behavior, and follow-up. It avoids bloat, though there is minor redundancy ('Cost: free' at the end repeats the earlier 'Managing monitoring is free'). Overall efficient and well-organized.

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

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

Despite having no output schema, the description covers prerequisites, cost, side effects, identification methods, and follow-up tools. It does not explicitly state what the tool returns (e.g., a confirmation or tracking ID), which is a minor gap, but the operational context is thorough enough for an agent to act correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful usage context by explaining the three identification methods (profileId, platform+handle, URL) and that platform must be paired with handle. It also clarifies that frequency defaults to weekly and that calling again updates the cadence, which enriches the parameter semantics.

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

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

The description clearly states the action ('Starts monitoring a profile') and the resource (a profile), with specific cadence options. It distinguishes itself from sibling tools by explicitly contrasting with crawl_profile and pointing to get_tracked_updates for retrieving updates.

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: requires the profile to already exist, says to use crawl_profile first if not, explains that repeated calls update the cadence, and directs users to get_tracked_updates for pulling posts. This clearly frames when to use this tool versus 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?

Beyond the annotations (which indicate a non-read-only, non-destructive mutation), the description discloses that the profile and its posts remain searchable, that only the refresh stops, and that it is free to call. It also specifies the not_found error behavior, which the annotations do not cover, adding significant transparency.

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

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

The description is front-loaded with the core action and keeps most sentences short. However, it repeats 'free' twice ('Free to call' and 'Cost: free'), which is slightly redundant but not misleading.

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

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

With one parameter and no output schema, the description covers all essential aspects: what happens to the data, cost implications, error response, and input provenance. For a tool of this simplicity, it is complete.

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

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

The schema already documents profileId with 100% coverage, so the baseline is 3. The description adds value by specifying the source of the ID (list_tracked_profiles or search results) and clarifying it is internal, which helps the agent obtain the correct 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 uses the specific verb 'Stops monitoring a profile' and clarifies the resource and key consequence (no further scheduled refresh crawls are charged). It distinguishes itself from sibling tools like track_profile by framing the action as stopping a recurring process, not deleting data.

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

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

It tells the user to pass the internal profileId from list_tracked_profiles or search results, and explains the not_found return case for a profile not currently monitored. While it doesn't explicitly name alternatives like track_profile, the context makes the usage scenario unambiguous.

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