Influship

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds behavioral context: 'Cheap and fast', 'Returns a short list of matching creators with their IDs, platforms, and display names', and shows how results feed into downstream tools. No contradictions.

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

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

The description is longer than typical but well-structured: purpose, usage guidance, examples, and downstream usage. Every section serves a distinct function and there's no fluff. Slightly verbose but highly informative.

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 purpose, usage context, alternatives, examples, return format, and downstream integration. Given the tool's simplicity and the presence of an output schema, this is fully complete.

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

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

Schema description coverage is 100%, so the schema already documents each parameter. The description reinforces the meaning of q by referencing 'partial input' but doesn't add details about limit, scope, or platform 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 opens with a specific verb and resource: 'Autocomplete creator names, usernames, or display names from partial input.' It explicitly differentiates from siblings by stating 'prefer over search_creators', 'Use get_profile instead', and 'Use semantic_search_creators only for discovery...'.

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

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

Explicit when to use: 'Use this for fast lookup when the user types a partial handle or name' and 'Cheap and fast — prefer over search_creators'. Also explicit exclusions: 'Use get_profile instead when the user gives an exact platform+username pair' and 'Use semantic_search_creators only for discovery...'.

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 non-destructive behavior, and the description adds valuable context beyond that: seeds are blended via multiple embedding types, results are ranked with scores, and a seed_not_found response means the seed cannot be used for similarity matching and should not be retried. This helps the agent reason about outcomes.

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

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

The description is front-loaded with the core purpose, followed by usage conditions, seed-passing semantics, result behavior, and sibling routing. Every section earns its place, including the examples that concretize abstract guidance. It is longer than average but not padded.

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

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

For a 9-parameter tool with an output schema and annotations, the description is exceptionally complete: it explains when to use the tool, how to pass seeds, what alternative tools to use, what the result looks like, and how to handle errors. The examples tie everything together.

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, but the description adds real meaning to the seed-related parameters: it explains that seed_creator_ids are canonical UUIDs, that seed_profiles are platform+username pairs, and that handlers should be resolved via autocomplete_creators first if needed. It also clarifies that seeds can be passed in either or both forms.

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

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

The description opens with a specific action and resource: 'Find creators SIMILAR to one or more seed creators.' It clearly distinguishes this from sibling tools by naming semantic_search_creators and match_creators as alternatives, so the agent can tell which tool fits without opening schemas.

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

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

Explicit when-to-use guidance is provided: use when the user already knows a seed creator they like. It also gives concrete when-not-to-use guidance by directing topic/niche queries to semantic_search_creators and candidate scoring to match_creators, reinforced with user-phrase examples.

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 signal read-only, non-destructive behavior, so the description's burden is lower. It adds useful behavioral detail beyond annotations: for platform+username inputs it 'resolves through the profile endpoint and returns the profile record plus the underlying creator record,' and for UUID inputs it explains how `include: ['profiles']` changes the response. It does not discuss edge cases like invalid/missing identifier combinations, but the main response-shaping behavior is transparent.

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

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

The description is front-loaded with the core purpose, followed by explicit when-to-use bullets, then parameter behavior, then examples. Every sentence serves a distinct purpose and the examples are compact and illustrative rather than redundant. Despite covering two input modes and several sibling tools, the structure keeps the content scannable.

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 output schema and annotations, the description is complete for an agent to select and call the tool correctly. It covers both identifier modes, the optional include behavior, example invocations, and clear routing to relevant siblings. No critical operational context—such as whether this is read-only, destructive, or how to format inputs—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, but the description adds significant meaning beyond the schema. It explains the mutually exclusive lookup modes: `id` alone versus `platform`+`username`, and clarifies that `include: ['profiles']` only matters in the UUID path because the platform+username path already returns matched profile context. The examples additionally map user phrasing to concrete parameter values.

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

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

The description opens with a specific verb and resource: 'Fetch the full record for a single creator by ID or exact platform username.' It clearly distinguishes this tool from siblings by naming `get_profile` for profile-specific needs and `lookup_profiles` for batch exact lookups. The two supported lookup modes are explicit and each is tied to prior tools like `search_creators` and `semantic_search_creators`.

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 says 'Use this when you already have either' and enumerates the two exact conditions. It also gives explicit exclusions and alternatives: use `get_profile` if profile metrics are the main need, and use `lookup_profiles` for batch exact profile lookups. Examples map natural user requests to the correct parameter combinations.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds valuable behavioral context beyond annotations by specifying that the data is raw and fresh, and enumerating the exact content types (coauthors, tagged users, paid partnership metadata, etc.), which helps the agent set expectations about data completeness and structure.

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

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

The description is compact and front-loaded: the first sentence states the action and resource, and the second sentence provides usage guidance and data scope. Every sentence earns its place with no filler, making it an exemplary concise description.

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

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

Given the tool's simplicity (one parameter), the presence of an output schema, and safe annotations, the description fully covers the necessary context: what data is returned, when to use the tool, and why it exists. Nothing critical is missing.

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

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

The input schema provides 100% coverage of the single parameter 'shortcode' with a clear description ('Instagram post shortcode from a /p/, /reel/, or /tv/ URL'). The tool description does not add additional parameter semantics, but the schema fully documents the parameter, so 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 uses a specific verb ('Fetch') and resource ('raw Instagram post-page data by shortcode'), clearly distinguishing it from sibling tools like get_instagram_posts (plural) and get_instagram_post_transcript. It further differentiates by enumerating the unique data fields it returns (coauthors, paid partnership metadata, video versions, etc.), making the purpose unmistakable.

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

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

The description provides an explicit when-to-use scenario: 'when the user needs fresh raw Instagram post metadata that is not guaranteed on regular cached post-list endpoints yet.' This implies an alternative (cached post-list endpoints) and a condition for exclusion, though it does not name a sibling tool explicitly. The guidance is clear and contextually useful.

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

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

Beyond the annotations (readOnlyHint=true, destructiveHint=false), the description discloses automatic transient upstream recovery and per-item success/error details. This adds valuable information about retry behavior and partial failure handling that annotations do not cover, though it omits specifics like rate limits or lookback windows.

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 well-structured: the first sentence states the core function, and the second explains the return behavior. Every sentence contributes meaningful information without redundancy, making it highly efficient for an agent to parse.

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

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

With a single well-documented parameter, an output schema, and annotations covering safety, the description fully addresses the tool's operational context. It adds the necessary behavioral narrative (retries, per-item errors) to round out what structured fields cannot express, leaving no critical gaps.

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 thorough description of the 'shortcodes' parameter, including source URL types and min/max constraints, giving 100% coverage. The description adds the concept of 'bounded list' but does not substantially extend beyond the schema's parameter details, maintaining the baseline for high schema coverage.

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

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

The description clearly states a specific verb (fetch), resource (raw Instagram post-page data), and input scope (bounded list of shortcodes). It distinguishes itself from siblings like get_instagram_post by emphasizing the plural 'posts' and the 'raw API' nature, making its batch purpose unambiguous.

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

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

Usage is implied through terms like 'bounded list' and 'raw API', which suggest batch retrieval of unprocessed data. However, there is no explicit comparison with alternatives such as get_instagram_post or transcript tools, so the description relies on sibling context rather than clearly stating 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?

While annotations already indicate read-only and non-destructive behavior, the description adds valuable cache-related details: the response includes raw post metadata on a cache miss and omits the post field on a cache hit. This context is not available from annotations or the schema, enhancing transparency about response variability.

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

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

The description is two succinct sentences, front-loaded with the main action and immediately providing relevant behavioral and alternative-tool guidance. Every word earns its place with no redundancy.

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

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

Given the presence of an output schema and the description's coverage of cache behavior and a sibling-tool alternative, the tool is fully contextualized. The agent has enough to select and invoke it correctly without missing critical 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?

Schema description coverage is 100% with clear descriptions for both 'shortcode' and 'language'. The description does not add parameter-specific semantics beyond mentioning 'by shortcode', so the baseline of 3 applies where the schema carries the full 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 the tool's function: 'Transcribe an Instagram video post by shortcode through the raw API.' This is a specific verb (transcribe) and resource (Instagram video post), and it distinguishes from the sibling 'get_instagram_post' by noting the cache behavior and explicitly recommending that tool for metadata needs.

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 alternative: 'use `get_instagram_post` when you need post metadata with a cached transcript.' This provides a clear when-not-to-use condition and directs the agent to a sibling tool, matching the high-standard example.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, which the description supports. The description adds valuable behavioral context: the nested post field is present on cache misses and omitted on cache hits, explaining a subtle response behavior not evident from annotations. It doesn't mention rate limits or failure modes, but given the read-only annotation, the added cache behavior detail justifies 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 two sentences and front-loaded with the primary action. Every sentence earns its place: the first states the function and scope, the second explains a nuanced cache behavior and points to an alternative. 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?

Given the tool has an output schema, an input schema with 100% parameter coverage, and read-only annotations, the description provides sufficient context. It covers the key edge case of cache hits/misses, directs to the sibling tool for different needs, and explains the bounded nature. No significant gaps remain for an agent to select and invoke it correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds extra semantics beyond the schema: it specifies 'bounded list' (aligning with maxItems 10), explains the 'nested post field' behavior in relation to shortcodes, and clarifies that language is optional for auto-detection. This adds meaningful context above the schema descriptions, warranting a 4.

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 specific verb 'Transcribe' and resource 'Instagram video posts by shortcode through the raw API'. It distinguishes from siblings by explicitly mentioning 'bounded list' and directing users to `get_instagram_posts` for post metadata, and the sibling list includes singular/plural transcript tools, which this differentiates.

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 says when to use this tool vs alternatives: use it when you need transcripts for a bounded list of shortcodes, and use `get_instagram_posts` when you also need post metadata for every shortcode. This explicit alternative guidance is clear 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?

Adds rich behavioral context beyond the read-only annotation: describes pagination via next_cursor/has_more, limit cap at 50, default sort behavior, and cursor-tied-to-sort error semantics. This gives an agent a clear model of how the tool behaves and what to expect.

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?

Though moderately long, the description is well-structured with a clear lead sentence, parameter guidance, return summary, and concrete examples. Every section adds value and none feels redundant with the schema.

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

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

For a list tool with pagination, multiple sort modes, and an OR identifier pattern, the description fully covers identification, sorting defaults, pagination semantics, and return fields. Output schema handles structured return details, and the description supplements with usage context and examples.

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%, but the description adds crucial meaning: the OR relationship between creator_id and (platform+username), the semantics behind each sort enum value, and how to use cursor from next_cursor. This goes beyond the schema's field-level descriptions.

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

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

The description opens with a specific verb and resource ('Fetch a creator's posts, sorted and paginated'), making the core purpose clear. However, it does not explicitly distinguish this tool from sibling get_instagram_posts, so it misses the sibling-differentiation criterion for a 5.

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

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

Provides explicit usage scenarios and examples ('Use this when the user asks to see what a creator has posted'), plus sequencing guidance with get_profile and match_creators. It lacks clear when-not-to-use or alternative-tool exclusions, so it earns 4 rather than 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds meaningful behavioral context: case-insensitive matching is handled server-side, the @ sign should be omitted despite the schema accepting it, and the response includes both the profile record and underlying creator record. This goes beyond what annotations alone convey.

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

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

Despite being longer than average, the description is tightly structured: a lead sentence, explicit usage policy, three clarifying examples, and alternative-tool routing. Every section earns its place, especially given the large sibling set that could be confused with this tool.

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

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

With a full input schema, an output schema, and read-only annotations, the description covers everything an agent needs: trigger conditions, parameter formatting, alternatives, and response contents. Nothing essential for correct invocation is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by clarifying how to pass the username ('exactly the username they typed without the @ sign'), that matching is case-insensitive, and how to extract platform and username from URL-style user input. This reduces ambiguity beyond the schema's property descriptions.

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

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

The description starts with a specific verb and resource ('Fetch a single social profile by (platform, username)') and immediately distinguishes it from siblings like search_creators, get_creator, and lookup_profiles. The purpose is unambiguous even before reading the schema.

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

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

The description explicitly states when to use this tool ('Always use this first when the user gives an exact handle on a specific platform'), when not to ('Do not use search_creators for an exact platform+username lookup'), and names alternatives for other cases ('use get_creator instead', 'use lookup_profiles'). Concrete examples make the routing decision trivial.

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 non-destructive. The description adds valuable behavioral context by clarifying it returns one configured sample creator with social profile context, framing it as a preview, and instructing the agent on what to say after showing the preview. This exceeds what annotations alone provide.

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

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

The description is concise and front-loaded with the primary use case. Every sentence earns its place: the first states when to use it, the second defines the tool's behavior and exclusions, and the third gives necessary post-invocation guidance. No redundant or promotional language is present.

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 low complexity, zero parameters, existing output schema, and read-only annotations, the description covers everything needed to invoke and respond correctly. It includes when to use the tool, what it does, what it should not be used for, and even the required follow-up message.

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 zero parameters, so there is no parameter semantics for the description to add. With schema coverage at 100%, the baseline of 4 applies; the description does not need to compensate for missing parameter 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 states a specific verb and resource: 'Fetches one configured sample creator with social profile context.' It clearly identifies this as a preview tool and distinguishes it from search, discovery, matching, and comparison requests, making it easy to separate from siblings like search_creators and match_creators.

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?

Usage context is explicit: use when a user wants to preview what Influship can return before linking an account. It also explicitly states what not to use it for and provides post-preview conversational instructions, leaving no ambiguity about when or how to apply 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?

Beyond annotations (readOnlyHint, openWorldHint), the description discloses that data is 'current' and 'normalized', that a leading @ is accepted, and that it is a 'metered live-data request'—important cost/latency context. It also lists returned categories, adding behavioral expectations without contradicting annotations.

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

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

Three sentences: purpose, return contents, and input handling/cost context. Each sentence is informative and front-loaded with the core action. No filler 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 an output schema present (not shown), the description does not need to detail return structure. It covers key aspects: input normalization, live/metered nature, and high-level output categories. For a simple one-parameter tool, this is complete and appropriately scoped.

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 has one parameter (username) with no description, so the description carries the full burden. It explains that a leading @ is accepted and usernames are normalized, giving practical meaning to the parameter. While it doesn't provide examples or edge cases, it sufficiently compensates for the 0% 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 uses specific verb 'Fetch' with resource 'TikTok profile' by username, clearly distinguishing from general profile/creator tools. It also states the scope (current, normalized) and returns high-level metrics, making the tool's purpose unambiguous.

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

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

The description indicates this is for TikTok profiles and is a live-data request, implying when to use it (when you need current TikTok data) but does not explicitly name alternatives or exclusions. It provides clear context but lacks direct comparison to sibling tools like get_creator or get_profile.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, destructiveHint), the description discloses important behaviors: returned media URLs are temporary, media capture is asynchronous, content resolves against the US region, and the request is metered. These details meaningfully inform an agent's expectations and would not be inferred from the schema or annotations alone.

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

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

The description is compact yet information-dense. The main action is front-loaded in the first sentence, and each subsequent sentence adds a specific caveat or behavioral detail. No filler or redundant phrases are present.

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 simplicity (one required parameter, fixed region, output schema provided), the description covers all essential call-time context: URL format variants, region behavior, temporary media URLs, asynchronous capture, and metering. An agent has enough information to correctly select and invoke the tool without encountering surprises.

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 0%, so the description must compensate for parameter meaning. It does so by explaining what URL forms are accepted ('Canonical video URLs and TikTok share URLs') and clarifying that the region is always US ('Content always resolves against the US region'). This adds practical semantics beyond the bare 'uri' format and 'const: US' in the schema.

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

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

The description opens with a specific verb ('Fetch'), a clear resource ('TikTok video URL'), and the exact kind of data returned ('normalized details and current engagement metrics'). This clearly distinguishes it from sibling tools like get_tiktok_profile, get_tiktok_video_transcript, and list_tiktok_video_comments, which concern different resource aspects.

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 the tool: it accepts canonical and share URLs and is a metered live-data request, implying it should be used when current engagement metrics and normalized details are needed. It does not explicitly name alternatives or exclusions, but the accepted URL types and live-data warning offer actionable usage guidance.

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

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

Beyond the readOnly/openWorld/destructive annotations, the description discloses concrete behavioral traits: transcript content does not expire and is reused, and requests are metered with potentially slower generation. This gives the agent actionable expectations not encoded in the 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?

Four brief sentences, each carrying distinct information: the primary action, the output format, caching behavior, and performance characteristics. Front-loaded with purpose and no redundant language.

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 an output schema and strong annotations, the description covers operation, expected returns, caching, metering, and latency. There are no significant gaps; the description is complete for selecting and invoking 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 input schema has a single url parameter with 0% description coverage. The description only implies the URL should point to a TikTok video; it does not explicitly state accepted formats or normalization expectations. This is adequate but not fully compensating for missing schema descriptions.

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

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

The description opens with 'Fetch or generate a normalized TikTok video transcript,' a specific verb-object pair that precisely identifies the tool's function and scope. Mentioning 'TikTok' and 'transcript' clearly differentiates it from sibling tools like get_instagram_post_transcript.

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 clear operational context: canonical transcripts are reused on later requests and generation is metered/slow. This implies when a cached result may be available but does not explicitly name alternatives or exclusions, so it falls short of a 5.

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

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

Annotations already cover read-only, open-world, and non-destructive behavior. The description adds value by noting this is a 'metered live-data request,' which warns about cost and data freshness, and it mentions the option to include recent videos. This is useful behavioral context beyond the annotations, though it doesn't detail pagination or error handling, which are partly covered by the output schema.

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

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

The description is two sentences with no fluff. The primary purpose is front-loaded, and the optional video inclusion is mentioned as a secondary clause. It is efficient 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?

The output schema provides return structure, annotations cover safety, and purpose is clear. However, the lack of explanation for video_limit and include_videos leaves a gap in parameter understanding. The description could be more complete by stating that video_limit controls the number of recent videos when include_videos is true, but it does not.

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

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

Schema description coverage is only 33% (only 'channel' is described). The description says 'Optionally includes recent videos,' which hints at include_videos, but it does not explain video_limit (e.g., range, default) or how it interacts with include_videos. Given the low coverage, the description should compensate by clarifying these parameters, but it leaves them ambiguous.

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

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

The description clearly states the verb 'Fetch' and the resource 'YouTube channel', and specifies three identification methods (handle, channel ID, URL). This differentiates it from siblings like get_youtube_video and get_youtube_channel_transcripts, which focus on videos or transcripts rather than the channel object itself.

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 does not explicitly name alternatives or conditions for using this tool over others. It does mention 'metered live-data request,' which implies cost considerations but provides no direct guidance on when to choose this over, say, get_creator or search_youtube. Usage context is implicit but not explicit.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the read-only safety is covered. The description adds the metered batch context, which hints at cost or rate limits, but does not disclose how the video batch is selected, error behavior, or response shape. It adds some value beyond annotations but lacks depth.

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 with no redundancy. The purpose is front-loaded, parameters are summarized in one sentence, and the metered note is brief. Every sentence earns its place.

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

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

Given that an output schema exists (so return format is covered), the description covers all parameter groups and flags the metered nature. It does not mention potential volume limits or that it processes multiple videos sequentially, but for a batch operation with an output schema, this is reasonably complete.

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

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

Schema coverage is only 20% (only 'channel' has a description), so the description must explain the other parameters. It explicitly names the choices: 'video count, ordering, language, and whether timestamped segments are included', mapping directly to video_limit, sort_by, language, and include_segments. This adds meaning beyond the bare schema, though it does not specify value ranges or defaults.

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 ('Fetch'), a clear resource ('transcripts for a selected batch of videos from a YouTube channel'), and distinguishes this from sibling tools like get_youtube_video_transcript by emphasizing the batch and channel scope. An agent can easily tell this is the channel-level batch operation.

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

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

The description implies the tool is for batch transcript retrieval from a channel but does not explicitly state when to prefer it over alternatives (e.g., for a single video use get_youtube_video_transcript) or when not to use it. The context is clear enough from the name and phrasing, but explicit routing 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 declare readOnlyHint=true and destructiveHint=false, so the read-only nature is known. The description adds that the request is 'metered' and 'live-data', which conveys cost and real-time behavior beyond the annotations. This is valuable context that helps an agent anticipate side effects. However, it does not mention rate limits or error behavior, so it is not exhaustive.

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

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

The description is two sentences with no redundant phrasing. The core function is stated first, followed by a use case and a metering note. Every sentence adds value, and the structure is efficient and front-loaded.

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

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

For a tool with three parameters and an existing output schema, the description covers the essential context: what it does, when to use it, and a key behavioral constraint (metered live-data). It does not detail the response format, but that is provided by the output schema. The absence of explicit parameter descriptions is partially mitigated by the description's hints, so overall it is adequate but could be slightly enhanced for parameter clarity.

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 0%, so the description must compensate. It does imply 'q' is a partial phrase and that 'localized' relates to country and language codes, but it does not explicitly explain each parameter or their formats (e.g., ISO codes). The description bridges some gaps but leaves the agent to infer parameter details. This is above a 2 but short of clearly documenting 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 identifies the tool as fetching current localized YouTube query suggestions for a partial phrase. It uses a specific verb ('Fetch') and resource ('YouTube query suggestions'), and the phrase 'before search' distinguishes it from search tools like search_youtube. This gives an agent unambiguous understanding of the tool's purpose.

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

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

The description states it is useful for expanding topic seeds before search, giving a concrete use case. However, it does not explicitly contrast with sibling search tools or state when not to use it. The context is clear enough for routing, but lacks explicit exclusions or alternative guidance.

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

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

Beyond the readOnlyHint/openWorldHint annotations, the description adds the genuinely useful qualifier 'This is a metered live-data request,' warning agents of cost and freshness implications—valuable behavioral context an agent cannot infer from the annotations. The phrase 'exact publication data when available' hints at nullable/conditional returns for incomplete videos. It stops short of discussing rate limits, authentication, or error cases for invalid/deleted IDs, but given that annotations already signal a safe, read-only, open-world surface, the incremental disclosure is meaningful, pushing it above the minimum.

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

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

The description front-loads a strong, verb-first sentence that captures the tool's essence, then lists the specific return fields, and closes with the operational warning. Every sentence earns its place—no filler, no repetition of the tool name or obvious parameters, and the paragraph break separates the definition from the warning. It's tight without being sparse.

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 only one well-constrained parameter, comprehensive annotations, and a present output schema, the description doesn't need to detail the return structure and reasonably keeps that to a short list. The metered/live warning covers the key operational caveat for a data-retrieval tool. The only minor gaps (region restrictions, handling of deleted videos, rate limits) are edge cases that would be nice-to-have but aren't essential for correct invocation.

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

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

Schema description coverage is 0%, so the description carries the full explanatory burden, but with a single `video_id` parameter constrained by the YouTube ID regex pattern, the risk of misuse is low. The description's mention of 'a YouTube video ID' confirms the parameter's purpose in natural language. Since the parameter name plus the regex pattern already leave minimal ambiguity, the description's light touch suffices to reach a 4.

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

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

The description opens with a specific verb and resource: 'Fetch fresh metadata and engagement for a YouTube video ID.' It then enumerates concrete return dimensions (views, likes, comments, duration, tags, categories, channel identity) that clearly scope the tool to single-video metadata. This distinguishes it from siblings like get_youtube_video_transcript, get_youtube_channel, and search_youtube without being confused with them.

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 intended use—retrieving metadata for one YouTube video by ID—is implied by the verb 'Fetch' and the parameter name, and the metered-live-data note hints agents should call sparingly. However, there's no explicit routing to alternatives such as 'for transcripts, use get_youtube_video_transcript' or 'for channel data, see get_youtube_channel,' which the sibling list suggests would be valuable. No prerequisites, ordering constraints, or degradation conditions are stated; an explicit 'use this when' statement is absent.

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

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

Annotations already mark this as readOnly and non-destructive, so the description's main value is beyond that. It discloses that the request is metered and may take longer when captions need resolving, which is additional operational context not present in annotations. It does not contradict 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 and well-structured. The first sentence states the core purpose, and the second adds important context about metering and latency. It avoids unnecessary verbosity, though it could be slightly more explicit about usage guidelines. The information is front-loaded and scannable.

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 has an output schema (mentioned in context), the description doesn't need to detail return values. It covers the key aspects: normalization, timestamped segments, caption languages, and metering. However, it could benefit from specifying the default language behavior (e.g., 'auto' meaning auto-detect) and any limitations (e.g., videos without captions). The description is adequate but leaves some gaps.

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 0%, so the description must compensate. It explains that the tool returns timestamped segments and available caption languages, providing meaning for the 'language' parameter (caption language) and the output. However, it doesn't explicitly state the format of the video_id, but the schema already provides a regex pattern. This is a strong compensation for the lack of schema descriptions.

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

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

The description clearly states the function: fetches a normalized transcript for a YouTube video ID. It specifies the resource (YouTube video transcript) and the verb (fetch). While it does not explicitly distinguish from siblings like get_youtube_channel_transcripts, the focus on a single video vs. channel transcripts is apparent from the name and description.

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 useful context: it mentions the request is metered and may take longer when captions must be resolved, which implies use cases where the user accepts potential latency. However, it does not explicitly state when to use this tool versus alternatives like get_youtube_channel_transcripts, nor does it provide exclusions or specific scenarios.

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

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

Beyond the annotations (readOnlyHint=true, destructiveHint=false), the description discloses several non-obvious behaviors: cursor-based pagination, latest/popular ordering, temporary media URLs, canonical dataset piggybacking eligibility, US region resolution, and metering. This meaningfully enriches the agent's mental model without contradicting the annotations.

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

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

Three sentences with no filler. The main purpose is front-loaded, and each subsequent sentence adds essential operational context (pagination, ordering, temporary URLs, region, metering). Every sentence earns its place.

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

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

Given an output schema exists and annotations already cover safety, the description covers all operational essentials: pagination methods, ordering options, URL lifetime, regional resolution, and cost implications. An agent has everything needed to invoke this 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 0%, so the description must compensate. It explicitly explains cursor (pagination), sort_by (latest/popular), and region (US). Username is left implicit, but its meaning is obvious from the tool name and title. This is solid compensation, though not exhaustive.

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

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

The description opens with a specific verb and resource: 'Fetch one cursor-paginated page of current TikTok videos for a username.' This clearly distinguishes it from sibling tools like get_tiktok_profile (a single profile) or get_tiktok_video (a single video) and states its scope without ambiguity.

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

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

The description gives clear operational guidance—'Use the returned cursor to paginate and choose latest or popular ordering'—and flags that this is a metered live-data request, implying judicious use. It does not explicitly name alternative tools or state when not to use it, but the purpose sentence makes the use case self-evident.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds valuable behavioral context: it is cursor-paginated (not a one-shot fetch), metered (rate/cost implications), and live-data (not cached/historical). It also explains the pagination workflow, going beyond the structured fields.

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

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

Three short sentences, each serving a distinct purpose: what it does, how pagination works, and the metering/live-data implication. The description is front-loaded with the primary action and contains no filler or redundant 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 simplicity (two parameters, annotations present, output schema exists), the description fully covers what an agent needs: read-only behavior (via annotations), pagination handling, and the metered/live-data constraint. Return values are already defined by the output schema, so no additional 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?

Schema description coverage is 0%, so the description must carry the burden for parameters. It identifies the URL parameter as a 'TikTok video URL' and explains the cursor parameter with 'Pass the returned cursor to retrieve the next page.' Both parameters get meaningful contextual explanation, compensating for the schema's lack of descriptions.

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

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

The description opens with 'Fetch one cursor-paginated page of current comments for a TikTok video URL,' providing a specific verb (fetch), a clear resource (comments for a TikTok video), and a scoping qualifier (cursor-paginated page). This clearly differentiates from sibling tools like get_tiktok_video and list_tiktok_profile_videos, which focus on video metadata or profile feeds.

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 establishes clear context by stating it returns one page of current comments and that the returned cursor should be passed for the next page. While it does not explicitly list alternative tools, there is no other comments-related sibling tool, making the intended use unambiguous. It stops short of explicit when-not-to-use guidance.

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

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

Beyond the readOnlyHint=true annotation, the description discloses important runtime behavior: the response splits into `data` and `not_found`, and profiles are returned in no particular order, requiring re-correlation via platform/username. It also notes the round-trip efficiency benefit. These are not inferable from the schema or annotations.

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

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

The description is well-structured: a one-sentence summary, a when-to-use paragraph with examples, an explicit alternatives paragraph, and a return-behavior note. Every sentence earns its place, and the most critical information is front-loaded. Despite being a bit long, it is appropriately sized for the tool's complexity and avoids fluff.

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

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

The description is complete given the tool's complexity. It covers purpose, usage, examples, alternatives, and return behavior. The existence of an output schema means the description need not re-explain return values, but it still adds critical context like unordered results and the not_found split. Nothing important is missing.

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

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

The input schema already covers the `profiles` array with item definitions, required fields, and min/max constraints (100% coverage). The description adds meaningful context by framing these as '(platform, username) pairs' for 'exact batch handle lookup' and explaining that not_found contains unrecognized pairs. This goes slightly beyond the schema's bare 'Profiles to lookup' with extra usage semantics.

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

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

The description opens with 'Batch-fetch up to 100 profiles by (platform, username) pairs' – a specific verb, resource, and constraint. It then clearly distinguishes this tool from siblings, noting that `get_profile` handles a single exact pair, `search_creators` and `autocomplete_creators` handle fuzzy input, and `semantic_search_creators` handles topical discovery.

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

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

The description gives explicit when-to-use guidance: 'when the user has a list of handles and you need profile data for all of them at once.' It also provides concrete examples of user requests that should and should not use this tool, and names alternative tools for other scenarios (e.g., semantic_search_creators for 'Find wellness creators in Austin'). No ambiguity remains.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: it returns a match score (0-1), a good/neutral/avoid decision, and structured reasons, and it clarifies that candidates can be passed as UUIDs and/or profiles. This goes beyond annotations, though it doesn't describe sorting, pagination, or failure behavior, so it isn't a 5.

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

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

The description is longer than average but well-organized: core purpose first, followed by parameter guidance, sibling disambiguation, and concrete examples. Each sentence adds value, though the example section is somewhat verbose and could be tightened without losing 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?

Given the tool has 4 parameters, full schema coverage, an output schema, and 13 sibling tools, the description provides sufficient context: it explains what the tool does, when to use it, how to handle different input forms, how it relates to siblings, and includes both brief and full user-intent examples. There are no significant gaps for an agent to invoke it correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds practical parameter semantics by stating that creator_ids and profiles can be used 'and/or', that intent_query is 'the brief the LLM reasons against', and that intent_context is optional extra context (target audience, brand values, prior collabs). This helps an agent compose valid inputs beyond what the schema alone conveys.

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

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

The description opens with a specific verb+resource: 'Score how well specific creators fit a campaign brief or search intent.' It clearly distinguishes this from sibling tools by noting the tool evaluates existing candidates, whereas semantic_search_creators is for discovery and search_creators for resolving 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?

It provides explicit when-to-use guidance: use when the user already has candidate creators in mind and wants fit evaluation. It also names alternatives with explicit conditions ('Use semantic_search_creators when you don't have candidates yet', 'Use search_creators first when you only need to resolve rough creator names/handles', 'Use find_lookalike_creators when you want creators similar to known good fits'). Realistic user-phrasing examples reinforce 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?

The description warns that the tool 'may consume Influship account or API usage,' which is useful cost-related context. However, annotations do not include readOnlyHint, leaving the possibility of side effects unclear; the description does not clarify whether any persistent state changes occur or how the rendering process behaves in detail.

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

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

The description is two sentences, front-loaded with the usage trigger, and contains no filler. Every clause earns its place.

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

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

Given the output schema exists, the description adequately covers the input requirements, process, and a cost caveat. It could be more thorough by noting when not to use this tool or how the output relates to other render tools, but it remains 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?

Schema coverage is 100%, so the schema already documents all parameters. The description adds the qualifiers 'canonical' and 'specific' but does not meaningfully enrich understanding beyond the schema.

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

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

The description clearly states the tool fetches current creator details, scores each against a campaign brief, and renders a side-by-side comparison. This distinguishes it from sibling tools like render_creator_profile (single profile) and search_creators (discovery).

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

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

The description explicitly opens with 'Use this when the user has 2–4 canonical creator IDs and a specific campaign brief,' providing clear usage context. It does not mention alternatives or when not to use it, but the trigger conditions are well-defined.

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

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

With all annotation hints false, the description carries the burden and discloses key behavior: it fetches the current creator record and up to six recent posts, and it 'may consume Influship account or API usage.' This cost/resource warning is valuable beyond what annotations provide. It does not describe side effects or reversibility, but the operation is presented as a fetch/read, and the consumption warning is sufficient.

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?

Two sentences, front-loaded with the usage trigger ('Use this when...'). Every phrase adds value: the scope ('one canonical creator ID'), the data retrieved, and the cost warning. No fluff 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 tool with one parameter and an existing output schema, the description explains the data scope (record + up to six posts) and the usage cost caveat. It gives enough context for an agent to decide appropriately. It could have mentioned how this differs from get_creator/get_profile, but the 'visual deep dive' phrasing and cost warning provide sufficient differentiation.

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 100% coverage with a clear description for creator_id ('Canonical Influship creator ID.'). The tool description merely repeats 'canonical creator ID' without adding format details or constraints. Since the schema does the heavy lifting, 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 a specific action: 'visual deep dive on one canonical creator ID' and describes what it fetches ('current creator record plus up to six recent posts'). It distinguishes itself from siblings like render_creator_comparison and render_creator_shortlist by focusing on a single creator and a visual/deep-dive format.

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 a clear when-to-use directive: 'Use this when the user wants a visual deep dive on one canonical creator ID.' It also implicitly differentiates from simpler lookup tools by flagging that it 'may consume Influship account or API usage,' suggesting it's for heavier, explicit requests. It does not name alternative tools or exclusions, but the context is clear.

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

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

Annotations are all false, so the description carries the burden. It discloses that the tool fetches stored creator details, preserves ranking/confidence/evidence, and 'may consume Influship account or API usage.' This adds valuable behavior context beyond the annotations, though it doesn't elaborate on output format (covered by output schema).

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

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

Five sentences, none wasted. It front-loads the primary use case, then gives parameter routing, a prerequisite, and a cost warning. The structure is clear and scannable.

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 usage context, parameter selection, prerequisites, and side effects. It doesn't explicitly state whether search_id and creator_ids are mutually exclusive, which is a minor gap given neither is required in the schema. Overall it is highly complete for a rendering 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 baseline is 3. The description adds important parameter semantics: search_id preserves exact ranking/confidence/evidence, creator_ids are only for lookup results, and the 'do not invent IDs' warning. This goes beyond the schema's field descriptions and clarifies parameter selection rules.

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 renders a shortlist of 1–8 creator cards for scanning, and distinguishes it from siblings like render_creator_profile and render_creator_comparison by specifying the discovery/lookup context. It also specifies the exact resource (creator cards) and the action (render/shortlist).

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 when to use the tool ('when discovery or lookup tools have returned results'), and provides conditional guidance for parameters: use search_id after semantic_search_creators, or creator_ids for name/handle lookup results. It also says 'Always call an Influship data tool first; do not invent IDs', which gives a clear prerequisite and an alternative direction.

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, so the description adds valuable context about dual routing: it can return either autocomplete-style lookup results or legacy semantic results depending on the query, and it preserves backward compatibility with legacy fields. This goes beyond what annotations provide.

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

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

The description is longer than average but well-structured with a clear purpose, usage guidance, examples, and return-value notes. Every section carries useful information for a tool with dual behavior; minor redundancy could be tightened but complexity justifies the length.

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

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

Given the tool's 12 parameters, dual routing, existing output schema, and rich annotations, the description is highly complete. It explains return types, downstream tool chaining, and the legacy fallback behavior, giving an agent all context needed to select and invoke 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 input schema covers all 12 parameters (100% coverage), so the baseline is 3. The description adds meaningful semantics by explaining when to use query_type 'creator_lookup' versus 'semantic_discovery' and showing examples with exact query strings. However, the schema's query description contradicts the tool's purpose by saying 'do not pass exact handles or usernames here', which the description does not explicitly correct, creating 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 this tool finds a creator by name/handle while also preserving legacy semantic search. It distinguishes from siblings by explicitly naming get_profile for exact handles on specific platforms and semantic_search_creators for topical discovery, and it provides illustrative examples.

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 as the default creator lookup for creator-ish strings, prefer get_profile for exact handles on a specific platform, and prefer semantic_search_creators for new topical/niche discovery. Concrete examples map user requests to the correct tool and query_type.

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 already establish a safe, volatile read (readOnlyHint, openWorldHint, destructiveHint=false), so the description is not under pressure to justify side effects. It adds genuinely useful context about pagination semantics ('Pass next_cursor back as cursor') and cost ('Each page is one metered request'). It doesn't cover rate limits or freshness windows, but for a read-only search tool this is adequate.

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 with zero fluff. The purpose is front-loaded, the filter dimensions are listed in parallel, and the pagination/cost closure is actionable. Every clause earns its place.

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

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

For a 9-parameter search tool, the description covers the essential workflow—search, filter, paginate, budget for pages—and the presence of an output schema plus safe-read annotations lightens the compensatory burden. Gaps remain: behavior at the limit cap (50), the exact response shape of next_cursor, and whether codes are ISO-format are unaddressed. Adequate, not rich.

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

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

At 0% schema description coverage, the description must compensate—and it does so only loosely. 'upload window, popularity, result type, duration, country, and language' roughly maps to upload_date, sort_by, content_type, duration, country_code, and language_code, but mappings like 'popularity'→sort_by require inference and the cursor/next_cursor naming mismatch could confuse. Cursor pagination is clearly explained, but q, limit, and ISO code formats rely on name inference.

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?

'Search current YouTube results with discovery filters and cursor pagination' is a specific verb+object pair with the two differentiators named. The word 'current' usefully signals a live-results guarantee. It doesn't explicitly distinguish itself from siblings like search_creators or get_youtube_video, but the function is unambiguous.

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

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

It implies when to use this tool (search and filter YouTube, paginate with a cursor) but never names alternatives or exclusion conditions. The 'one metered request' note starts to frame a cost-based decision but doesn't guide the agent (e.g., 'prefer this over get_youtube_video for discovery', or 'use search_creators for creator lookup'). An agent must infer the boundary from the tool name.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds meaningful behavioral context beyond annotations: it explains the hybrid vector search mechanism, states that results may be lookalike/topical matches, and acknowledges that exact usernames may be missed. It also advises using flat numeric fields to constrain results, which clarifies expected 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 long but well-structured and every sentence earns its place. It opens with a clear purpose, gives concrete usage rules, includes illustrative examples with user queries, and differentiates from siblings. The examples are compact and highly informative, making the length appropriate for the tool's complexity.

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

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

Given the tool's complexity, its 9 parameters, and a rich sibling landscape, the description is complete. It covers the query semantics, return value summary, filtering approach, and exclusions, and it complements the existing output schema and annotations. No critical usage context 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 value beyond the schema by explaining the nature of the query parameter (natural-language, topic-based) and by explicitly instructing to use the flat follower, engagement-rate, and verified fields for numeric constraints. This enriches parameter understanding, though the schema already documents each parameter well.

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

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

The description states a specific verb and resource: 'Semantic discovery search for influencers/content creators using natural-language queries.' It clearly distinguishes itself from sibling tools by explicitly naming alternatives like get_profile, search_creators, lookup_profiles, find_lookalike_creators, and match_creators.

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

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

The description provides explicit when-to-use guidance: 'Use this only when the user asks to discover creators by topic, audience, geography, niche, content style, or campaign criteria.' It also gives explicit when-not-to-use instructions and names alternative tools for exact handle lookup, similar-creator search, and scoring creators against a brief.

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