Viral Outliers

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

The description goes well beyond annotations by disclosing idempotent-like behavior ('Already-present creators are reported, not duplicated'), unresolved creator handling ('unresolved ones come back in notFound'), allowance consumption, and over-limit behavior. This is rich behavioral context that annotations alone do not 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 front-loaded with the primary action and packs many important details into a compact paragraph. The only minor redundancy is stating 'Free to call' and 'Cost: free' separately, which is slightly repetitive but not distracting.

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 covers key invocation details: input formats, limits, prerequisites, failure behavior for unresolved IDs, non-duplication, and allowance consequences. It is complete enough for an agent to select and call the tool correctly, though exact success response shape is not described.

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 baseline is 3. The description adds meaningful context beyond the schema by explaining where profileIds come from ('from search_profiles or any search result'), clarifying the shape of handles as {platform, handle} pairs, and reinforcing the 25-per-call limit. This pushes it above baseline.

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

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

The description clearly states the action ('Adds creators to one of your watchlists') and identifies the key resource (watchlists and creators). It distinguishes itself from siblings like remove_watchlist_profiles through its explicit add semantics and covers both input modes (profileIds and handles).

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 on when to use the tool, including the prerequisite that creators must already be tracked and the explicit instruction to 'crawl_profile first if not'. It does not explicitly name alternatives for removing creators, but the usage context for adding is well specified, so only minor 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?

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?

Beyond the annotations, the description reveals important non-obvious behavior: watchlists appear in the owner's web app, the call is free, and watchlists count against a workspace allowance. It also explains the over-limit behavior. This is rich contextual detail that helps an agent anticipate 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 well-structured and front-loaded with the core purpose and return value. It includes a minor redundancy between 'Free to call' and 'Cost: free', but overall every sentence contributes useful workflow, allowance, or behavior information.

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

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

Given the tool's moderate complexity, the description covers creation, return value, downstream integration with two sibling tools, web-app visibility, and quota implications. There is no output schema, but the key return value (watchlistId) is stated. The description is sufficient for correct invocation.

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

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

The input schema already documents both parameters completely (name and notes) with descriptions, so schema coverage is 100%. The description does not add much parameter-level detail, but it doesn't need to because the schema carries the load.

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 that this tool creates an empty watchlist, a named set of creators, and returns a watchlistId. It is easily distinguished from siblings like add_watchlist_profiles, delete_watchlist, and list_watchlists by focusing on the creation action.

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 usage workflow: create the watchlist, populate it with add_watchlist_profiles, and then pass the id to search_outliers. It does not explicitly mention when not to use it versus alternatives, but the workflow context is clear and practical.

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

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

The description is very transparent about destructive effects: it deletes the watchlist, its memberships, and frees slots. However, the annotations set destructiveHint=false, which directly contradicts the clearly destructive behavior described. Per the scoring rule, this contradiction forces 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?

Three concise sentences front-load the action and side effects, then provide ownership, compatibility, and cost details. Every sentence earns its place with no padding.

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 delete tool with no output schema, the description is complete: it states what is deleted, side effects (slot freeing), compatibility, ownership restriction, and cost. The lack of return-value details is a minor gap given the tool's simplicity.

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

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

The schema already covers the single parameter at 100%, so the baseline is 3. The description adds useful meaning by clarifying that the watchlistId is valid for lists created through the API or in the web app, broadening the schema's narrow 'API-created watchlist id' 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 uses the specific verb 'Deletes' with the resource 'one of your watchlists' and clarifies the full scope ('including its memberships'). It clearly distinguishes itself from sibling tools like remove_watchlist_profiles by stating the entire list and its memberships are removed.

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 usage context: only the owner can delete, it works for both API-created and web-app lists, and it frees slots. It doesn't explicitly name alternatives, but 'including its memberships' implies that removing only certain profiles should be done with a different tool. A slightly more explicit when-to-use/when-not-to-use statement would make it 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. Beyond that, the description adds valuable context: the cost per call, that pre-existing transcripts/visual analyses are included 'at no extra cost', and the detailed structure of the visual analysis (scene-by-scene breakdown with timing, on-screen text, etc.). This goes well beyond what the annotations convey.

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

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

Three dense sentences cover the core function, optional inclusions, related tools, workflow, and cost. Each sentence earns its place; there's no fluff or redundancy. The most critical information (the verb 'Fetch' and resource) is front-loaded.

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

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

For a read-only fetch tool with no output schema, the description thoroughly covers the response payload (views, likes, engagement rate, outlier scores, etc.), optional cached data, and how to trigger new enrichment. It also gives a clear workflow ('Use after search_outliers'), making it complete for its intended purpose.

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?

Since schema description coverage is 100%, the baseline is 3. The description adds context by explaining that `includeTranscript` and `includeVisualAnalysis` pull from cache ('When a transcript or visual analysis already exists it is included at no extra cost') and that new generation is delegated to other tools, which clarifies the default behavior. However, the schema already conveys the core meaning of these flags, so the added value is incremental.

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 a single post by id' – a specific verb, resource, and scope. It clearly enumerates the returned data (views, likes, comments, engagement rate, outlier scores, thumbnail, owning profile) and distinguishes itself from sibling tools like `search_outliers` (which is for searching/listing) and `get_profile` (which targets profiles, not posts).

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

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

The description explicitly states, 'Use after search_outliers to deep-dive a result,' providing a direct workflow context. It also points to `request_transcript` and `request_visual_analysis` for new enrichment, unambiguously indicating when NOT to use this tool. The cost note ('1 credit per call') further guides the agent's decision-making.

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 (readOnlyHint=true, idempotentHint=true, destructiveHint=false) already indicate a safe read operation. The description adds valuable context beyond that: it's free, unauthenticated, and billable calls return X-Credits-Charged and X-Credits-Balance headers. This is exactly the kind of extra behavioral detail that helps an agent.

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 complete—three sentences, no fluff, and the core purpose is front-loaded. Every sentence adds actionable info (what's returned, cost/authentication, header behavior), and it ends with a clear cost indicator.

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 input schema, no output schema, and no parameters, the description carries the entire burden—and it fully delivers. It explains the return payload, the response headers, the access requirements (none), and the cost. An agent can call this tool without any further information.

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 thoroughly explains the return structure (credit value, skills, packs, allowances) and the response headers, which is more than sufficient for a parameterless tool.

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 ('Returns') and a precise resource ('current price list as structured JSON') and enumerates exactly what's included (credit value, skills with costs and routes, packs, plan allowances). No sibling is about pricing, so it's 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?

Clearly describes when to use it (to render live costs to integrators, attribute spend for resellers) and notes it's free and unauthenticated, which implies it's safe to call anytime. It doesn't explicitly name alternatives, but no other sibling handles pricing, so the guidance is sufficient.

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, idempotentHint, and non-destructive behavior, so the bar is lower. The description goes further by disclosing the job-lifecycle requirement, the exact result contents, an alternate access path, and cost. This adds meaningful behavioral context beyond 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 concise and front-loaded, with the core result and contents in the first sentence. The only minor issue is redundancy: 'Free to call' and 'Cost: free' communicate the same fact twice, preventing 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 simple one-parameter read-only tool with no output schema and strong annotations, the description is complete: it explains what is returned, the polling prerequisite, the web app alternative, and cost. No critical usage context is missing for an agent to correctly 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?

Schema coverage is 100% and the sole parameter, jobRef, is already described as 'The pipeline jobRef returned by remix_post.' The description restates that it is for a remix_post job but does not add meaningful new semantics or format details beyond the schema. Baseline 3 is appropriate.

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

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

The description uses a specific verb+resource pattern: 'Returns the finished remix for a remix_post job' and enumerates the exact output contents (adapted title, description, script segments, whyItWorks, checklist). This clearly distinguishes it from sibling tools like get_job_status, which tracks job progress rather than the finished result.

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

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

It explicitly names the prerequisite workflow: 'Poll get_job_status until the job reports completed, then fetch here.' This gives the agent a clear when-to-use instruction and identifies the alternative tool by name. It also notes the result is viewable in the web app, adding useful 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?

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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds useful behavioral context by stating the call is free and by specifying exactly what is returned: every member profile with profileId, handle, platform, and follower count. This goes beyond the annotation-only safety profile.

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

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

The description is compact and front-loaded with the core return behavior. However, 'Free to call' and 'Cost: free' communicate the same fact twice, creating minor redundancy that keeps it from 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 single-parameter read tool with no output schema, the description is complete: it identifies the input, enumerates the output fields, states the cost, and connects the output to a likely follow-up mutation. An agent has enough information to invoke the tool correctly and interpret its result.

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% and the only parameter, watchlistId, is adequately described in the schema. The description merely references 'by watchlistId', adding no substantial meaning beyond the schema, 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 a specific verb ('Returns') and resource ('a single watchlist by watchlistId') and enumerates the returned fields. This distinguishes it from sibling tools like list_watchlists, which returns collections, and remove_watchlist_profiles, which mutates.

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

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

The description gives explicit use cases: review or explain a list before searching it, and pick profileIds for remove_watchlist_profiles. It does not explicitly name alternative tools or state when not to use this tool, but the use-case guidance is concrete and actionable.

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

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

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 establish readOnly, idempotent, and non-destructive behavior. The description adds useful context beyond annotations: output fields include watchlistId, name, notes, profile count, and last-updated time, and it notes the tool is free to call. No pagination or limits are disclosed, but the annotations significantly lower the burden.

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

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

The description is front-loaded with the main return behavior and fields, which is good. However, 'Free to call.' and 'Cost: free.' are redundant statements of the same fact, 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?

For a zero-parameter, no-output-schema read-only list tool, the description is complete: it states what is returned, the fields included, the scope of watchlists, and how the result can be used. Nothing critical is missing for an agent to call it correctly.

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

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

The tool has zero parameters and 100% schema description coverage, so there is no parameter meaning left unexplained. With no parameters, description-level parameter guidance is unnecessary; the baseline 4 applies.

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

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

The description states a specific verb and resource: 'Returns every watchlist on the account'. It also clarifies scope by including both agent-created and web-app-created watchlists, and it names the exact output fields. This clearly differentiates it from sibling tools that manage or analyze single watchlists.

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

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

The description explicitly says to use it 'to recall an id for search_outliers, add_watchlist_profiles or get_watchlist', giving concrete downstream use cases. It does not explicitly state when not to use the tool or contrast it with other listing tools like list_tracked_profiles, so it falls just short of a 5.

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

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

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

Transparency is excellent beyond the annotations: it details async behavior (~1–3 min), untracked URL handling, automatic refunds on failure, credits cost per call, and the fact that it auto-generates transcripts/analysis for videos—description adds value beyond the raw annotation hints, with no contradiction with readOnlyHint=false. The behavior disclosure is comprehensive (e.g., cleanup, failure cleanup, timing) and includes useful caveats like 'few minutes longer for untracked URLs.'

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 information-dense sentences that follow a logical progression: what it does, async/error handling, and special case handling (videos) plus credits cost. No fluff, 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 an async job-based tool with no output schema, it covers the essential workflow: what to expect asynchronously, how to poll, cost and refunds, and the handling of untracked URLs. Missing a short note on exact result structure beyond the 'remix' field, but the description justifies its choices well for the given complexity.

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

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

Schema already covers 100% of parameters, giving a baseline of 3. The description adds semantic value by explaining the 'url' parameter in depth (no need to track, untracked URLs fetched automatically) and describing the result or output expectations, going beyond what the schema's terse descriptions or examples provide. It could go further by addressing constraints or relationships between 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 is specific about verb+resources: takes a post (URL or id) plus a niche and produces an adapted content idea with a detailed output breakdown. Clarifying language ('adapted content idea: rewritten title and description, segment-by-segment script...') distinguishes it from siblings like get_post or crawl_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?

Clear guidance is provided: no crawl_profile round-trip is needed, untracked URLs are fetched automatically, and users should poll get_remix_result until the 'remix' field populates. However, it lacks explicit 'use X instead' alternatives or when NOT to use this tool, despite the sibling list offering related capabilities.

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 reveals useful behavioral details beyond annotations: it returns 'how many were removed plus the new profile count' and states the call is free. Since annotations already show this is a non-read-only mutation, the description adds appropriate cost and return-value context 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 short and front-loaded with the core action and return behavior. There is minor redundancy between 'Free to call' and 'Cost: free', but overall it is compact and readable.

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

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

For a simple two-parameter tool with no output schema, the description covers everything needed: what it does, what it returns, cost, and how to obtain the required profileIds. No essential information is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds extra semantic value by pointing to get_watchlist as the source for obtaining profileIds, which helps the agent understand where the ID values come from.

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 ('Removes'), a clear resource ('watchlist'), and explicit inputs ('given profileIds'), making it immediately obvious what the tool does. This clearly distinguishes it from siblings like add_watchlist_profiles and delete_watchlist.

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

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

The description provides clear usage context by telling the agent to 'Use get_watchlist to find the profileIds', which is practical guidance. However, it does not explicitly state when not to use this tool versus alternatives or give exclusion criteria.

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

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

Beyond the 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?

The description discloses the asynchronous nature, credit charging, automatic refund on failure, up-front rejection without charge, and attachment to get_post responses — all side effects not visible in the sparse annotations. It does not contradict the annotations; readOnlyHint=false is consistent with a queueing, credit-consuming operation.

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?

Five sentences, each adding a distinct fact: what it does, accepted inputs, async behavior/result location, credit/refund policy, and excluded inputs with the correct alternative. The most important identifying behavior 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 two-parameter async tool with no output schema, the description covers invocation inputs, workflow, cost consequences, failure refunds, and unsupported cases. No additional information is needed for an agent to select and call it correctly.

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

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

Schema coverage is 100%, and the schema already explains that url is an alternative to postId and that postId is the internal post id. The description restates this as 'a public post URL or an internal post id' without adding format, precedence, or required-value details, so it adds little beyond the schema.

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

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

The description names a specific action ('Queues AI transcription of the spoken audio for a video post') and a clear resource, while distinguishing it from the sibling request_visual_analysis. It also clarifies accepted input forms, leaving no ambiguity about what the tool does.

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

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

It explicitly states when the tool is appropriate (video posts with spoken audio) and when it is not (image slideshows and photo posts), and names the alternative request_visual_analysis for the excluded cases. The async workflow is also prescribed with get_job_status, so an agent knows exactly how to consume the result.

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

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

The description goes well beyond the annotations by disclosing asynchronous job semantics, credit charging on queueing, automatic refunds on failure, and where the result will appear. No contradiction with the annotations exists; the non-read-only, non-idempotent hints align with the described queueing 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 dense but every sentence earns its place: output structure by media type, accepted inputs, async workflow, integration point, failure refund, sibling reference, and cost. It is front-loaded with the core purpose and uses a comma-separated structure to avoid excessive verbosity.

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

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

Given that there is no output schema, the description compensates by explaining the job reference return, the polling mechanism via get_job_status, how results surface in get_post, and the credit/refund policy. This is sufficient for an agent to invoke and poll the tool 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?

The schema already describes both parameters comprehensively (public post URL and internal post id) with 100% coverage. The description adds only minor context about post URL being public and post id being internal, which largely duplicates the schema.

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

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

The description clearly states the tool 'Queues a structured visual analysis for a post' and distinguishes the output types for video versus slideshow. It also explicitly identifies itself as the 'visual twin of request_transcript', which disambiguates it from a closely related sibling.

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

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

It gives explicit workflow guidance: returns a job reference to poll with get_job_status and attaches the completed analysis to get_post responses. It also mentions request_transcript as the analogous alternative, providing the agent with enough context to choose by modality.

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 meaningful behavior: found:true returns the postId, found:false distinguishes untracked profile vs. just this post, and each call costs 1 credit. It also warns about short-link expansion, adding context the annotations alone do not 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 dense but well-structured: the first sentence states the core purpose, and subsequent sentences add conditional guidance and edge-case handling. Every sentence earns its place, including the cost note, with no redundant filler.

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

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

With no output schema, the description compensates by explaining the found:true/found:false result semantics and how the returned postId connects to get_post, request_transcript, download_post_media, and remix_post. It also covers untracked-profile handling, URL expansion, and cost, making it fully adequate for agent 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?

Although the schema already describes the url parameter with 100% coverage, the tool description adds substantial meaning by enumerating supported platforms (TikTok, Instagram, YouTube) and explicitly instructing that short links must be expanded. This goes well beyond the schema's one-line 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 clearly states the tool's function: it takes a public post URL and resolves it to the tracked post, positioning it as the entry point for link-based input. It also distinguishes itself from siblings by explicitly noting that remix_post accepts untracked URLs directly and can skip this lookup.

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

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

The description gives explicit when-to-use guidance: use when the input is a link. It also names alternatives like crawl_profile for untracked profiles and remix_post for direct ingestion, plus a prerequisite that short links must be expanded to canonical URLs first.

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 read-only/idempotent annotations, the description discloses meaningful behavior: the database is continuously crawled, results may include deleted posts and deactivated accounts, stats are frozen at deletion, and each call costs 1 credit. No contradiction with the annotations exists.

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

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

The description is dense and front-loaded with the essential ranking concept, and every sentence carries useful information. The long enumerative sentence is justified by the large parameter set, though it is slightly harder to scan than a more structured layout would 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?

Given the absence of an output schema and the 17-parameter surface, the description explains return contents (metadata, stats, thumbnails) and important edge cases (deleted posts, deactivated profiles, cost). Missing details like pagination and watchlist scoping are minor but prevent a perfect score.

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 only 18% schema description coverage, the description compensates by enumerating the filter dimensions (platform, keyword, exact handle, content type, outlier-score band, view band, follower band, engagement-rate band, time window) and sort options. It does not define units for numeric bands or mention page/pageSize/watchlistId semantics, so it is not fully complete.

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 names the resource ('continuously-crawled database of social media posts') and the core verb ('Search...ranked by outlier score'), making the purpose specific and unambiguous. It does not explicitly contrast itself with siblings like get_trending_outliers, but the filter/search framing sufficiently distinguishes it from profile-oriented 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 an explicit use context: 'Use this to find proven viral formats in any niche before creating content.' It also advises filtering out deleted/deactivated posts when only live content is wanted. It does not, however, name alternatives or state when not to use this tool.

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

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

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.