AIsa Instagram

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

Adds substantial context beyond the readOnlyHint/openWorldHint/destructiveHint annotations: the call is free, it requires the Authorization header, and it discloses result semantics ('ok is true only when the balance was read; otherwise each entry of errors says what to do in next_step'). That tells an agent how to interpret partial failure, which 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?

Three sentences, front-loaded with what the agent gets, followed by cost/auth, then call triggers, then result interpretation. No sentence is redundant and none could be dropped without losing 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?

For a zero-parameter read tool with an output schema already present, the description covers the remaining gaps: cost, auth requirement, invocation triggers, and the ok/errors/next_step contract. Nothing an agent needs to call or interpret 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 tool takes zero parameters, so the description has nothing parameter-level to compensate for, and the schema is fully covered. A 4 rather than 5 reflects that it adds no input-syntax detail, though none is possible here.

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 concrete resource set (identity/key, account balance, Go-to-Market wallet, usage over 1/7/30 days) rather than restating the name. It is clearly distinguishable from every sibling, which are all Reddit, batch, or search tools. An agent knows exactly what it will learn by calling it.

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 triggering conditions are given: 'Call it to verify a new connection or to explain a 402.' That is a strong when-to-use statement. It stops short of 5 because it names no alternative tool or a when-not condition, though the sibling list offers no obvious competing diagnostic.

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 the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description is not required to restate it. It adds genuine operational context: the batch_use prohibition, exact-name/prefix requirements, and session reuse semantics. It does not cover failure handling when names are invalid, keeping it below 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?

Front-loaded with the core action and size limit, and every sentence carries workflow value. The session_id sentence duplicates the schema's own parameter description, which is minor redundancy rather than bloat.

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 batch retrieval tool with an output schema, the description supplies the orchestration context an agent needs (source of names, next steps, session handling) without needing to explain return values. Nothing essential to 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 real meaning beyond the schema by constraining names to those returned by search and warning against a client prefix such as mcp__aisa__, which is not encoded 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?

States a specific verb and resource ('Retrieve schemas for 1 to 20 exact tool names') and pins the source of those names to search. This clearly separates it from siblings like search (finds tools), batch_quote, and batch_use.

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

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

Explicitly sequences the workflow: build arguments from successful schemas, then call batch_quote, and 'Do not call batch_use yet.' This is an explicit when-to-use and when-not-to-use instruction naming the alternative siblings.

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

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

Goes well past the readOnly/idempotent annotations by explaining that quotes are price observations rather than authorization grants, and precisely delimiting what auto_execute_eligible does and does not waive (user prohibition, narrower scope, tighter budget). It also guarantees no execution fallback, which is the key behavioral risk for this 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?

Purpose is front-loaded and most sentences carry distinct rules (no fallback, eligibility limits, naming, session reuse). It is on the long side and the argument-shape constraint is stated twice in spirit, but little is truly 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?

An output schema exists, so return-value documentation isn't required, yet the description still flags the two response fields that matter for a downstream decision. Combined with session and naming guidance, an agent has everything needed 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?

At 67% schema coverage the schema already documents each parameter, so the description earns credit only for added meaning: exact-name rules for 'tool', session_id reuse semantics, and the 1-to-20 argument-shape parallel with batch_use. It doesn't clarify search_id beyond what the schema states.

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

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

States a specific verb and resource ('Obtain AIsaServices cost quotes for 1 to 20 published tools') plus the crucial scope qualifier 'without executing them.' It is immediately distinguishable from the sibling batch_use, which executes rather than quotes.

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

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

Explicitly names the parallel sibling ('Same input as batch_use') and draws the boundary ('Never falls back to execution'). It also gives operational conditions: use names exactly as search returns them, strip any mcp__aisa__ prefix, and reuse session_id from Search for the task.

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 mutability, destructiveness, and open-world behavior. The description adds critical business logic: billable calls, quote dependency, the meaning of auto_execute_eligible (waives only cost confirmation, not user prohibitions), and no silent retry. It doesn't detail rate limits or return format, but with an output schema present, that's acceptable.

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-loads the cost warning, but it packs many separate instructions into one block, making it less scannable. Some sentences like 'A missing or failed quote is not free' add value, but the overall flow could be better structured.

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

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

Given the destructive, open-world annotations and the presence of an output schema, the description covers the essential preconditions and behavioral constraints. It could mention error handling or partial failure behavior, but the core guidance is sufficient for correct invocation.

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

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

Schema coverage is 67%, and the description adds important semantics: tool names must be exact without client prefix, session_id reuse guidance, and 1-20 call limit. It doesn't explain search_id, but the schema description for search_id is already clear enough.

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 and resource: 'Execute 1 to 20 independent published-tool calls', and the title matches. It distinguishes itself from batch_quote by requiring a quote first, but doesn't explicitly contrast with the singular 'use' sibling, though that's implied by 'batch'.

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 conditions: only after a successful batch_quote with auto_execute_eligible=true or explicit user authorization. It also states re-quote conditions and prohibits silent retries, leaving little ambiguity.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds genuinely new behavioral context — the ~4 KB footprint versus 380 KB, the flat/already-normalised shape, and the injected billing estimate. It doesn't discuss rate limiting or the credit-free cached path, which the schema covers but the description does not reinforce.

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?

Front-loaded with purpose and size comparison, then the selection rule, then id sourcing — a sensible order with little filler. It runs long and the HTML-comment pricing block is noise, but that block appears to be machine-injected boilerplate rather than authorial padding.

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

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

An output schema exists, so return values need no prose explanation, and the schema itself carries the cache_max_age semantics. Given that, the description covers everything an agent needs: what it returns, how big it is, when to prefer it, and where the id comes from.

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 and the schema already documents cache_max_age and its enums. The description still adds value beyond the schema by specifying the id is 'numeric' and by telling the agent where to obtain it (data.user.id, id from search, post owner).

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

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

States a specific verb+resource ('Returns a compact public profile for a numeric Instagram user id'), quantifies the payload (~4 KB vs 380 KB), and explicitly separates itself from the sibling get_instagram_profile. It also names a second sibling (get_instagram_search_profiles) as an id source, so an agent can route without opening a 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?

Gives an explicit decision rule: 'Prefer this endpoint whenever the id is in hand' and 'Use get_instagram_profile only when a handle is all that is available.' It even enumerates the three places the required id can be sourced from, so the prerequisites are fully closed.

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 safety (readOnly, idempotent, non-destructive), and the description adds behavioral facts the annotations cannot convey: the 400 error on photo posts, the ~13 second latency as the slowest call in the API, and the ~1 KB payload size. These are exactly the beyond-annotation details that change an agent's calling strategy.

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?

Front-loads purpose, then constraints, then alternative routing, in four tight sentences. The appended pricing comment block is boilerplate rather than task-relevant guidance, which slightly dilutes an otherwise waste-free entry.

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?

An output schema exists, yet the description still names the return shape (id, shortcode, transcribed text), and it covers the operational envelope: duration cap, error behavior on photo posts, latency, and payload size. Nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is 100%, and the two non-trivial parameters (cache_max_age, allow_long_transcription) carry extensive inline documentation including enum values, billing semantics and the 'true'-only opt-in rule. The description adds no parameter-level detail beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb (transcribes the speech) and resource (public Instagram video or reel), and explicitly distinguishes itself from get_instagram_post by contrasting spoken words with the author's caption. An agent can separate this from the transcript-adjacent siblings without opening a 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?

Gives a hard precondition (video under two minutes), the failure mode when violated (photo post returns 400 bad_request), the diagnostic step when URL type is unknown (check is_video with get_instagram_post first), and names an alternative tool for a different need (caption via edge_media_to_caption). When-to-use and when-to-use-something-else are both 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 cover the read-only/idempotent/non-destructive profile, but the description goes further by disclosing response payload location (data.xdt_shortcode_media), approximate response size (~197 KB), and the side effect plus credit cost of download_media (mirrors media to permanent storage, 10 credits vs 1). It does not discuss rate limits or auth requirements, but the added operational cost/size context is genuinely useful 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?

Purpose and routing are front-loaded, and every sentence carries operational information. However, the long enumeration of output fields in the first sentence is largely redundant given the tool has an output schema, making it denser than necessary.

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

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

With an output schema present, the description need not explain return structure, and it still supplies size, cost, caching-adjacent trade-offs, and sibling routing. An agent has everything needed to decide whether to call this tool and how to configure it.

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

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

Schema description coverage is 100%, so all six parameters (including cache_max_age semantics and download_media cost) are already documented in the schema. The description reinforces the download_media cost/default trade-off but adds no syntax or behavior that the schema does not already carry, so the baseline 3 applies.

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

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

The opening sentence gives a specific verb (returns), resource (full metadata for one public post or reel), and identity mechanism (by URL). It is immediately distinguishable from siblings like get_instagram_post_comments and get_instagram_media_transcript, which the description itself names.

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 routing rules are provided: call get_instagram_post_comments for the comment thread and get_instagram_media_transcript for spoken words in a video. It also gives a clear when-not for a costly parameter ('leave it off unless the files are needed'), so the agent knows both alternatives and cost trade-offs.

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

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

Annotations already declare readOnly/idempotent/non-destructive/openWorld, yet the description adds substantial extra context: the normalised response shape, approximate ~10 KB payload size, cursor paging, and the key constraint that only top-level comments are returned while child_comment_count merely reports reply counts. This is behavioural detail far 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?

Front-loaded with purpose and shape, and each sentence carries information (shape, size, pagination, reply limitation). The pricing boilerplate and the 'one of the few small responses' remark are the only mild padding.

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

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

With annotations plus an output schema present, the core safety and return-shape burdens are covered, and the description still enriches them. It is slightly incomplete/inconsistent regarding how include_replies reconciles with the claim that replies cannot be expanded.

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 url, cursor and include_replies, and the description adds little parameter-specific meaning. There is a mild tension: the description says replies 'are not included, and there is no endpoint that expands them,' while the schema exposes include_replies to fetch replies, which could confuse an agent about whether replies are retrievable.

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

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

States a specific verb and resource ('Returns the comments on a public post or reel by URL'), and names the sibling it is not for post-level data ('call get_instagram_post'). An agent can distinguish this from the sibling without opening a 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?

Explicitly routes the agent to get_instagram_post when the post's caption/view counts/video URL is wanted, giving a clear alternative selection rule. However it gives no guidance on when to prefer this over get_instagram_user_posts or the digest tools for broader comment needs.

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

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

Annotations already cover the safety profile (readOnly, idempotent, openWorld, non-destructive), yet the description adds substantive behavior: an approximate payload size (~380 KB), the counterintuitive finding that trim saves under 1% and shouldn't be relied on, and the exact response paths where counts and posts live. This is meaningful context an agent cannot get from 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?

The core content is front-loaded and every sentence carries information: response shape, size, trim caveat, and the cheaper alternative. The trailing pricing boilerplate adds length but is a platform-injected block rather than author prose, so it only marginally detracts.

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?

An output schema exists, so return-value documentation is not strictly required, yet the description still maps the key fields to their JSON paths. Combined with the size estimate, trim caveat, and alternative-tool routing, an agent has everything needed to call this correctly and predict the response.

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 goes beyond the schema by disclosing that the trim parameter is effectively useless for shrinking the payload — information that directly contradicts the optimistic schema text 'Set to true to get a trimmed response' — and by naming where the handle's data surfaces. cache_max_age is left entirely to the schema, which documents it 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?

States a specific verb and resource ('Returns the full public profile for an Instagram handle') and identifies the upstream source. It explicitly distinguishes itself from the sibling get_instagram_basic_profile, so an agent can route correctly without opening either schema.

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

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

Provides an explicit alternative with its selecting condition: 'When the numeric id is already known, get_instagram_basic_profile returns the same headline numbers in about 4 KB.' It also warns that trim=true is not a viable way to reduce payload. It does not address other profile-adjacent siblings (instagram_profile_digest, get_instagram_user_posts), which keeps it 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?

Goes well beyond the annotations (readOnly/openWorld/idempotent) by disclosing coverage limits ('what Google has indexed publicly, not everything on Instagram'), measured payload size (~87 KB) and latency (~8s), and that all four engagement counts are populated. It does not cover auth requirements or pagination depth behavior, so it stops short of 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?

Dense but front-loaded: purpose and mechanism first, then caveats, then routing to siblings. The exhaustive enumeration of return fields partly duplicates the existing output schema and is the one sentence that does not fully earn 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 a rich output schema and full annotations, the description fills the remaining gaps an agent needs: data-coverage caveat, latency/size expectations, and alternative tool routing. Only minor parameter-level detail (page/limit behavior) is left unexplained.

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

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

Schema description coverage is 75%, so the baseline is already anchored at 3. The description adds meaning by clarifying that date_posted 'narrows to a relative window' and by framing query as the keyword driver; page/limit still carry no description beyond their schema text.

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

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

States a specific verb+resource (searches reels by keyword) and immediately distinguishes itself from siblings by naming the mechanism ('through Google rather than Instagram's login-gated search'). An agent can identify this tool's niche without opening 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?

Explicitly routes to alternatives with their selecting conditions: get_instagram_search_hashtag for a specific hashtag, get_instagram_reels_trending for what is popular with no query. This is exactly the when/when-not/alternative guidance the dimension asks for.

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 safety profile (readOnly, idempotent, openWorld), yet the description adds substantial behavior: batch pagination with overlapping successive batches requiring dedup on shortcode, measured payload size (~411 KB / 30 reels), and the caveat that play_count/ig_play_count come back null here unlike in get_instagram_reels_search. That is real, non-obvious operational context.

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

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

Front-loaded with what it returns, then pagination/dedup behavior, then routing to the sibling. Dense but every clause carries information; the embedded field enumeration and the injected pricing comment add bulk without adding invocation guidance.

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

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

For a no-parameter, output-schema-backed tool, everything an agent needs is present: scope, pagination/dedup requirement, known null fields, size expectations, and the correct alternative for filtered searches. Nothing material 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?

Zero parameters, so the baseline is 4. The description reinforces this by stating it takes no parameters and cannot be filtered, which prevents an agent from inventing filter arguments, but there is no further parameter detail to add.

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

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

States a specific verb and resource ('Returns the reels Instagram publishes on its public instagram.com/reels page') plus the normalized output shape. It explicitly distinguishes itself from get_instagram_reels_search and implicitly from get_instagram_user_reels by scope (public trending page vs topic search vs a user's reels).

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

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

Gives explicit operational guidance: 'call repeatedly and de-duplicate on shortcode' because batches overlap, plus 'Takes no parameters and cannot be filtered; to search by topic use get_instagram_reels_search.' Both the when and the when-not (with a named alternative) are 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 cover read-only, idempotent, open-world and non-destructive, yet the description adds non-obvious behavior: results are Google-indexed rather than direct Instagram data, the cursor is a Google results page number rather than an Instagram cursor, and payload size is about 78 KB for ten posts. The cursor quirk in particular is exactly the kind of detail that prevents misuse.

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?

Purpose, return shape, enum behavior, the cursor caveat and the alternative are all front-loaded with no filler. It is densely packed into a single block rather than cleanly segmented, and the injected pricing block adds bulk, but every sentence of the authored text 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?

With an output schema, full annotation coverage and 100% schema description coverage, the description already goes further by naming the normalized return fields and the size/cursor behavior. Nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents hashtag, cursor, media_type and date_posted; the description mostly restates them (optional '#', all vs reels). It adds little parameter meaning beyond what the schema provides, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Finds public posts carrying a hashtag through Google') plus the exact scope of coverage. It names the sibling it is not (get_instagram_reels_search) and explains the shared normalized shape, so an agent can distinguish it without opening 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?

Gives clear routing guidance: media_type=reels vs all, and an explicit alternative ('To search caption keywords rather than a hashtag, use get_instagram_reels_search'). It stops short of stating exclusions or prerequisites (e.g., hashtag is not required), so it is strong context rather than a full when/when-not matrix.

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 the safety profile (readOnly, idempotent, openWorld, non-destructive), yet the description still adds meaningful traits: the source is Google (open-world scraping, not the Instagram API), the measured payload/latency (~18 KB, ~13 s), and the matched_from field that explains why a profile appeared. Rate limits and failure behavior are not covered, which keeps it short of 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?

Purpose and routing are front-loaded and the performance metrics are compact, but the long enumeration of return fields is largely redundant with the existing output schema and consumes most of the description's length. It could be trimmed to keep only the fields that inform selection.

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?

An output schema exists, so return values need no explanation, and the description still supplies the source of the data, cost/latency expectation, sibling routing, and the chaining target for the returned id. Nothing an agent needs to invoke this correctly is missing.

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

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

Schema description coverage is 100%, so both parameters are already documented, and the description adds no syntax or format detail beyond restating 'keyword or bio phrase'. The cursor/pagination parameter is not addressed at all. Baseline 3 is appropriate when 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?

States a specific verb+resource ('Searches Google for public Instagram profiles matching a keyword or bio phrase') and enumerates the returned identity fields, so the agent knows exactly what it gets back. It also distinguishes itself from siblings by naming the post-search alternatives, so an agent can pick correctly without opening a 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?

Gives an explicit exclusion ('To search posts rather than people, use get_instagram_search_hashtag or get_instagram_reels_search') and a downstream chaining rule ('The numeric id feeds get_instagram_basic_profile directly'). Both when-to-use and when-not-to-use are stated rather than inferred.

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 safety (readOnly, idempotent, non-destructive, openWorld), and the description adds real behavior beyond them: raw Instagram media objects under a 'reels' key, cursor/has_more paging, and a measured payload size (~177 KB for five reels). It also discloses that the response shape matches get_instagram_user_reels rather than the normalised search-endpoint shape, which is non-obvious and useful.

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

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

Front-loaded with the core purpose, then progressively more specific detail (shape, acquisition paths, size, alternative tool). It is dense but every content sentence carries information; the appended pricing block is boilerplate rather than authored prose.

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?

An output schema exists so return values need not be doc-dumped, yet the description still orients the agent on response shape and paging. The one residual gap is that audio_id is technically optional in the schema but effectively the tool's subject, and the description never says what happens if it is omitted.

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 goes beyond the schema by explaining how audio_id is obtained and where it lives on other responses. Cursor semantics are only echoed from the schema rather than extended.

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

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

States a specific verb+resource+filter: 'Returns the reels that use one audio track.' It explicitly names the sibling it is not (get_instagram_reels_search for keyword-based discovery), so an agent can distinguish it without opening either 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?

Gives concrete selection guidance: use this when you have an audio_id, use get_instagram_reels_search when you want keyword search. It also supplies two confirmed acquisition paths for audio_id (the /reels/audio/<id>/ URL number and clips_metadata.original_sound_info.audio_asset_id), which removes the main prerequisite uncertainty.

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 the safety profile (readOnly, idempotent, openWorld, non-destructive), yet the description adds genuinely new traits: the ~206 KB payload size, the fact that it is nearly all inlined markup and styling, and that it contains zero structured profile data. These are the details that change how an agent handles the result.

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 author-written text is tight and front-loaded: purpose first, then handling advice, then the alternative tools. The injected pricing banner adds length the author does not control, which keeps this just short of 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?

An output schema exists, so return values need not be explained, and the description goes further by characterizing the payload's size and composition. For a single-parameter read tool with full annotation coverage, nothing an agent needs 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% for the single 'handle' parameter, so the schema already carries the semantics. The description mentions the handle only in passing and adds no format or validation detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Returns Instagram's official profile embed widget for a handle as a single html string') and immediately distinguishes itself from data-returning siblings by noting it carries no structured profile data. An agent can identify the tool's output shape without opening 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?

Explicitly routes the agent to alternatives: get_instagram_basic_profile when the numeric id is known, get_instagram_profile when only the handle is. It also gives a usage posture ('treat the result as something to store or render rather than something to read'), which is exactly the when/when-not guidance 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 cover readOnly/idempotent/non-destructive, but the description adds real behavioral context: the response echoes the id in prefixed form, the 404 misattribution gotcha, and measured payload size (~630 KB for 38 stories) that scales with the album. This is exactly the kind of beyond-annotations disclosure that earns a top score.

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?

Front-loaded with purpose, then the parameter gotcha, then the failure mode, then the size note. Every sentence carries actionable information; nothing is padding despite the density.

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, return values need no elaboration, yet the description still names key fields. Combined with the ID-format warning and size scaling, an agent has everything needed 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?

Schema coverage is 100%, yet the description adds the critical semantics the schema omits: the id must be the bare numeric form from get_instagram_user_highlights, and the prefixed highlight:<id> form yields a 404 whose message misleadingly blames deletion or a private account. This is meaningful parameter meaning 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?

States a specific verb and resource ('Returns the stories inside one highlight album') and enumerates the returned fields, which cleanly separates it from the sibling list-level get_instagram_user_highlights. An agent can tell exactly what this tool does versus its siblings.

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

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

It explicitly routes the agent to get_instagram_user_highlights as the source of valid IDs and implies this tool is the per-album follow-up. It does not state explicit exclusions or when not to use it, but the upstream/downstream relationship is unambiguous.

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, openWorld and non-destructive, so the safety profile is covered. The description adds genuinely non-structured context: approximate payload size (~6 KB), the fields returned, the chaining prerequisite for the detail tool, and a latency tradeoff between handle and user_id. It stops short of rate-limit or failure-mode 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?

Front-loads what it returns, then the routing rationale, then the parameter tip — a sensible order with no filler. The speed/parameter sentence duplicates the schema text rather than earning new space, and the embedded pricing block sits awkwardly in the middle of the tool description.

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

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

With an output schema present, the definition need not enumerate returns, yet it does so concisely alongside cost and chaining guidance. Nothing critical is missing for a two-optional-parameter read tool; only explicit pagination or empty-result behavior is absent.

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 both properties already document themselves, including the 'use user_id for faster response times' hint, which the description largely repeats. The description confirms both params are optional by omission but adds no new syntax, format, or mutual-exclusion guidance 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?

States a specific verb and resource ('Lists the story highlight albums on a public profile') and immediately differentiates from sibling get_instagram_user_highlight_detail by declaring itself 'the only source of a highlight id.' An agent can pick between the two without opening either 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?

Gives explicit usage context ('a cheap way to see whether an account keeps highlights at all') and the routing condition to the sibling tool, noting the detail tool 'requires the bare numeric id exactly as returned here.' It also tells the agent which parameter to prefer and why, which is more than most definitions offer.

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 the safety profile (readOnly, idempotent, non-destructive, openWorld), yet the description adds substantial context beyond them: measured payload size (632 KB), the limited effect of trim (only down to 523 KB), pagination loop mechanics, and the fields present in each item. This is exactly the value-add the dimension rewards.

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?

Front-loaded with purpose, then pagination, payload realities, and alternatives in a logical order; nearly every sentence earns its place. Slightly dense, and the appended pricing boilerplate is external noise not attributable to the tool author.

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

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

Despite an output schema existing, the description still conveys return shape and size, pagination termination, and sibling routing. For a large-payload, paginated list tool, an agent has everything needed 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?

Schema coverage is 100%, so baseline is 3, but the description adds real meaning: it clarifies that next_max_id is a cursor for paging and that trim=true barely reduces the already-large payload, tempering a user's expectation. It does not document the handle parameter's format, keeping it from 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?

Opens with a specific verb and resource scope ('Returns one page of a public account's timeline, reels and photos and carousels alike') and explicitly distinguishes itself from get_instagram_user_reels and get_instagram_post. An agent can identify the tool's role without opening 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?

States the selection rule explicitly: use get_instagram_user_reels for reels alone and get_instagram_post for one known post. It also pre-empts a common wrong assumption by noting neither alternative yields a smaller payload.

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 the safety profile (readOnly, idempotent, openWorld, non-destructive), yet the description adds behavior beyond them: one-page-at-a-time pagination via max_id, an expected payload size of 594 KB per page for context budgeting, and the exact fields returned per reel. That is real operational context not derivable from 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?

Return shape and pagination are front-loaded, and the alternative-tool routing sits at the end where it belongs. The sentences are dense but each carries distinct information; the appended pricing boilerplate is noise but outside the author's prose.

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, the description need not explain return values, yet it still sketches the envelope and cross-references a sibling tool's input contract. Combined with annotations and 100% schema coverage, an agent has everything needed to call this correctly on the first try.

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, max_id, and trim, and the description largely restates the user_id-vs-handle preference and max_id chaining. The trim parameter is not addressed at all in the description. Baseline 3 is appropriate given 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 and resource ('Returns one page of a public account's reels'), names the response envelope (items[].media) and the pagination token (paging_info.max_id), and explicitly contrasts itself with get_instagram_user_posts for the full timeline. An agent can distinguish it from get_instagram_song_reels, get_instagram_user_posts, and reels_search 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 names two concrete alternatives with selecting conditions: get_instagram_song_reels is invoked by piping clips_metadata.original_sound_info.audio_asset_id, and get_instagram_user_posts covers the whole timeline including photos and carousels. It also advises user_id over handle for speed, giving the agent actionable routing rather than 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?

Beyond the annotations (readOnly, idempotent=false, openWorld), it discloses concrete behavior: 632 KB → ~20 KB, nothing summarised, no post dropped, upstream order preserved, which 9 variants and ~100 flags are dropped, and a pagination limitation the API cannot work around. This is unusually rich.

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?

Front-loaded with the core purpose and routing, then the survival/removal detail. Slightly long, but nearly every sentence carries decision-relevant information; the byte-savings figures and field list earn their space.

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-param read tool with an output schema, the description covers projection semantics, dropped fields, ordering, and the pagination constraint. An agent has everything 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?

One required parameter with 0% schema description coverage. The description implies the handle identifies a public account whose timeline is fetched, but never explicitly defines the parameter or its format. With a single trivial param and an output schema present, this is adequate but not compensating for the coverage 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 states a specific verb+resource ('one page of a public account's timeline, projected down') and explicitly contrasts with `get_instagram_user_posts`, so an agent can distinguish it from the sibling without opening either 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 gives explicit when-to-use (need compact captions/counts in a context window) and when-not (downloading every resolution, building a player, forensic detail), and routes to the exact alternative tool by 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 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 establish that this is a safe, read-only, closed-world operation. The description adds useful context beyond annotations by saying it returns categories, servers, tool counts, and the dedicated endpoint, and that it is free. It omits auth/rate-limit details, but those are less critical given the read-only annotations.

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

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

The description is front-loaded with what the tool returns and is generally efficient. The parenthetical about tool-router and the endpoint URL add some density, but each part contributes usage or content context.

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

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

With zero parameters, read-only annotations, and an output schema available, the description supplies enough context for correct invocation. It explains the catalogue contents and gives the category-specific endpoint alternative, leaving no critical gap for an agent.

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 parameter semantics are not a meaningful differentiator. The schema has no properties to explain, and the description does not need to document any inputs.

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

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

The description clearly states that this tool gives a catalogue overview: categories, servers per category, tool counts, and a dedicated endpoint. The resource is specific and recognizable, though sibling differentiation is only partial because it references 'tool-router' rather than the listed siblings like search/use.

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 a clear alternative: use the category-specific endpoint if you only need one category, rather than going via search. It also notes the tool is free and AIsa-only, but it does not explicitly state when to call list_categories instead of search or use.

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 workflow behavior the annotations cannot: the has_full_schema flag gates a required batch_get_schema call, and the next step after search is batch_quote, not batch_use. It stops short of disclosing retrieval limits or catalog breadth that would push it to 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?

It is a dense run of imperatives rather than flowing prose, but each sentence carries a distinct rule (scope, language, workflow branch, negative cases, result interpretation) and the most important scoping guidance is front-loaded. Slightly more compression would help.

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, the description need not explain return values, and it correctly avoids doing so while still referencing the output fields that drive the workflow (has_full_schema, next_steps_guidance). A mutation-free, well-annotated search tool is adequately covered, though catalog scope ('AIsa-only', no external providers) could be stated more explicitly.

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 structured baseline is 3. The description adds genuine meaning beyond the schema by telling the agent to write the query in English and to place tickers, URLs, providers, or identifiers in known_fields, which is non-obvious routing guidance for a nested free-form object.

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: 'Discover AIsa tools and Plans for external data or actions.' It also separates this discovery step from the sibling execution tools by naming batch_get_schema, batch_quote, and batch_use and stating when each follows, so an agent can place it in the workflow 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 ('tasks needing external data or actions'), when-not ('tasks that only need supplied content or general knowledge'; no standalone rewriting, translation, summarization, formatting, or calculations), and named alternatives (batch_get_schema when has_full_schema=false, batch_quote rather than batch_use). It also specifies query language and atomic-query style, leaving little 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=false, destructiveHint=true, and openWorldHint=true, so the agent knows this is a state-changing, open-world operation. The description adds only the deprecation status and says nothing about what gets mutated, spend behavior (despite a max_price_usd param), or authorization needs.

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?

A single clause with zero waste; the deprecation notice and the replacement are front-loaded. It is terse by design for a deprecated endpoint, though it is under-specified rather than optimally 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?

Has an output schema and annotations, which reduces the burden, but a 4-parameter operation tool with a deprecation notice gives no information about what it executes or whether it remains functional. For an agent deciding between this and batch_use, the description is thin.

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 all four parameters (operation_id, arguments, search_id, max_price_usd) are already documented in the schema. The description adds no parameter meaning on top, so the baseline 3 applies.

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

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

The description never states what the tool does — no verb or resource. It only labels the tool as deprecated and points to a replacement, leaving the actual capability ('Run an AIsa operation' from the title) unexplained. An agent must infer the purpose from the title and schema alone.

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 routes the agent to the alternative ('use batch_use instead'), which is exactly the guidance needed for a deprecated tool. It doesn't explain when, if ever, this tool should still be called (e.g., during a migration window), so it stops 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.