AIsa Instagram

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

Annotations already declare destructiveHint=true and openWorldHint=true, so safety is covered. The description adds valuable behavior: independence of items (one failure doesn't cancel others) and per-call billing. These are not derivable from annotations and help the agent set expectations.

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

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

Three short sentences with zero filler. The action and limit are front-loaded. The phrase 'tool-router's batch_use' is redundant since it restates the tool name, but it's a minor flaw. Overall it is concise and well-structured.

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

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

With annotations covering destructive behavior and an output schema presumably describing results, the description covers the key operational aspects: concurrency limit, independence, and billing. It doesn't mention error reporting formats, but those likely live in the output schema. It is sufficiently complete for a batch tool.

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

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

Schema description coverage is 100%, so the schema fully documents each parameter. The description adds no parameter-specific details. The calls parameter's description already explains the structure and batching context, so the baseline of 3 applies; the description doesn't need to compensate.

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

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

The description states a clear action (execute) and resource (operations) with a concrete limit (up to 20) and concurrency. It doesn't explicitly name the sibling 'use' for single operations, but the distinction is clear enough from the concurrency and limit. The redundancy of 'tool-router's batch_use' is minor.

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 no guidance on when to use this tool versus the sibling 'use' tool. The schema note about 'steps at the same execution_level of a plan go in one batch' is helpful, but it lives in the schema, not the description. The description only implies batching via concurrency but doesn't state when to choose it over the single-operation alternative.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds meaningful context: it is free, stops before any spend, and explains how price.model varies (quoted, list, dynamic, composed). It also clarifies that suggested_max_price_usd has headroom. This goes beyond the annotation flags and gives the agent a clear model of what happens.

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 moderately long but well structured: it opens with the core purpose, then explains the price model in a dedicated paragraph. No redundancy or filler. It front-loads the most critical information (contract fields) and then gives necessary detail about price semantics. Slightly dense but not overly verbose.

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

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

The tool has an output schema, so return values need no description. The description covers the key behavioral aspects (no spend, pricing models, max_price headroom) and clarifies edge cases like routes without a price. For a read-only informational tool, this is complete enough for an agent to use 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 parameters are already documented. The description adds some nuance, such as how arguments affect pricing and that required parameters may be needed before a price can be quoted. It also clarifies with_quote's purpose (one round trip, spends nothing). These are useful but not essential given the schema's completeness.

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 purpose: returning the full contract of one or more operations, including schemas, read_only, side_effects, price, and known_pitfalls. It clearly distinguishes this from executing operations (use, batch_use) and from discovery (search, list_categories). The verb 'get' and the noun 'details' align with the title, and the first sentence is explicit.

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

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

The description implies the tool is used to assess an operation before spending (e.g., 'A quote authenticates like a call but stops before any spend'), and the schema says 'One operation_id from search', hinting at a flow. However, it never explicitly states when to choose this over siblings like use or search, nor does it give exclusions. The guidance is implied, not stated.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering safety. The description adds useful behavioral context: the compact size (~4 KB), the normalized flat fields, and the explicit list of returned fields. It doesn't contradict annotations and goes beyond them by explaining what data shape 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?

The description is dense but efficient. It front-loads the core purpose, then provides size comparison, field list, and usage guidance. Each clause earns its place; while it's a single long sentence, splitting it would improve readability but not information content.

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

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

For a single-parameter, read-only tool with an output schema, this description is remarkably complete. It specifies the exact return fields, clarifies the input constraint, provides provenance for the id, and gives routing to alternatives. Nothing an agent needs to call it correctly is missing.

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

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

The schema documents userId with a description and example, but the description adds crucial semantics: the id must be numeric, and it explains how to obtain it from other tools (data.user.id, search results, or post owners). This is meaningful beyond the schema's simple 'Instagram user id'.

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: 'Returns a compact public profile for a numeric Instagram user id.' It immediately distinguishes itself from get_instagram_profile by contrasting size (4 KB vs 380 KB) and field list. An agent can tell exactly what this tool does and how it differs from siblings 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?

The description gives explicit when-to-use and when-not-to-use guidance: 'Prefer this endpoint whenever the id is in hand' and 'Use get_instagram_profile only when a handle is all that is available.' It also explains how to obtain the id from three other tools, fully routing the agent to the correct alternative.

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

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

Beyond the readOnly/idempotent/non-destructive annotations, the description discloses the photo-error behavior, the two-minute duration limit, the measured 13-second latency, and an approximate 1 KB response size. These are the operational behaviors an agent needs to anticipate and they do not contradict 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?

Four sentences each carry distinct information: purpose and output, constraints and error, performance and payload size, and the caption alternative. The most important selection criteria are front-loaded before operational details.

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 parameter and an output schema present, the description covers everything an agent needs to decide and invoke correctly: input constraints, failure mode, fallback verification, and the sibling tool to use for captions. No critical gap remains.

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

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

The schema only says the url is an Instagram post or reel URL, but the description adds substantive meaning: it must be public, a video or reel, under two minutes, and should be verified with is_video when the type is unknown. This materially improves correct invocation.

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: it transcribes speech in a public Instagram video or reel and lists the returned transcript fields (id, shortcode, and transcribed text). This clearly differentiates it from caption-focused siblings like get_instagram_post.

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

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

It gives explicit conditions for use: the target must be a video under two minutes, a photo returns 400 bad_request, and when the type is unknown the agent should check is_video with get_instagram_post first. It also directs the agent to use get_instagram_post's edge_media_to_caption when the written caption is needed.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: the response size ('Measured at about 197 KB'), the credit cost difference (1 vs 10 credits), and the side effect of download_media=true ('mirrors the media to permanent storage'). This is useful behavioral disclosure that annotations don't 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 three sentences with no filler. It front-loads the core purpose and return data, then adds the cost warning, then routes to siblings. Every sentence earns its place and the structure is logical.

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

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

The description is complete for a read-only metadata tool. It covers the return path, key fields, response size, cost implications, and sibling routing. The output schema exists, so return values don't need further explanation. An agent has everything needed to select and 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 100%, so the schema already documents all four parameters. The description adds context for download_media (credit cost and permanent storage) and implies the URL is the primary identifier, but it doesn't add much beyond the schema for trim or region. Baseline 3 is appropriate since the schema does the heavy lifting.

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

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

The description states a specific verb ('Returns full metadata'), a specific resource ('one public post or reel identified by its URL'), and the exact data path ('data.xdt_shortcode_media'). It also lists the key fields returned, which distinguishes it from sibling tools like get_instagram_post_comments and get_instagram_media_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?

The description explicitly names sibling tools for related use cases: 'For the comment thread call get_instagram_post_comments with the same URL, and for the spoken words in a video call get_instagram_media_transcript.' It also gives clear guidance on when to use the download_media parameter ('leave it off unless the files are needed'). This is explicit routing and usage context.

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

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

Beyond the annotations (read-only, idempotent, non-destructive), the description adds valuable behavioral context: the response is normalized and small (~10 KB), only top-level comments are returned, child_comment_count is informational only, and replies cannot be expanded. This materially helps the agent set expectations about output size and limitations.

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, each earning its place: the first defines the return shape, the second adds a size expectation, and the third clarifies scope limits and routes to a sibling tool. The core behavior is front-loaded and there is no redundant restating of the schema or annotations.

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

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

For a simple GET-like tool with two parameters sufficient descriptions in the schemached, an output schema, and strong annotations, the description is complete. It covers paging, top-level-only behavior, the unexpandable replies limitation, and the sibling tool for related data, so nothing an agent needs to call it correctly is missing.

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

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

The input schema already describes both parameters fully (url and cursor), so the schema carries most of the burden. The description adds minor context by confirming the URL may point to a post or reel and mentioning the cursor is used for paging, but it does not substantially extend the schema's parameter explanations.

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

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

The description names a specific resource (comments on a public Instagram post or reel by URL) and states the action (returns them in a normalized shape). It also lists the exact fields returned)Skip and distinguishes itself from get_instagram_post by directing that tool to post metadata, so an agent can tell it apart without opening any 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?

It states when to use the tool (when you need comments on a public post/reel), and explicitly says to call get_instagram_post instead for the post itself. It also discloses that only top-level comments are available and that no endpoint expands replies, preventing fruitless attempts to fetch child comments through this API.

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, idempotent, and non-destructive. The description adds valuable operational context beyond those hints: the data comes from Instagram's own web API, the payload is about 380 KB, trim barely reduces it, and the response contains specific fields under data.user. No contradiction with annotations exists.

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

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

The description is dense but every sentence earns its place: it states the purpose, lists the response contents, gives the payload size, warns about trim's inefficiency, and points to the lighter alternative. It is front-loaded with the core result and organized in a logical flow.

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

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

For a read-only two-parameter tool with an output schema present, the description covers response shape, payload size, the trim caveat, and the sibling alternative thoroughly. It does not mention error cases or rate limits, but the annotations and output schema reduce the burden, making the description complete enough 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 both parameters. The description goes further by quantifying trim's actual effect (saves under one percent) and advising against relying on it, which is meaningfully useful semantics beyond the schema. The handle parameter is adequately covered by its example 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 states a specific verb and resource: 'Returns the full public profile for an Instagram handle'. It also distinguishes itself from get_instagram_basic_profile by noting the basic variant returns the same headline numbers in 4 KB when the numeric id is known, so an agent can easily tell the two apart.

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

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

It explicitly names get_instagram_basic_profile as the alternative when the numeric id is already known, including the size trade-off. It also warns that trim=true saves under one percent and should not be relied on, giving clear when-to/when-not-to guidance for configuration.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint falsecars. The description adds meaningful behavioral context beyond that: the source is Google's public index, coverage is incomplete, measured size/time are provided, and engagement counts are populated. This gives the agent concrete expectations about data scope and performance without contradicting annotations.

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

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

The description is compact yet information-dense, with the core purpose front-loaded, followed by coverage constraints, performance characteristics, and explicit routing to alternatives. Every sentence adds useful information, and nothing is wasted.

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 complexityaine, the presence of an output schema listing all return fields, annotations covering safety, and a thorough description of behavior, limitations, and alternatives, the definition is fully sufficient for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters with examples and descriptions. The description adds some interpretive value (e.g., date_posted narrows to a relative window) but does not materially expand parameter semantics beyond the schema. Baseline 3 is appropriate.

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

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

The description uses a specific verb ('Searches') and names the exact resource ('reels by keyword through Google'), while distinguishing it from the login-gated Instagram search. It also explicitly differentiates from sibling tools like get_instagram_search_hashtag and get_instagram_reels_trending, making the tool's unique role immediately clear.

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

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

The description explicitly states when to use this tool vs alternatives, naming get_instagram_search_hashtag for hashtag searches and get_instagram_reels_trending for trending reels with no query. It also clarifies coverage limitations and the behavior of date_posted, giving clear context for selecting and invoking the tool.

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

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

The description discloses that Instagram serves small overlapping batches, that the tool returns about 30 reels and 411 KB, and that play_count and ig_play_count came back null on every item. This goes well beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) and gives the agent critical expectations about pagination, size, and null fields. No contradiction with annotations.

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

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

The description is dense but every sentence earns its place: it states the source, the normalized shape, the batching/overlap behavior, the measured size and null fields, and the sibling alternative. It is front-loaded with the core purpose and then provides operational details. 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?

Given the tool has no parameters, an output schema exists, and annotations cover safety/idempotency, the description is complete. It explains the return shape, the need for de-duplication, the null-field caveat, and the alternative for topic search. An agent has everything needed to invoke and process the result correctly.

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

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

The tool has zero parameters, and the schema coverage is 100% (empty properties). The description explicitly states 'Takes no parameters and cannot be filtered,' which adds clarity beyond the empty schema by ruling out any hidden filtering capability. Since there are no parameters to document, the description fully covers 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 states a specific verb ('Returns'), a specific resource (the public instagram.com/reels page), and the normalized shape of the result. It also explicitly distinguishes itself from get_instagram_reels_search, which is a sibling tool, by noting the difference in play_count/ig_play_count population. This makes the tool's 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 explicitly says the tool takes no parameters and cannot be filtered, and it directs the agent to use get_instagram_reels_search for topic-based search. It also provides operational guidance: call repeatedly and de-duplicate on shortcode because batches overlap. This is clear when-to-use and 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 annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint false), the description discloses that it searches via Google, returns a normalized shape consistent with a sibling tool, notes that the cursor is a Google page number (not an Instagram cursor), and gives an approximate response size (~78 KB). This adds substantial behavioral context 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 a single paragraph that front-loads the core purpose, then adds critical usage details (media_type, cursor semantics, size) and a routing note. It is informative without being bloated, though it could be tightened by removing the size measurement which may be overly specific for an agent's selection decision.

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 4-parameter schema with enums, an output schema, and rich annotations, the description covers the search method, parameter nuances, sibling differentiation, and performance expectation. An agent has all necessary information to select and invoke this tool correctly without missing context.

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

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

Schema coverage is 100%, so every parameter is documented in the schema. The description adds meaningful nuance for the cursor parameter (explaining it is a page number) and clarifies media_type options ('narrow to reels'), which go slightly beyond the schema's basic descriptions. This justifies a score above the baseline of 3.

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

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

The description states a specific verb ('Finds') and resource ('public posts carrying a hashtag through Google'), and explicitly distinguishes it from the sibling get_instagram_reels_search by contrasting the search method. The purpose is unambiguous and differentiated.

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 clearly states when to use this tool versus the alternative: 'To search caption keywords rather than a hashtag, use get_instagram_reels_search.' It also explains the media_type option for narrowing results, providing explicit usage context without leaving anything to inference.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and idempotentHint=true, so the safety profile is covered. The description adds measurable operational context ('Measured at about 18 KB and 13 seconds') and discloses that the tool relies on Google search results, which an agent can factor into cost and reliability decisions. No contradiction with annotations.

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

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

The purpose, cost, downstream chaining, and sibling routing are each valuable and the description is front-loaded. However, the first sentence enumerates roughly fifteen output fields, which is largely redundant with the existing output schema and makes the description longer than needed.

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 the output schema documenting return fields and annotations covering safety and open-world semantics, the description fills the remaining gaps: cost, search mechanism, and downstream integration. An agent has everything needed to decide whether and how to call 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 coverage is 100%, and the description adds little beyond it: 'keyword or bio phrase' restates the schema's 'Bio or caption keyword/phrase to search for,' and the cursor behavior is already documented ('next Google results page number'). Baseline 3 is appropriate when the schema carries the 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 opens with a specific verb and resource scope: 'Searches Google for public Instagram profiles matching a keyword or bio phrase' and enumerates exactly what is returned. It differentiates from sibling search tools by naming get_instagram_search_hashtag and get_instagram_reels_search for post search, so an agent can distinguish profile-search from post-search 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-not guidance is given: 'To search posts rather than people, use get_instagram_search_hashtag or get_instagram_reels_search.' The description also gives a downstream chaining instruction ('The numeric id feeds get_instagram_basic_profile directly'), which helps an agent plan multi-step workflows.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive, so the description doesn't need to repeat those. It adds significant behavioral context by mentioning the raw response shape, the approximate payload size (177 KB), and the output fields (cursor and has_more for paging), which help set expectations about response characteristics beyond the annotations.

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

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

The description is relatively concise and front-loads the core function, then provides usage guidance, response details, and a sibling alternative in a logical flow. It is a bit longer than strictly necessary but every sentence adds value, so it earns a 4 rather than a 5.

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, the description doesn't need to detail return fields, but it still covers paging and the raw shape. The main gap is that it doesn't explain potential errors or edge cases (e.g., invalid audio_id), but the tool is relatively simple with only 2 parameters and good annotation coverage, so the description is nearly complete.

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

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

The input schema already comprehensively describes both parameters (audio_id and cursor) with examples and descriptions, so schema coverage is 100%. The description adds limited extra meaning by explaining how to derive audio_id from URLs or other API responses, but it doesn't elaborate on cursor usage beyond what the schema says. Thus, a baseline of 3 is appropriate.

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

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

The description clearly states the tool returns reels using a specific audio track, identifying the resource and the verb. It distinguishes itself from siblings by explicitly naming get_instagram_reels_search as the alternative for keyword-based search, making its unique 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?

It provides explicit guidance on when to use this tool vs alternatives, stating to use get_instagram_reels_search for keyword-based queries instead. It also gives concrete instructions on how to obtain the required audio_id, including two specific methods, which is critical for correct invocation.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds valuable behavioral context beyond those hints: result size (~206 KB), inlined markup/styling, and that it carries no structured data. This helps agents decide to store/render rather than parse. It does not mention rate limits or auth, but those are not required for this read-only embed tool.

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

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

Three sentences, each earning its place: first states the core action/output, second adds critical size/usage caveat, third provides routing to alternatives. The most important information (what it returns and how to use it) is front-loaded. No filler.

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

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

For a single-parameter tool with an output schema, the description is complete: it explains the return type (HTML string), the behavioral requirement (store/render, not read), the absence of structured data, and directs to alternatives. The output schema covers return details, so no further explanation is needed.

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

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

Schema coverage is 100% and the only parameter 'handle' is documented with an example, which meets the baseline. The description adds meaningful semantic distinction by noting that this tool takes a handle, unlike get_instagram_basic_profile which requires a numeric id, and by clarifying the tool's output is an HTML string derived from the handle. This helps agents select the correct identifier format.

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

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

The description states a specific verb and resource ('Returns Instagram's official profile embed widget for a handle as a single html string') and explicitly contrasts it with siblings that return structured data (get_instagram_basic_profile, get_instagram_profile). An agent can immediately distinguish this tool's purpose from the rest of the family 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?

It gives explicit when-to-use guidance ('ready to drop into a web page') and explicit when-not-to-use with named alternatives and conditions: 'for follower counts, biography or bio links use get_instagram_basic_profile when the numeric id is known, or get_instagram_profile when only the handle is.' This routes agents to the correct sibling based on data needs and available identifier.

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 cover the read-only, idempotent, and non-destructive profile, so the description adds value by disclosing concrete behavioral traits: the response echoes the id as highlight:<id>, the prefixed input causes a misleading 404, and the payload size is roughly 630 KB for 38 stories with size scaling. This is exactly the kind of context structured annotations cannot convey.

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

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

Four sentences, each earning its place: the return payload, the source of the id, the critical prefixed-form pitfall, and size scaling. No fluff, no redundant restatement of schema or annotations.

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

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

For a single-parameter, read-only tool with an output schema and safety annotations, the description provides everything an agent needs for correct invocation: how to obtain the id, how to format it, the failure mode to avoid, and an indication of response size. Nothing material appears missing.

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

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

The schema already documents id and points to the highlights endpoint, giving a high baseline. The description adds essential semantics beyond the schema: the id must be a bare numeric value, not the prefixed highlight:<id> form, even though the response echoes the prefixed version. This prevents a real, observed failure mode and clarifies that the parameter should be supplied despite the empty required array.

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: 'Returns the stories inside one highlight album' and enumerates the payload fields (reel_type, latest_reel_media, owning user, items). It also references get_instagram_user_highlights for obtaining the id, which helps distinguish this detail endpoint from the album-list sibling.

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

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

The description establishes a clear workflow by instructing the agent to 'Pass the bare numeric id from get_instagram_user_highlights.' It also warns against feeding the prefixed form and explains the resulting misleading 404. It doesn't explicitly enumerate when to choose this over unrelated siblings, but the dependency relationship is clear.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds useful behavioral context beyond that: it notes the response is small (~6 KB), cheap, and reveals whether an account keeps highlights at all. It also clarifies the dependency on the numeric id, which helps the agent understand usage patterns. This is meaningful additional context, though 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 compact and front-loaded: the purpose is stated first, then key return details, then the critical dependency, then a parameter optimization tip. Every sentence adds value, and there is no filler. It is well-structured and efficient.

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 optional parameters, read-only, idempotent) and the existence of an output schema, the description covers everything an agent needs to invoke it correctly: what it returns, how it relates to the detail tool, performance characteristics, and a usage tip. No critical information is missing.

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

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

Schema description coverage is 100% — both handle and user_id are fully described with examples and usage notes. The description repeats the tip about using user_id for faster responses, which is already in the schema. No additional semantic information about parameters is provided beyond the schema, so the 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: 'Lists the story highlight albums on a public profile.' It names the exact output fields and distinguishes itself from the sibling tool get_instagram_user_highlight_detail by explaining it is the source of the highlight id. This makes 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 explicitly states when to use this tool: it is 'the only source of a highlight id' and that the detail tool requires the id exactly as returned here. It also advises using user_id for faster response, which guides parameter choice. This is explicit when/why guidance with a clear alternative mentioned.

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 read-only annotations, it discloses pagination behavior (next_max_id, more_available, num_results), response size (~632 KB, trim only reduces to 523 KB), and mentions internal flags and large payload, which is critical for performance expectations. No contradiction with annotations.

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

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

The description is dense and front-loaded with the primary purpose, then covers pagination and size. It includes a helpful comparison to siblings, though the size details (632 KB vs 523 KB) may be more than needed, making it slightly verbose but each sentence adds value.

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

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

Given a clear output schema exists (though not shown in detail, it's told as 'has output schema: true'), the description covers pagination, size, and alternative routes, which is adequate for a complex tool. Missing details like error handling or rate limits are minor given the rest of the context.

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

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

The schema covers all parameters (100%), and the description adds context around next_max_id and trim (trim doesn't reduce size much), but doesn't explain handle beyond the schema's 'Instagram handle' or next_max_id beyond 'Cursor to get next page'. Baseline 3 is appropriate as schema does the heavy lifting.

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

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

The description states a specific verb ('Returns'), resource ('public account's timeline, reels and photos and carousels'), and result format ('raw Instagram media objects under items'), clearly distinguishing it from siblings like get_instagram_user_reels and get_instagram_post by scope and raw shape.

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

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

It explicitly tells when to use this versus alternatives for reels or single posts, and notes that alternatives return the same raw shape, guiding selection. It doesn't explicitly state when NOT to use this tool (e.g., for profiles), but the context and sibling names imply those use cases.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior, so the burden is lower. The description still adds valuable behavioral context: it returns only one page, exposes raw Instagram media objects under items[].media, provides paging_info.max_id for the next page, reports the approximate response size (594 KB), and reveals which media fields are included.

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 dense sentences, each earning its place: the first defines the primary output and pagination, the second enumerates fields and cross-tool linkage, the third gives performance guidance, and the fourth names an alternative. No repetition or filler.

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

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

Given the annotations, complete schema coverage, and an output schema, the description covers everything an agent needs to call and interpret the tool correctly: pagination, response shape, performance tradeoff, returned field references, and the sibling to use for broader timelines.

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 handle, user_id, trim, and max_id. The description mostly restates the schema's advice to prefer user_id for faster responses and doesn't add substantial new meaning per parameter. It does add useful cross-tool output semantics, but that relates to return values rather than parameter usage.

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: 'Returns one page of a public account's reels'. It clearly differentiates itself from the sibling get_instagram_user_posts by explicitly scoping this tool to reels only and noting that posts covers the whole timeline including photos and carousels.

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: pass user_id instead of handle for faster responses, use max_id from the previous response for the next page, and use get_instagram_user_posts instead when the whole timeline including photos and carousels is needed. It also chains to get_instagram_song_reels via the audio_asset_id explanation.

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

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

The description goes well beyond the annotations (readOnlyHint=true, openWorldHint=true). It discloses exactly what is kept per post (code, caption, counts, etc.), what is dropped (resolution variants, dash manifests, internal flags), the measured size reduction (632 KB to 20 KB), and confirms nothing is summarised or dropped. It also details pagination behavior with `next_max_id` and `more_available`. This is rich behavioral context that significantly aids an agent.

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

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

The description is well-structured and every sentence adds value. It opens with the core purpose, then details the content and size reduction, then clarifies exclusions and the alternative, and ends with pagination. It is front-loaded and free of fluff, making it 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?

Given the tool's complexity and the presence of an output schema, the description is complete. It covers the returned fields, exclusions, size reduction, pagination, and the alternative tool. An agent would have all necessary information to call it correctly and interpret the response without missing context.

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

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

The input schema has 0% coverage (no descriptions). The description explicitly explains the `next_max_id` parameter: 'Page with `next_max_id` from the previous response; `more_available` says whether another page exists.' However, the `handle` parameter is not explicitly described, though it is implicitly clear from 'public account' and the tool's name. Since coverage is low, the description compensates for one parameter but not the other, warranting a 4 rather than a 5.

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

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

The description clearly states the tool's function: 'One page of a public account's timeline, projected down to what fits a context window.' It explicitly contrasts itself with `get_instagram_user_posts`, making the purpose unambiguous and distinguishing it from siblings. The verb 'projected down' and the resource 'timeline' are specific and clear.

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

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

The description provides explicit guidance on when to use this tool versus the alternative: 'If you need any of those — downloading every resolution, building a player, forensic detail — call `get_instagram_user_posts` instead.' It also implies the appropriate use case (a compact digest for context windows) and explains pagination with `next_max_id`, leaving no ambiguity about selection criteria.

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

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

Annotations already mark this as read-only and non-destructive, and the description adds meaningful behavior beyond that: field flattening with a concrete path mapping (`edge_followed_by.count` → `followers`), measured size reduction from 380 KB to 15 KB, what is retained vs. dropped, and the one-display-URL-per-post rule. No contradiction with annotations.

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

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

Four compact sentences, front-loaded with the core purpose, followed by the field list, measured size, flattening detail, and alternative routing. Every sentence adds operational value with no wasted words.

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

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

The description plus the existing output schema cover almost everything an agent needs: scope, field semantics, size characteristics, relation to siblings, and return shape. The only meaningful gap is the undocumented `handle` input and any format restrictions. For a one-parameter public read tool, this is very close to complete.

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

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

The only parameter, `handle`, is never described in the definition. With 0% schema-description coverage, the description should at least state that `handle` is the Instagram username and whether a leading `@` is accepted, but it only mentions `username` as an output field. The input contract is left to 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?

Defines the resource (a public Instagram profile) and the transformation (a compact flat-card projection), then enumerates exactly which fields are kept. It explicitly contrasts itself with `get_instagram_profile`, so an agent can distinguish it from that upstream tool and from `instagram_posts_digest`.

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

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

Gives an explicit when-not signal: if the agent needs the untouched upstream response with every field and wrapper, call `get_instagram_profile` instead. It also explains that the returned numeric `id` feeds `get_instagram_basic_profile`, enabling intentional chaining for bulk enrichment. The size framing tells the agent when the compact digest is the right choice.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds meaningful behavioral context beyond annotations: the tool is free, requires no key, and can direct users to a category-specific endpoint that lists tools directly rather than through search.

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 moderately detailed but every sentence adds useful information: output scope, cost/auth, sibling differentiation, and endpoint usage. It is slightly longer than strictly necessary but remains well-structured and front-loaded with the core purpose.

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

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

For a zero-parameter, read-only tool with an output schema and safety annotations, the description is complete. It covers what the tool returns, the free/no-key access model, and provides the category endpoint for specialized use, leaving no essential gap for an agent to call it correctly.

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

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

The tool has zero parameters, so the baseline is 4. The description includes a <category> placeholder only in the endpoint examples, not as a tool parameter, which is appropriate supplementary guidance rather than a parameter-semantics gap.

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 what the tool does: it presents the AIsa catalogue at a glance, including categories, servers, tool counts, and a dedicated category endpoint. It also distinguishes itself from search by explaining that the endpoint lists tools directly instead of via search.

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

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

The description provides clear usage context: use list_categories for a catalogue overview, and use the provided endpoint when you only need one category. It explicitly contrasts with search ('instead of via search') and notes tool-router has no equivalent, although it does not exhaustively cover all sibling alternatives.

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

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

The description discloses meaningful behavior beyond annotations: search spans the entire AIsa catalogue, candidates may belong to modules other than the current one, multiple providers for the same metric are surfaced, and no API key is required. This gives the agent a clear picture of scope and output 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 front-loaded with the core purpose and is dense with useful information: scope, no-auth requirement, response shape, and relationship to the catalogue. Each sentence adds operational value, and the structure makes the tool's behavior predictable.

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

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

For a complex discovery tool with output schema, the description is unusually complete: it explains the response modalities, candidate fields, direct pass-through to `use`, full-catalogue search behavior, and cross-provider visibility. An agent has enough context to invoke and interpret the tool correctly.

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

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

Schema coverage is 100%, so the schema already documents all parameters. The description adds value by explaining that the category parameter is not a hard boundary—search spans the full catalogue—and that queries are plain-language task descriptions, which clarifies how to use the tool effectively.

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 finds AIsa data operations across many categories via a plain-language query. It distinguishes itself from siblings like get_details and use by emphasizing that search covers the full catalogue, not just the pinned category.

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 conveys when to use search: when you need to discover operations across the full catalogue, even those not in the current tools/list. It also implicitly contrasts with get_details by noting that returned candidates already include input_schema, so they can be passed directly to `use` without an extra call.

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

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

Annotations already provide readOnly=false, openWorldHint=true, and destructiveHint=true. The description adds valuable behavior beyond that: billing per call, the BatchCallResult response shape, and the error structure with retryable status. It does not spell out side effects, but the destructive flag is already carried by annotations, so the additional context 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?

Three short sentences, each earning its place: purpose, cost, response shape, and routing guidance. Key behavioral facts are front-loaded, and nothing is redundant with the schema or annotations.

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

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

Given that an output schema exists and all parameters have descriptions, the tool description is complete enough for correct invocation. It covers cost, return/error contracts, and how routing to this tool differs from calling pinned tools directly, leaving no practical gap.

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

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

Schema description coverage is 100%, and each parameter is already clearly documented: operation_id as returned by search, search_id provenance, arguments matching input_schema, and max_price_usd as a spend guard. The description does not need to add parameter detail, so baseline 3 is appropriate.

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

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

The description opens with 'Execute one AIsa operation,' a specific verb+resource statement. The word 'one' distinguishes it from the sibling batch_use, and the closing note distinguishes it from calling pinned tools directly. An agent can tell what this tool is for immediately.

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

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

It explicitly states when to use the tool: 'this is the way to call anything found through search.' It also gives the alternative: 'Pinned tools in tools/list can also be called directly.' This is clear when-versus-alternative guidance with no ambiguity.

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