captapi

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

With no annotations, the description discloses cost behavior (low cost, cached free, failures not charged) and implies read-only nature, beyond the empty schema.

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

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

Two front-loaded sentences: purpose then cost nuance. No redundant words; every 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?

For a simple balance tool with no output schema, the description covers purpose and cost but lacks details about the response format or plan limits specifics.

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?

No parameters exist (schema coverage 100%), so the description correctly adds no param info; baseline 4 for zero-parameter tool.

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

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

The description clearly states 'Get current Captapi credit balance and plan limits' with a specific verb and resource, distinguishing it from sibling account tools like account_daily_usage or account_request_history.

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 context about cost (low/cached free) implying safe frequent use, but does not explicitly state when not to use it or compare to 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?

No annotations are provided, so the description carries the full burden. It discloses cost behavior and caching, but lacks details on authentication requirements, response format, or whether it's read-only. The description is adequate but minimal.

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

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

The description is two sentences, front-loaded with the purpose, and contains zero waste. Every word 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?

For a simple tool with one parameter and no output schema, the description covers purpose and cost but omits output structure or example. It is adequate but not comprehensive.

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% (one parameter 'days' with description). The description does not add any meaning beyond what the schema already provides (default 30, max 365). Baseline 3 is appropriate.

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

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

The description clearly states the tool returns a 'Daily request and credit usage summary', which is a specific verb+resource combination. It distinguishes itself from siblings like 'account_balance', 'account_most_used_routes', and 'account_request_history' by focusing on daily usage metrics.

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 cost context ('Costs ~0 credits; cached results are free, failures are never charged') but does not explicitly state when to use this tool versus alternatives. The purpose is clear from the name, but no direct guidance on when not to use or which sibling to choose.

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

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

With no annotations, the description carries the burden of disclosing behavioral traits. It adds useful context about cost (≈0 credits), caching (cached results are free), and failure policy (failures never charged). It does not, however, describe the exact response format or ordering, which would be valuable given no output schema, but the provided information exceeds basic 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?

The description is a single sentence that is front-loaded and directly states the tool's purpose and cost characteristics. There is no filler or redundant content; every clause ('Most used API routes', 'by request count and credits', 'Costs ~0 credits', 'cached results are free', 'failures are never charged') carries meaningful 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 simple tool with two optional parameters and no output schema, the description is largely complete. It names the key output dimensions (request count and credits) and covers operational behavior (cost, caching, failures). It could be more explicit about the exact response fields (e.g., route name, count, credits) but given the low complexity, the current level is sufficient.

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

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

The input schema has 100% description coverage, with both days and limit clearly documented including defaults and maximums. The tool description itself adds no parameter-specific semantics, so the baseline score of 3 is appropriate. The limit parameter already notes it is free, so the description does not need to repeat this.

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

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

The description clearly identifies the resource ('most used API routes') and the dimensions ('by request count and credits'), making the tool's purpose understandable. It does not use an explicit verb like 'list' or 'get', but the intent is unambiguous. It distinguishes itself from siblings like account_daily_usage and account_request_history by focusing on routes, not usage history or balances.

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?

No explicit guidance is given for when to use this tool versus alternatives. The description implies it is a lightweight way to see top routes, but it does not mention alternate tools like account_request_history for detailed logs or account_daily_usage for daily breakdowns. The cost note ('Costs ~0 credits') hints at a use case, but no direct comparison or exclusions are provided.

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

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

With no annotations, the description carries the full burden. It explicitly states cost behavior: 'Costs ~0 credits; cached results are free, failures are never charged.' This is valuable behavioral context beyond simple read/write hints. It also mentions 'live', indicating real-time data, but does not disclose potential error behavior or return format details beyond the listed 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 description is two sentences, front-loaded with the core purpose, followed by filter and cost details. No redundant or filler language. Every phrase adds value, making it very 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?

Despite lacking an output schema, the description lists key response fields (requestId, creditsUsed, cacheHit), giving a partial picture of return values. It covers cost, caching, and failure charging. Filter parameters are mentioned and match the schema. It doesn't mention ordering or pagination, but for a simple log tool this is reasonably complete.

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

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

Schema description coverage is 100%, so all parameters are already well-documented. The description lists 'endpoint/statusCode/since/until' as filter options but adds no additional parameter semantics beyond what the schema provides. It also mentions response fields, which are not parameters, so the contribution to parameter understanding is minimal.

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

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

The description clearly identifies the resource as a 'live request log' and specifies key fields (requestId, creditsUsed, cacheHit). It distinguishes this from sibling account tools like account_balance and account_daily_usage. However, it lacks an explicit verb like 'list' or 'retrieve', relying on the noun phrase to imply the action.

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

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

The description implies usage for inspecting request history, but it does not explicitly state when to use this tool versus alternatives or provide exclusions. It highlights that the tool is free, which suggests low risk, but there is no direct guidance about when to prefer it over other account-related tools.

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

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

With no annotations, the description carries full behavioral disclosure. It adds useful context: cost (~1 credit), cache behavior (free results), and failure policy (never charged). It also describes the output fields and pagination, which goes beyond the schema. This is strong transparency for a read-only fetch 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?

The description is two concise sentences, front-loaded with the core purpose and followed by cost/caching information. Every sentence provides important information without redundancy. Ideal length for the tool's complexity.

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

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

Given no output schema, the description adequately explains what the tool returns (products with price, badges, scrapedAt, cursor pagination) and provides cost and caching context. Combined with the fully detailed input schema, the description is complete for an agent 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 baseline is 3. The description does not add any parameter-specific meaning beyond the schema; it only mentions output fields and cost. The schema already fully documents all five parameters, so the description adds no extra value 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 clearly identifies the resource: Amazon seller storefront products, and mentions the included fields (price, badges, scrapedAt) and cursor pagination. It lacks an explicit verb like 'get' or 'list', and does not distinguish from siblings, but the intent is 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 no guidance on when to use this tool versus alternatives. It only mentions cost and caching, but no scenarios, exclusions, or comparisons to other shop-related tools. The schema's URL description includes some exclusions (e.g., influencer /shop/ pages), but that is within structured schema, not the description.

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

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

With no annotations, the description carries the full burden and delivers useful behavioral context: 1 credit per resolved URL, cache hits free, failures never charged. It also clarifies that mixing platforms is allowed. This goes beyond what the schema provides, though it does not detail error responses or the exact return structure.

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

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

The description is short and front-loaded with the purpose, but it contains redundancy: '1 credit per resolved URL; cache hits free' is repeated again as 'Costs ~1 credit; cached results are free'. This duplication wastes words and reduces the efficiency of the message.

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 multi-URL tool with cost and caching nuances and no output schema, the description covers cost, failure policy, and mixing platforms. However, it does not specify the output format (e.g., a list keyed by URL) or handle edge cases like invalid URLs, rate limits, or resolution behavior. It relies on the reader's familiarity with the standard analytics/post object.

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% since both parameters have descriptive text. The description adds minor semantics beyond the schema (e.g., 'cache hits free' ties to the cache parameter, '1 credit per resolved URL' clarifies urls cost). However, it does not substantially compensate for or extend the schema's 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 implies the tool returns the standard analytics/post object for each of up to 10 URLs, but it never explicitly states a verb like 'retrieve' or 'compare'. The phrase 'Same analytics/post object per URL' is vague and does not clearly differentiate this from simply calling the single analytics_post tool multiple times.

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 context ('Mix platforms freely') that suggests cross-platform comparison, and the cost/cache information hints at when to use it (e.g., use cache for free). However, it does not explicitly state when to use this tool versus alternatives like analytics_post, nor does it mention any exclusions.

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

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

No annotations are provided, so the description carries the burden. It discloses cost behavior (flat 1 credit, cached free, failures never charged) and mentions approximation flags, which adds useful context. However, it does not mention auth requirements, rate limits, or error behavior, and the lack of an output schema leaves return format unclear.

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

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

The description is two sentences, front-loads the core purpose, and each sentence adds distinct value (what it does, then cost/caching behavior). No redundant or filler 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 read-only analytics tool with no output schema, the description covers purpose, key metric attributes, and cost/caching. It does not explain the full response structure or error handling, but the essential operational context is present. The lack of an output schema is partially compensated by naming key output fields.

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 covers 100% of parameters with detailed platform lists and cache behavior. The description adds no new parameter-level semantics beyond what the schema already provides, and the extra metrics mentioned (engagementRateBasis, approximation flags) are output fields rather than input parameters.

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

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

Description clearly states it provides unified metrics for one post across 11 platforms with auto-detection, distinguishing it from platform-specific detail tools and analytics_compare. The purpose is specific and unambiguous.

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

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

The description implies usage for cross-platform post metrics but does not explicitly guide when to use this tool versus platform-specific alternatives or analytics_compare. Context is present but no exclusions or alternative recommendations are given.

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?

No annotations are provided, so the description carries full responsibility. It discloses cost (~1 credit), caching behavior (cached free, failures not charged), and implies read-only operation. However, it does not detail what 'engagement' includes (e.g., likes, reposts) or specify response format. For a tool with no annotations, this is moderately transparent but lacks depth.

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

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

The description is extremely concise with two short sentences, no redundancy, and essential information (purpose, cost, caching). Every phrase earns its place.

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

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

Given no output schema and sibling tools, the description provides a minimal but adequate overview. It omits return fields and selection guidance among Bluesky tools. For a simple metadata tool with well-documented parameters, it is acceptable but not complete.

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

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

Schema description coverage is 100%, with both parameters (url and cache) fully described in the schema. The description adds cost and caching policy but does not enhance parameter meaning 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 clearly states 'Metadata + engagement for a Bluesky post', specifying the verb (get/details) and resource (Bluesky post). It distinguishes from sibling tools like bluesky_profile (about user) and bluesky_user_posts (list of posts) by focusing on a single post's metadata and engagement.

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

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

The description does not provide explicit guidance on when to use this tool over alternatives. It mentions cost and caching but lacks when-not-to-use instructions or comparisons with sibling tools like bluesky_profile or bluesky_user_posts. The URL parameter description warns against cross-platform URLs, but that's a parameter constraint, not 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?

With no annotations, the description carries the burden and does add useful behavioral context: 'Costs ~1 credit; cached results are free, failures are never charged.' It does not disclose other traits such as authentication needs or rate limits, but the billing/caching note is meaningful beyond the schema.

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

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

The description is very short and contains no filler, earning high marks for conciseness. The use of 'verification{}' and 'labels[]' is compact but somewhat cryptic, so it is not perfectly structured, but it wastes no 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?

There is no output schema, so the description must explain return values, but it only lists vague placeholders like 'counts', 'associated{}', and 'verification{}' without defining their structure or meaning. The cost/caching details do not compensate for the ambiguity in what the tool actually returns.

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 provides full descriptions for both parameters (url and cache), covering 100% of them. The tool description adds little parameter-specific meaning, except that cached results are free, which is implied by the cache parameter but not stated 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 clearly identifies the tool as returning a Bluesky profile with components like counts, banner, verification, labels, and associated data, distinguishing it from sibling post/details tools. However, it lacks an explicit verb such as 'get' or 'fetch', so it stops short of a fully specified action.

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

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

No guidance is given for when to use this tool versus alternatives like bluesky_post_details or bluesky_user_posts. The description only mentions cost and caching behavior, which are operational details rather than 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?

No annotations are provided, so the description bears full responsibility. It discloses cursor pagination, cost (~3 credits), caching (free results), and failure charging policy. However, it omits rate limits, authentication requirements, error behavior (e.g., private profile), and how 'recent' the posts are.

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

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

Two sentences, no redundant information. The first sentence captures core purpose and output, the second adds cost behavior. Highly efficient and front-loaded.

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

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

Given no output schema, the description adequately lists output fields (text, author, likes, reposts, embeds) and mentions pagination. It covers cost and caching. Missing details on error cases, rate limits, and return format structure, but still sufficiently informative for a simple data retrieval tool.

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

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

Schema coverage is 100% with detailed parameter descriptions. The tool description adds no additional meaning beyond the schema (e.g., cost hint is not parameter-specific). Baseline 3 is appropriate.

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

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

The description clearly states the verb ('list recent posts'), the resource ('Bluesky profile'), and the data fields ('text, author, likes, reposts, embeds; cursor pagination'). It distinguishes from sibling Bluesky tools (bluesky_profile and bluesky_post_details) by focusing on posts.

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

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

The description provides pricing and caching guidance but lacks explicit when-to-use vs alternatives. The input schema includes a note about not passing cross-platform URLs, which implies correct usage, but no direct mention of when not to use this tool or alternative options.

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?

No annotations are provided, so the description carries the full burden. It does disclose useful behavioral traits: cost (~2 credits), cached results are free, and failures are never charged. This adds context beyond the schema, but it omits other behavioral specifics like read-only nature, rate limits, or response contents. This is adequate but not 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?

The description is a single sentence with two clauses, front-loaded with the tool's identity and then cost/caching. Every word earns its place, and it is appropriately sized for a low-complexity tool.

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

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

For a 2-param tool with no output schema, the description covers cost and cache but not return values or usage context. It is sufficient for basic selection but lacks details about what 'details' are returned, making it somewhat incomplete for an agent to know what to expect.

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

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

Schema coverage is 100% with detailed descriptions for both parameters (URL platform matching and cache behavior). The description itself adds no parameter semantics beyond what's in the schema, 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?

The description is a noun phrase ('Meta/Facebook ad details') rather than a verb statement. It restates the tool name and doesn't specify what 'details' entails, nor does it distinguish it from sibling tools like facebook_ad_library_ad_transcript. It clarifies the platform but leaves the core purpose vague.

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?

No guidance is provided on when to use this tool versus alternatives. It doesn't mention that this tool is for specific ad details, nor does it compare with search or transcript siblings. The only usage hint appears in the schema's URL description about platform matching, which is a constraint rather than usage guidance.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It adds valuable operational context: cost (~17 credits), cached results are free, and failures are never charged. This goes beyond a generic read operation, though it doesn't describe response format or prerequisites.

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

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

Two concise, front-loaded sentences with no filler. The first states the action and resource; the second adds cost and caching caveats. Every sentence earns its place.

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

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

For a two-parameter tool, the description plus schema covers purpose, platform constraint, cache behavior, and cost, which is sufficient for basic invocation. It could mention alternative tools or response structure, but the absence is not critical for this simple extraction tool.

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

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

Schema coverage is 100%, with both url and cache parameters fully described, including the platform-matching warning on url. The description adds no parameter-specific meaning beyond the schema, 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 uses a specific verb-resource pair ('Extract creative text from a Meta/Facebook ad as transcript text') that clearly states the tool's function and output. This distinguishes it from sibling tools like facebook_ad_library_ad_details and generic video_transcript tools.

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

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

The description implies usage (for getting ad creative transcript text) but provides no explicit when-to-use vs alternatives. It doesn't mention using ad_details for structured metadata or other transcript tools, though the schema's cross-platform URL warning adds some 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?

With no annotations, the description discloses important behaviors: 'Costs ~2 credits; cached results are free, failures are never charged.' This adds billing and caching semantics not inferable from the schema. However, it does not describe what data is returned or any rate limits, so it is not fully transparent.

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

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

The description is two short sentences: the first states the core purpose, the second gives cost/caching behavior. Every word contributes value with no redundancy 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?

No output schema exists, and the description does not explain what the returned 'ads' include (IDs, spending, creative, etc.). Given the tool has 4 parameters and no annotations, this is a significant gap. The cost information helps but does not offset the lack of return-value 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 description coverage is 100%, so the baseline is 3. The description's first sentence restates the url parameter's purpose but adds no new detail beyond the schema. The schema already thoroughly documents all parameters (e.g., cache, limit, country).

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 'Ads for a Facebook page or Meta Ad Library URL' clearly identifies the resource type but lacks an explicit verb (e.g., 'get' or 'list'). It distinguishes from siblings by the URL input and 'company ads' focus, though this is more evident from the tool name than the description.

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

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

The description does not mention when to use this tool versus alternatives like facebook_ad_library_search or facebook_ad_library_ad_details. The schema includes a warning about cross-platform URLs ('Do not pass cross-platform URLs'), but that is a constraint, not a comparative usage guideline.

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

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

With no annotations, the description carries the full behavioral burden. It explicitly discloses cost (~2 credits), cache semantics (free cached results), and failure policy (never charged), which adds meaningful behavioral context beyond the schema. It does not describe return structure or permission requirements, but the safety profile of a read-only search is implied.

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

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

The description is two sentences with no filler. The opening sentence front-loads the core purpose and filters, and the second sentence provides essential cost/cache info. Every word earns its place.

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

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

Given the rich 100%-covered schema, the description is sufficient for selection and invocation: it names the resource, keyword search, filter groups, and cost behavior. It does not explain the output format, but no output schema exists and the schema covers all parameter defaults and allowed values, so the overall package is complete.

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

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

The input schema covers all 11 parameters with descriptions, so the baseline is 3. The description adds only a high-level grouping of filter types (status, media, date, sort), which maps to some but not all parameters (ad_type, country, search_type, and limit are not mentioned). This adds modest value without compensating for any schema gaps.

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 ('Search') with a clear resource ('Meta/Facebook ads') and enumerates filter dimensions (status, media, date, sort), which distinguishes it from sibling tools like ad_details, company_ads, and ad_transcript. The scope (by keyword) is explicit and the description is not a tautology.

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?

No guidance is provided about when to prefer this tool over the many sibling ad-library tools (e.g., facebook_ad_library_company_ads, google_ad_library_search_ads). The description only states what it does, not when to use it vs. alternatives, so agents must infer usage from the name and schema.

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

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

With no annotations, the description carries the burden of behavioral disclosure. It adds valuable details: approximate credit cost, free cached results, and no charge on failures. This goes beyond the schema, though it omits return format and pagination 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?

Two sentences, front-loaded with purpose, and every sentence provides value: the first explains what the tool does, the second covers cost and failure policy. No redundancy or fluff.

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

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

For a simple search tool with a fully described schema, the description is fairly complete. It covers purpose, cost, caching, and failure behavior. Gaps include return value structure and pagination, but these are not critical given the tool's simplicity and the schema's completeness.

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

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

Schema coverage is 100% with all parameters documented. The description adds no new parameter semantics beyond the schema; the mention of 'by name' maps directly to the 'q' parameter. Baseline 3 is appropriate.

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

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

The description clearly states the tool's function: finding advertisers/pages in the Meta Ad Library by name. The verb 'Find' and the resource 'advertisers/pages' are specific and distinguish this tool from siblings like 'facebook_ad_library_search' or 'facebook_ad_library_company_ads'.

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

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

The description gives clear context for usage: searching by name and the associated credit cost. However, it does not explicitly exclude alternatives or name sibling tools for specific scenarios, so it lacks the explicit comparison that would merit 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?

With no annotations, the description adds useful behavioral details including cost (~2 credits), free cached results, and no charge for failures. It also notes the output shape matches comments. However, it lacks details on pagination, rate limits, or full response structure, leaving moderate transparency.

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

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

The description is a single, front-loaded sentence covering purpose, output shape, and cost. It is concise with no wasted words or redundant information.

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

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

The tool has no output schema, and the description only vaguely references the comments shape rather than providing full return structure. Cost and caching are covered, but usage prerequisites and detailed response format are omitted. It is adequate for a simple tool but has clear gaps.

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

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

Schema description coverage is 100%, so all parameters are already documented in the schema. The description adds no additional parameter-specific meaning beyond the schema, meeting the baseline but not exceeding it.

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 'Replies to a Facebook comment' with a specific verb and resource. It also mentions the output shape relative to comments, providing context. However, it does not explicitly distinguish from sibling tools like facebook_comments, relying on the tool name for differentiation.

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 vs alternatives. It does not state that comment_id should come from the comments endpoint or that this is the follow-up to fetching comments. No alternatives or exclusions are 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?

With no annotations, the description carries the full burden. It discloses cost behavior (~2 credits, cached free, failures not charged) and hints at response structure (stable author.id, replyCount, hasMore). However, it does not explain pagination mechanics, rate limits, or authentication needs. The '10-type reactions{}' is cryptic and under-specified.

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 very short and front-loaded with 'Facebook comments'. It packs cost and response hints into two sentences. However, the phrasing is telegraphic ('10-type reactions{}') and lacks natural flow, slightly undermining clarity. Still, it is concise without unnecessary 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?

This tool has no output schema, so the description must compensate for return-value documentation. It mentions a few fields but does not describe the overall response structure, how pagination works with hasMore, or how replies relate to this tool. Given the complexity of Facebook comments, the description is insufficient for an agent to fully understand what will be returned.

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 parameters (url, cache, limit, feedbackId) are fully explained in the schema. The description adds no parameter-level detail, which is acceptable given the schema's completeness. The baseline of 3 applies because the description does not add or contradict parameter semantics.

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

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

The description clearly indicates this tool deals with Facebook comments by naming the resource and listing key attributes like reactions and author.id. It is implicitly distinct from facebook_comment_replies, which handles replies, but the description does not explicitly state 'get comments for a post or reel.' The name itself carries most of the purpose.

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

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

No guidance is provided on when to use this tool versus alternatives like facebook_comment_replies or facebook_details. The only behavioral note is about cost and caching, which does not help an agent decide between this and sibling tools. It lacks any 'use this when' or 'prefer this over X' 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?

With no annotations, the description carries the burden of disclosing behavior. It discloses cost (~2 credits), caching benefits, and that failures are never charged. However, it does not mention rate limits, authentication requirements, or behavior on private/unavailable content beyond 'when exposed'.

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 sentence that efficiently conveys purpose and key behavioral notes. It avoids redundancy with the schema. Every clause serves a 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 two-parameter tool with no output schema, the description covers the core purpose, key return fields, and pricing/caching behavior. It is reasonably complete for a details-retrieval tool, though it could mention error handling or privacy restrictions.

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

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

The schema already provides 100% coverage for both parameters (url and cache) with descriptions. The tool description adds no new parameter-specific semantics beyond mentioning data fields returned, which are not directly tied to parameters. Baseline of 3 applies due to high schema coverage.

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

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

The description clearly identifies the tool as retrieving Facebook post or Reel details and lists specific data fields (engagement, author id, SD/HD video, captions, music). It distinguishes from sibling tools like facebook_page_details by specifying post/reel. However, it lacks an explicit verb like 'get' or 'fetch', relying on the noun 'details'.

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

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

The description implies the tool is for obtaining Facebook post/reel details but does not explicitly state when to use it over alternatives. No exclusions or comparisons to sibling tools are provided. The only usage guideline is in the schema's URL description about platform matching, which is a parameter constraint rather than a usage recommendation.

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?

No annotations are provided, so the description carries the full burden. It mentions credit cost and that cached results are free, but does not disclose fail behavior, auth needs, or side effects. It is inadequate for a mutation-free 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?

The description is a single sentence plus a brief clause on credits. It is front-loaded with purpose and contains no redundant information. Every word earns its place.

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

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

Given the tool has only 2 parameters with full schema coverage and no output schema, the description adequately lists the kind of details returned (date, location, attendees, tickets) and mentions credit cost. It could expand on pagination or limitations but is sufficient for a simple read tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds credit cost context but does not enhance parameter meaning beyond what the schema provides (URL format and cache flag). The note about cross-platform URLs is already in the schema description.

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

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

The description clearly states the tool returns details for a Facebook event including date, location, attendees, tickets. This is specific and identifies the resource. However, it does not explicitly distinguish it from sibling tools like facebook_event_search or facebook_details, though the name implies a single event.

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 credit cost and caching behavior but gives no guidance on when to use this tool versus alternatives (e.g., facebook_event_search for finding events). There is no mention of prerequisites or context for 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It adds meaningful context about credit costs (~40 credits), free cached results, and no charges on failures. However, it omits other important behaviors like return format, pagination, or whether any side effects occur, leaving some gaps typical of a search 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?

The description is two sentences long: the first states purpose and scope, the second discloses cost and failure policy. Every word earns its place; no unnecessary repetition of the tool name or schema information. Perfectly front-loaded with the primary action.

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 search tool with no output schema and moderate parameter complexity, the description covers the essential context: what it searches, cost mechanics, caching behavior, and failure charging policy. It implicitly tells the agent the return is a list of events. While it doesn't detail response structure, that is not required since no output schema exists, and the description is sufficiently complete for selection and invocation.

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

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

The input schema already provides full descriptions for all three parameters (100% coverage), including a concrete example for 'q' and billing details for 'limit'. The description's mention of 'by topic and/or location' reinforces 'q' and 'cached results are free' clarifies 'cache', but these are supplementary rather than essential, so the baseline score of 3 is appropriate.

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

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

The description uses a specific verb ('Search') and identifies the exact resource ('Facebook events') with clear scope ('by topic and/or location'). It distinguishes itself from sibling tools like facebook_event_details (which implies retrieving a specific event) and facebook_profile_events (events associated with a profile) by focusing on topical/locational 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 clearly implies when to use this tool: to search Facebook events by topic/location. It provides context about cost and caching, but it does not explicitly mention when not to use it or point to alternative tools for other scenarios. This is clear context without exclusions, matching a 4.

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

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

With no annotations, the description carries the full burden. It discloses cost (~2 credits), caching behavior (cached results free, failures never charged), and a data trait (shares null when unknown). These are meaningful behavioral details beyond the schema, though it does not mention rate limits, authentication, or response structure. The disclosed traits are substantial, so a 4 is warranted.

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

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

Two sentences, front-loaded with the core purpose, and every clause adds value: the first sentence defines the resource and output, the second covers cost and caching. No fluff, no repetition of schema details. Excellent structure for a 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?

For a simple read tool with 100% schema coverage and no output schema, the description covers purpose, key output fields, cost, and caching. Missing are return format, pagination, or error behavior, but the tool is straightforward and the schema handles parameters. The description provides enough context for typical usage, though some behavioral edge cases remain unaddressed.

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%, giving a baseline of 3, but the description introduces confusion by listing 'sortBy' (an input parameter) alongside output fields such as 'author IDs' and 'permalink'. This misrepresents the parameter's role and adds no clarity beyond the schema. The description also doesn't clarify the semantics of 'engagement' further, so the slight confusion lowers the score below baseline.

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

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

The description clearly states it retrieves public Facebook group posts and lists key output fields (author IDs, permalink, engagement). This distinguishes it from sibling tools focused on profiles or pages, and the noun phrase 'Public Facebook group posts' implies a retrieval action. It is specific and unambiguous.

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

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

The description implies usage for public Facebook group posts but does not explicitly exclude other platforms or mention alternatives. The schema adds a note about not passing cross-platform URLs, but the description itself lacks when/when-not guidance relative to siblings like facebook_profile_posts or facebook_page_details. Usage is implied rather than 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?

With no annotations provided, the description carries the transparency burden. It usefully discloses that the tool costs ~1 credit, cached results are free, and failed requests are never charged — meaningful economic and error-handling behavior. It doesn't describe the response structure or rate limits, but for a simple read-only detail tool this is solid disclosure.

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

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

The description is two short sentences, front-loaded with the core purpose and followed by concise, relevant billing/caching details. Every word adds value, with no repetition of schema 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 two-parameter single-item lookup with no output schema, the description covers the essential context: what the tool does, cost, caching behavior, and failure policy. The URL input is specified in the schema, so the description doesn't need to repeat it. It is sufficiently complete 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?

The input schema already describes both parameters clearly (url and cache) with 100% coverage, so the baseline is 3. The description adds practical semantics by noting that cached results are free, which gives the cache parameter meaningful cost context beyond the schema's mechanical definition. This extra layer justifies a 4.

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

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

The description states the tool returns 'Details for a single Facebook Marketplace listing,' using a clear retrieve-type verb and a specific resource. It distinguishes from sibling tools like facebook_marketplace_search and facebook_marketplace_location_search by focusing on a single listing. It stops short of explicitly naming alternatives, so it's very clear but not perfect.

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

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

Usage context is implied: use this tool when you need details for a specific Facebook Marketplace listing. However, there is no explicit guidance on when to prefer this over the search/location siblings or any exclusions. Cost and caching notes are behavioral, not applicability 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?

With no annotations, the description discloses crucial behavioral detail: flat credit cost, caching policy (cached results free, fresh fetch default), and that failures are never charged. It also hints at return content (cityPageId + lat/lng). While it doesn't mention side effects or auth, as a search/lookup tool this is strong transparency.

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

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

Two dense sentences fully cover purpose, usage, alternatives, and pricing. Every clause adds value; no fluff. The description is front-loaded with the core disambiguation function, then usage guidance, then cost 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?

The description is self-contained: it explains what the tool does, when to use it, what it returns (cityPageId + lat/lng), and cost behavior. It complements the schema without needing an output schema, and addresses the ambiguity problem clearly.

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

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

Schema already defines all parameters with 100% coverage, so baseline is 3. The description adds disambiguation nuance (bare 'Austin' may return multiple states; include state for single hit) and clarifies cache default behavior, going beyond the schema's basic descriptions.

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

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

The description uses a specific verb ('Disambiguate city names') and names the exact resource ('Marketplace hubs with Facebook cityPageId + lat/lng'). It explicitly contrasts with the sibling tool facebook_marketplace_search, which already accepts a city string, clearly distinguishing this tool's purpose.

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

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

The description explicitly states when to use this tool over the sibling: for ambiguous names (Austin TX vs MN) or when needing cityPageId. It also names the alternative tool directly, providing clear decision-making 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It adds valuable context about cost ('Costs ~2 credits'), caching ('cached results are free'), and failure policy ('failures are never charged'). However, it does not disclose return format, pagination behavior, data freshness, or other potential side effects. The cost and cache policy partially compensate for the lack of 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 two concise sentences. The first sentence states the core purpose with a specific verb and object; the second provides a concise operational note on credits and caching. Every word earns its place, and the structure is front-loaded with the most important 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 tool with 15 parameters and no output schema, this description is too minimal. It establishes the core function and cost but does not explain the shape of the response, pagination via cursor, the meaning of the details parameter (which incurs extra credits), or any practical usage context. The rich schema covers parameter semantics but not overall tool behavior, leaving the AI agent without sufficient context to set expectations.

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%, meaning all 15 parameters have individual descriptions. The main description mentions 'keyword and city name,' which maps to the required q and location parameters but adds no new semantic information beyond what the schema already states. The baseline of 3 applies because the schema does the heavy lifting.

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

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

The description clearly states the tool's function: 'Search Facebook Marketplace listings by keyword and city name.' The verb 'Search' plus the resource 'Facebook Marketplace listings' and the qualifiers 'by keyword and city name' make the purpose explicit and distinguish it from sibling tools like facebook_marketplace_item (which fetches item details) and facebook_marketplace_location_search (which focuses on location-based 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 no guidance on when to use this tool versus alternatives. It does not mention exclusions, preferred scenarios, or relationships to sibling search tools. The only usage-related note is about cost and caching, which is operational rather than directional.

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

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

With no annotations provided, the description carries the burden of disclosing behavior. It adds valuable context about cost: 'Flat 2 credits', 'cached results are free', and 'failures are never charged'. This explains pricing and caching behavior beyond the schema. However, it does not explicitly state that the tool is read-only or describe data freshness beyond what the cache parameter already implies.

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 very brief and front-loaded with the purpose, followed by cost details. It is efficient, though slightly redundant: 'Flat 2 credits' and 'Costs ~2 credits' repeat the same idea. Overall, it earns its place without unnecessary filler.

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

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

For a simple tool with two parameters and no output schema, the description provides a reasonable list of return fields and cost/caching behavior. However, it omits usage guidance and alternative tool comparisons, and it does not mention potential errors or the default fetch behavior (though the schema covers cache default). It is minimally viable but not 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 documents both parameters with full coverage (100%). The description adds no parameter-specific meaning beyond mentioning 'cached results are free', which relates to the cache parameter but does not clarify its semantics. Baseline of 3 is appropriate since the schema handles 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 clearly identifies the tool as providing a 'Facebook page profile' and enumerates specific data fields (likes vs followers, talkingAbout, category, website, public email), which distinguishes it from sibling tools focused on posts, comments, or events. However, it lacks an explicit verb like 'retrieve' or 'get', so the action is implied rather than stated.

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 no guidance on when to use this tool versus alternatives like facebook_profile_posts or facebook_details. It does not mention any exclusions or prerequisites. The only contextual hint is the cost information, which is not usage guidance.

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

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

With no annotations, the description carries the full burden. It discloses cost (~40 credits), caching behavior (cached results free), and failure policy (never charged), but does not mention whether the operation is read-only, return format, or any prerequisites like public URL. The cost/caching info adds value beyond the schema, but other behavioral aspects remain undocumented.

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

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

The description is two sentences, front-loaded with the core purpose, and includes valuable cost/caching information in the second sentence. Every word earns its place with no redundancy 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?

For a simple read tool with three documented parameters and no output schema, the description adequately conveys the basic content (events from a profile/page) and cost behavior. However, it doesn't describe the structure of the returned events or error cases, which would be helpful since there is no output schema.

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

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

Schema description coverage is 100% and each parameter (url, cache, limit) is already well-documented in the schema. The description adds no parameter-specific meaning beyond the note about credit costs, so it doesn't enhance what the schema already provides.

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

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

The description states the tool retrieves events from a Facebook profile or page, which is clear and specific. It distinguishes itself from sibling tools like facebook_event_search and facebook_event_details by focusing on events associated with a given profile/page, though it lacks an explicit verb like 'list' or 'get'.

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 usage when you need events from a specific Facebook profile or page, but it doesn't explicitly mention alternatives or exclusions. The cost and caching details add context but do not clarify when to choose this tool over facebook_event_search or other event-related tools.

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

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

No annotations exist, so the description carries the burden. It adds useful behavioral context: cost (~12 credits), free caching, and no charge on failures. However, it doesn't disclose what happens on failure (e.g., error behavior), the return format of photos, or any rate limits or authentication 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?

Two short sentences, front-loaded with the tool's purpose, followed by cost details. Every word earns its place with no fluff or redundant restatement of the name.

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 3-parameter tool with no output schema, the description gives purpose and one behavioral trait (cost), but lacks details about response contents, handling of invalid URLs, or any practical usage examples. It is sufficient for basic selection but not fully self-contained for invocation.

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

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

Schema description coverage is 100% for all 3 parameters, so the description adds minimal param-specific value. The cache and limit parameters are already well-documented in the schema. The description's cost/caching info is general rather than mapping to specific parameters, so 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?

Description states 'Photos from a Facebook profile or page', clearly identifying the resource and kind of data. However, it lacks an explicit verb like 'get' or 'list', so the action is implied rather than stated. It distinguishes from siblings like facebook_profile_posts or facebook_page_details by specifying photos.

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?

No guidance on when to use this tool versus alternatives. There is no mention of preferred scenarios, prerequisites, or exclusions. The cost and cache notes are operational, not usage direction.

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

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

With no annotations, the description carries the full burden for behavioral disclosure. It does disclose cost (~12 credits), caching behavior (cached results are free), and failure policy (failures are never charged), which is valuable. However, it omits whether the operation is read-only, any authentication needs, or response format, making the disclosure partial.

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 exactly two sentences, with the first stating the primary purpose and the second covering cost and failure behavior. There is no redundancy or filler, making it highly concise and front-loaded.

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

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

For a simple read-oriented tool with fully described parameters and no output schema, the description covers the essential context: what it does, cost, caching, and failure policy. It lacks explicit mention of return format, but given the tool's simplicity and the 'posts' label, this is adequate. Minor gaps around requirements for the URL are already handled in the schema.

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

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

The input schema provides 100% coverage for all three parameters, with detailed descriptions for url, cache, and limit. The tool description does not add parameter-specific meaning beyond what the schema already states. The cache-related cost note is useful context but not a parameter semantic, 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 'Latest posts from a Facebook profile/page' clearly states the action (get latest posts) and the resource (Facebook profile/page), distinguishing it from sibling tools like facebook_group_posts. However, it does not explicitly name alternatives or highlight what differentiates it, so it falls short of a 5.

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

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

The description provides no guidance on when to use this tool versus alternatives. There is no mention of exclusions, prerequisites, or similar tools, leaving the agent without direction on tool selection. The cross-platform warning in the URL parameter is about parameter validation, not 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?

No annotations are present, so the description carries the burden. It discloses cost (~2 credits), caching behavior (cached free, failures not charged), and the archive cliff. This is useful behavioral context, though it does not detail return structure or authentication.

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, dense sentence that packs purpose, ordering, cost, caching, and failure behavior into minimal text. No waste.

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

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

Given no output schema, the description explains the general return type (Reels with full engagement) and key constraints (cost, caching, archive cliff). It lacks specifics on engagement metrics or pagination but is sufficient for a basic understanding.

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 3 applies. The description adds indirect context (e.g., 'latest' and 'archive cliff' help understand the limit parameter) but does not directly explain parameter usage beyond the schema.

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

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

The description clearly specifies the resource (page Reels), the action (retrieve latest), and the ordering (newest-first). It also distinguishes itself from siblings like facebook_profile_posts by focusing on Reels, and the 'archive cliff' clarifies scope.

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 when to use this tool (for latest Reels only) and notes the archive cliff limitation, but it does not explicitly name alternatives or state when not to use it. This is clear context but lacks explicit exclusions.

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

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

With no annotations, the description discloses cost (~4 credits), caching policy (free, 24h), and failure charging (never). This adds useful behavioral context beyond the tool's name.

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

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

Two sentences, front-loaded with purpose, no wasted words. Each sentence adds valuable 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 simple summarization tool with no output schema, the description covers purpose, usage constraints, cost, and caching. Minor gap: no mention of summary format (e.g., text, points). Still adequate.

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

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

Schema coverage is 100%, but the description adds context: url must be public and platform-specific, and cache parameter default behavior (false) and cache duration (24h). This adds value beyond the schema.

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

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

The description clearly states the verb 'summarize' and the resource 'Facebook video or post'. It distinguishes from sibling tools like youtube_summarize and instagram_summarize by specifying the platform.

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

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

Explicitly states 'Public Facebook video or post URL' and warns against cross-platform URLs, providing 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?

No annotations are provided, so the description fully carries the burden of behavioral disclosure. It richly details the typed payload structure, event examples, the 90-event ceiling, the opaque Link cursor, the ~12 credit cost, caching benefits, and that failures are never charged. This comprehensive disclosure goes well beyond what is typical and covers operational behaviors an agent needs to know.

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, each delivering distinct information: purpose/typed payload, ceiling/cursor behavior, and cost/caching/failure policy. It is front-loaded with the main purpose and every sentence earns its place without redundancy or fluff.

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

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

Given the tool has 4 parameters and no output schema, the description is remarkably complete. It covers the essential behavioral aspects: what is returned (typed payload), limits (90-event ceiling), pagination (opaque Link cursor), cost (~12 credits), caching (free cached results), and error handling (failures never charged). An agent would have sufficient context 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?

The schema already provides descriptions for all four parameters (100% coverage), setting a baseline of 3. The description adds valuable context beyond the schema by explaining the 90-event ceiling (relating to limit), the opaque Link cursor (for cursor), and that cached results are free (for cache). This extra context enhances understanding of how the parameters behave in practice, meriting a 4.

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

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

The description clearly identifies the tool as returning public events with typed payloads, citing examples like Push commits/ref and PR/issue actions. This distinguishes it from sibling tools like github_contributions or github_repositories by focusing on the event stream. However, it lacks an explicit verb such as 'list' or 'fetch,' so the purpose is clear but not fully precise.

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 retrieve public GitHub events for a user, which is evident from the context. However, it does not explicitly state when to use this tool versus alternatives like github_contributions or github_pull_requests, nor does it mention exclusions or prerequisites. The usage guidance remains implicit rather than 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It transparently states the source (public calendar HTML), pricing ('Flat 2 credits'), and cache/failure behavior ('cached results are free, failures are never charged'). This adds valuable context about cost and side effects, though it does not mention rate limits or authentication requirements. 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 mostly concise and front-loaded with the core purpose. However, the pricing statement is redundant and slightly contradictory: 'Flat 2 credits. Costs ~2 credits.' This wastes a few words and could confuse the reader, so it is not perfectly polished.

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

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

For a tool with only 2 parameters, no output schema, and no annotations, the description covers the key aspects: output structure, source, pricing, and cache behavior. It does not explicitly mention that the username is required or how errors are handled, but those are implied by the schema. The redundancy in pricing is minor. Overall, it is adequately complete 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?

The schema already provides full descriptions for both parameters (username, cache), so the baseline is 3. The description adds value by explaining the cost implications of the cache parameter ('cached results are free') and reiterating that default is fresh data. This complements the schema without repetition, making the parameter semantics clearer.

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 returns the GitHub contribution graph with specific fields (totalContributions, currentStreak, days[{date,count,level}]). It distinguishes itself from sibling tools like github_user or github_activity by focusing on contribution data and specifying the source (public calendar HTML). The implied verb 'returns' is evident from the context and tool name.

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

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

The description does not provide guidance on when to use this tool over alternatives. It mentions cost and caching behavior, but no explicit 'use this when...' or 'instead of...' statements. There is no mention of prerequisite conditions or exclusions, leaving the agent to infer usage from the tool name and schema.

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

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

With no annotations provided, the description carries the full transparency burden. It discloses costs (~0.1/row, ~3 credits), caching behavior, failure charging policy, and the opaque Link cursor. This is substantial non-obvious behavior, but it stops short of mentioning authentication or a read-only guarantee.

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

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

Two dense sentences convey output fields, cost, pagination, caching, and failure policy without any filler. Every clause earns its place and the key output details are front-loaded.

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

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

Even without an output schema, the description states the exact output shape (id, login, type, url, avatar). It covers cursor semantics, cost, caching, and failure behavior, which is solid for a paginated listing tool. A minor gap is that it doesn't explicitly mention the nextCursor response field, though the schema references 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?

The input schema already provides 100% coverage with descriptions for all four parameters, so the baseline is 3. The description adds cost and caching context but does not add parameter-specific meaning beyond what the schema already 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?

The description opens with 'Follower cards {id,login,type,url,avatar}', making it clear that the tool returns GitHub follower records and their fields. It lacks an explicit verb like 'list' or 'get' and does not distinguish itself from the sibling tool github_following, so it falls short of a 5.

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

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

The description provides practical usage context: per-row cost, opaque cursor behavior, expensive full paging for large accounts, and free cached results. This gives clear guidance about when to use caching or avoid exhaustive paging, though it does not explicitly name alternatives or state when not to use 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?

With no annotations, the description carries the full burden. It discloses useful cost behavior (~3 credits, cached results free, failures not charged) and cursor type, but omits core behavioral traits like read-only status, return format, rate limits, or authentication needs. Partially transparent but incomplete.

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 sentence with no filler, making it concise. However, it prioritizes pricing over the tool's primary purpose, which makes it somewhat cryptic. It still earns high marks for efficiency.

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?

There is no output schema, so the description should explain the return value, but it does not. It covers pricing and cursor mechanics but not what data is returned (the list of followed users), pagination behavior, or error cases. Incomplete for a tool with no output schema.

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

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

Schema coverage is 100%, so the baseline is 3. The description reinforces the cursor parameter with 'Opaque Link cursor,' but this largely duplicates the schema's existing description. No substantial added semantics beyond pricing tied to the limit parameter.

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 explicitly states what github_following does. It references 'followers' for pricing but does not say the tool lists the users a GitHub user follows. The name and schema imply this, but the description itself lacks a clear verb and resource, making it vague and dependent on sibling context.

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?

No explicit guidance on when to use this tool versus alternatives. The mention of 'Same card... as followers' hints at similarity but does not distinguish use cases. It provides cost/caching details but not a decision rule for choosing this over github_followers or other GitHub tools.

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

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

With no annotations, the description carries the behavioral transparency burden. It discloses cost (~12 credits), caching semantics (free cached results), failure charging policy (never charged), and pagination via opaque cursor. This goes beyond a basic 'list' operation and adds useful context. However, it doesn't explicitly state read-only behavior, but the verb 'List' strongly implies it. This is well above minimal, but 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 a single, dense sentence that front-loads the core purpose. It uses compact notation like 'author{}' and 'head/base' which is cryptic but space-efficient. It earns its place by packing cost, cache, and pagination behavior. Not a model of clarity, but appropriately sized for a simple tool.

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

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

There is no output schema, so the description compensates by listing key response fields (draft, labels, author, head/base, state) and pagination cursor behavior. It also explains cost and caching, which is essential for usage decisions. It lacks a concrete return structure example but is sufficient for a straightforward list tool with a well-documented schema.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds marginal value by indicating 'state echoed' and 'opaque Link cursor', which slightly enriches the state and cursor parameters. But it mostly duplicates schema info. It doesn't compensate much beyond the schema, so a 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 'List PRs' with a specific resource. It distinguishes itself from sibling tools like github_repositories by focusing on pull requests, though the rest of the sentence is cryptic. It is a specific verb+resource combination, but the shorthand 'PRs' and density prevent a perfect score.

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 usage is implied: if you need to list pull requests, use this tool. However, there is no explicit mention of when to use alternatives or when not to use this. The cost and caching information provides context for cost-aware decisions but not tool selection. Thus, it meets the 'implied usage' bar but lacks explicit exclusions or 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?

Without annotations, the description carries full burden and does an excellent job. It discloses cost per call, caching behavior, failure billing, pagination via an opaque Link cursor, and field exclusions (parent/watchers). This goes beyond a typical description.

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 3 short sentences, with the core purpose front-loaded. Every clause adds information: cost, cache, page cursor, field exclusions, and failure billing. 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 list tool with 7 parameters and no output schema, the description covers key behavioral caveats (cost, cache, pagination, field exclusions). It does not describe the return structure of a repository object, but the obvious nature of 'list repos' mitigates this. Still, with no output schema, a bit more output detail would earn a 5.

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

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

Schema coverage is 100% with all 7 parameters described, so baseline is 3. The description adds minimal parameter-specific meaning; 'opaque Link cursor' is already in the schema, and 'echoed' refers to response behavior rather than parameter syntax.

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 'List repos' with a specific verb and resource. It distinguishes this tool from the sibling 'github_repository' by noting that parent/watchers are only available there, making the 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 provides an explicit exclusion: 'parent/watchers only on github/repository' tells agents when to use an alternative tool. It also gives cost/caching guidance ('Costs ~12 credits; cached results are free, failures are never charged') to inform cache usage. However, it doesn't state more general 'when to use this list tool vs search/list 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?

No annotations are provided, so the description must carry the burden. It does disclose useful behavioral details: license with NOASSERTION becomes null, parent is included only when the repo is a fork, and cached results are free/failures are not charged. However, it does not mention error behavior, return format, or any authentication requirements, leaving some gaps.

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

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

The description is concise and front-loaded with the core purpose. However, the pricing details are repeated ('Flat 1 credit. Costs ~1 credit') which is slightly redundant and could be streamlined into a single statement.

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 low complexity (2 params, no output schema), the description provides a good overview of the tool's return data and special cases (license conversion, parent for forks). It also includes pricing and caching semantics, making it fairly complete for an agent to understand what to expect.

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

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

The input schema already covers both parameters (repo and cache) with 100% description coverage. The tool description adds no additional parameter semantics, such as accepted formats for repo or examples of URL vs owner/name, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool returns repo details and lists specific data points (stars, watchers, openIssuesAndPrs, license, parent). This makes it clear what resource it targets, though it lacks an explicit verb like 'get' or 'fetch'. It is distinguishable from siblings like github_repositories (plural) by the focused single-repo scope, but this differentiation is not explicitly stated.

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?

There is no guidance on when to use this tool versus alternatives such as github_repositories or github_user. The only additional context is pricing and caching behavior, which does not help the agent decide between tools.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It does add useful context about costs (flat 2 credits, cached results free, failures never charged) and data enrichment ('hydrated'). However, it does not disclose whether the operation is read-only, any authentication requirements, or pagination behavior, leaving significant gaps.

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 short, but it contains redundancy: 'Flat 2 credits' and 'Costs ~2 credits' state the same information in different ways. While not overly verbose, this repetition could be tightened to a single phrase, making it less efficient than it could be.

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

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

Given there is no output schema and no annotations, the description does a fair job of conveying the tool's value and output expectations. It mentions the endpoint, the type of data (windowed ranks, popularRepo, followers, bio), and cost/failure behavior. However, it does not explicitly state the response format (e.g., a list of developer objects) or ordering, which would be helpful 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 schema already provides descriptions for all four parameters (cache, limit, since, language), giving 100% coverage. The description adds minimal parameter-specific meaning beyond the schema, only hinting at the 'since' concept with 'windowed ranks'. Since the schema does the heavy lifting, a baseline score of 3 is appropriate.

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

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

The description clearly identifies the resource as github.com/trending/developers and specifies what it provides: windowed ranks with popularRepo and hydrated followers/bio. This distinguishes it from sibling tools like github_trending_repositories and other GitHub user tools by indicating a focus on trending developers with enriched metadata.

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 offers no explicit guidance on when to use this tool versus alternatives. It does not mention that github_trending_repositories should be used for repositories, nor does it provide any use-case context or exclusions. The user must infer usage from the tool name itself.

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?

Despite lacking annotations, the description discloses cost structure, caching behavior, and the fact that failures are not charged, adding valuable context beyond the schema. It could further describe response format, but the provided details are substantive.

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

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

Two compact sentences, front-loaded with the core purpose and followed by cost details. No redundancy except a minor repetition of the credit cost, which does not detract from clarity.

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

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

The tool is simple with fully documented optional parameters, and the description covers key behavioral details (cost, caching, failure policy). The only gap is the absence of expected return fields, but this is not critical for a trending list 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 covers all parameters at 100%, so the description adds little beyond repeating the since values. Cost/caching details are not parameter-specific, so the description does not enhance parameter understanding.

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?

Specifies the exact source (github.com/trending) and ranking metric (starsGained with since=daily|weekly|monthly), and explicitly contrasts with all-time star search, distinguishing it from sibling tools.

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

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

Clearly indicates when to use (for trending repos by recent star gains) and what it is not for (all-time star search), but does not name specific alternative tools or provide explicit when-not-to-use scenarios.

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

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

With no annotations, the description carries full burden. It discloses the tool returns public profile data, is a 'thin wrap of free GitHub REST' (implying read-only and no auth), specifies camelCase JSON output, and explains the credit/caching model including free cached results and no charge for failures. This is solid but doesn't mention any potential rate limits or edge cases.

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 pack all necessary info: purpose, return type, cost, alternatives, and caching. No wasted words, information is front-loaded and dense but readable.

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

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

No output schema exists, but the description specifies the return as camelCase JSON with User|Organization and email-when-public, which is sufficient for a simple profile tool. It also covers cost, caching, and alternatives. With only 2 params and simple output, the description is complete.

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

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

Schema description covers 100% of parameters, so baseline is 3. The description adds value by giving an example for username ('e.g. getify'), explaining the output format related to the profile, and linking the cache parameter to the cost structure ('cached results are free'). This enhances understanding beyond the schema.

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

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

The description clearly identifies the resource as a GitHub profile with output format (camelCase JSON, User|Organization) and distinguishes from sibling tools like github_activity or github_followers by focusing on the profile itself. However, the verb is implied ('profile as camelCase JSON') rather than an explicit 'get/fetch', and no direct comparison to siblings is given, so it falls just short of a 5.

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

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

Explicitly provides alternatives: 'prefer Captapi for one-key multi-platform, api.github.com for GitHub-only.' It also clarifies when cached results are free and that failures are never charged, giving clear context on cost and behavior.

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

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

With no annotations, the description carries full behavioral burden and does well: it discloses credit costs (~2 credits), caching behavior (free for cached, 24h cache), and failure policy (never charged). It lacks info on response contents, but the cost and failure transparency is valuable beyond schema.

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

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

The description consists of two short, front-loaded sentences with zero wasted words. It immediately states the purpose and follows with essential 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?

The tool has three params, all documented, but no output schema. The description explains cost and caching but is vague about what 'ad details' includes (text, media, dates, etc.). Given the common expectation for an ad-details tool, this is a notable gap, though the cost/cache info elevates it somewhat.

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 already describes each parameter. The description adds extra meaning by linking creative_id to a 'Transparency Center URL' and pointing out that cache=true yields free results, which is not 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 clearly states the tool's function: retrieving Google ad details from a Transparency Center URL. It distinguishes itself from sibling tools like google_ad_library_advertiser_search and google_ad_library_company_ads by specifying the input type (URL) and the granularity (specific ad details).

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 usage when a Transparency Center URL is available and provides cost/cache guidance (e.g., use cache for free results). However, it does not explicitly explain when to prefer this tool over alternatives like google_ad_library_company_ads or how to select based on the required detail level.

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

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

With no annotations provided, the description carries full burden. It discloses cost model (1 credit, cached free, failures not charged) but lacks details on rate limits, data freshness beyond cache hint, or return format. It adds some value but not comprehensive.

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

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

Two concise sentences: first states purpose, second adds cost info. No redundant words. Front-loaded with actionable verb.

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

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

No output schema exists, so description should explain what is returned. It does not mention return structure (e.g., list of advertisers with IDs/names). Cost info is present but lacks completeness about tool output. Adequate but could be improved.

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

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

Schema coverage is 100% with all four parameters described. The main description adds only cost context related to 'cache' param. Since schema already covers parameter meanings, the description adds minimal extra value, meeting baseline.

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

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

The description clearly states 'Search Google Ads advertisers' with a specific verb-resource pair. Among siblings like google_ad_library_ad_details and google_ad_library_company_ads, this tool is uniquely for searching advertisers, making its purpose distinct.

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 mentions cost and caching behavior but does not explicitly state when to use this tool over alternatives or provide exclusions. Usage context is implied but not directive.

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

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

With no annotations, the description carries the transparency burden. It discloses cost (~2 credits), caching behavior, and that failures are not charged. It also mentions pagination and date filters, adding useful behavioral context beyond the schema. It does not discuss rate limits or response structure, but the key side effects are covered.

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

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

The description is concise and front-loaded with the core purpose, followed by a constraint and cost/caching details. Every sentence adds value with no redundancy. It is well-structured for quick scanning.

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

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

For an 8-parameter tool with no output schema, the description covers the key aspects: what it lists, accepted inputs, pagination, date filters, and cost implications. It does not describe the response format, but the absence of an output schema and the list-oriented nature make this a moderate gap rather than a critical one.

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 a high-level summary of parameters (media, cursor paging, optional date filters) but does not provide significant new semantics beyond what the schema already documents. The advertiser parameter formats are already 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 clearly states the tool lists Google Ads Transparency creatives for an advertiser, specifying accepted identifier formats (name, domain, or AR id). It distinguishes from sibling tools by focus on an advertiser's creatives, though it does not explicitly name alternatives like ad_details or advertiser_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 implies usage: when you need creatives for a given advertiser. It also notes a constraint ('Public commercial ads only') and mentions caching and failure charging, which inform usage decisions. However, it does not explicitly compare to sibling tools or provide 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?

With no annotations present, the description carries the full burden, and it covers important behaviors: approximate cost, free cached results, and no charge on failures. It also mentions the camelCase output convention. It does not discuss rate limits or authentication, but for a simple read-only profile fetch this is reasonably transparent.

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

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

The description is a single compact sentence that front-loads the core purpose and packs cost/cache/failure info and an output naming hint without redundancy.

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

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

Despite lacking an output schema, the description gives concrete examples of returned fields (followers, externalUrl, businessAddress) and clarifies cost/cache behavior, which is sufficient for a basic profile fetch. Minor gaps remain around exact field coverage and differentiation from similar Instagram tools.

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 provides 100% coverage for both parameters (userId and cache) with detailed descriptions. The tool description adds no additional parameter-level semantics beyond what the schema states, so 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 clearly states the tool retrieves an Instagram profile by user ID or @handle, with a specific note about camelCase output fields (followers, externalUrl, businessAddress). However, it does not explicitly differentiate itself from sibling tools like instagram_details or instagram_channel_details.

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 cost and caching context (costs ~1 credit, cached results free, failures never charged) but does not state when to prefer this tool over alternatives such as instagram_profile_search or instagram_details. Usage guidance is implied rather than 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?

With no annotations provided, the description carries full responsibility for behavioral disclosure. It adds value by mentioning credit cost (~1 credit), cached results being free, and no charge for failures. However, it does not reveal side effects, authorization needs, or detailed return behavior, leaving gaps.

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 extremely concise, consisting of two sentences that front-load the purpose and efficiently convey key details (credit cost, caching policy). No unnecessary words 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?

No output schema exists, so the description should explain what data the tool returns. It only vaguely mentions 'Profile info & stats,' which is insufficient. Given the complexity of Instagram profile data and the lack of structure, the description is incomplete.

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 both parameters (url and cache). The description adds no additional parameter-level meaning beyond what is in the schema, so the baseline score of 3 is appropriate.

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

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

The description clearly states it provides 'Profile info & stats for an Instagram account,' which is a specific purpose. However, it does not differentiate from similar sibling tools like instagram_basic_profile or instagram_details, leaving ambiguity about when to use this particular tool.

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?

No guidance is given on when to use this tool versus alternatives. The description lacks any context about prerequisites, selection criteria, or situations where this tool is preferred over similar Instagram profile tools.

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

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

No annotations are provided, so the description must disclose all behavioral traits. It mentions cost (~6 credits), caching (free cached results), and failure billing (never charged), but omits rate limits, authentication needs, or behavior for private profiles. This is minimal for a tool with zero annotation coverage.

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

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

The description is two concise sentences with no wasted words. The first sentence front-loads the purpose, and the second adds billing context. Every sentence earns its place.

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

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

With no output schema, the description should explain what the response contains (e.g., a list of posts with fields like caption, media, date). It lacks this information, and also omits pagination behavior beyond the cursor parameter. Completeness is insufficient for a tool with 4 parameters and moderate complexity.

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

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

Schema coverage is 100% with parameter descriptions already included. The description adds no new meaning about parameters beyond the schema, so a baseline score of 3 is appropriate.

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

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

The description clearly states 'Latest posts from an Instagram profile,' specifying the verb ('latest posts') and resource ('Instagram profile'). This distinguishes it from sibling tools like instagram_channel_reels or instagram_tagged_posts, which focus on different content types.

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 usage by stating it returns 'latest posts,' but does not explicitly contrast with siblings like instagram_tagged_posts or instagram_channel_reels. The schema's URL description includes a cross-platform warning, but no when-to-use vs alternatives 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?

With no annotations, the description carries the full burden of behavioral disclosure. It proactively mentions cost (~6 credits), free caching, no charge for failures, and pagination via nextCursor + hasMore — information beyond what the schema provides. This is exemplary transparency.

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

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

The description is a single, dense sentence that front-loads the main purpose and packs operational details (cost, cache, failures) efficiently. Every clause earns its place without unnecessary verbiage.

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

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

Given no output schema and no annotations, the description covers essential aspects: purpose, identifiers, pagination, cost, caching, and failure policy. It doesn't enumerate fields in each returned reel, but the pagination hint partially addresses return structure. Overall, it is sufficiently complete for a listing tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds minor context like 'cached results are free' but mostly repeats the url-or-userId relationship already in the schema. It does not meaningfully enhance parameter understanding beyond what the schema already documents.

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: 'Latest Reels from an Instagram profile' — a specific verb-resource pair. It also identifies the input forms (url or userId), which distinguishes it from other Instagram tools like posts or search by specifying 'from an Instagram profile.'

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

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

The description gives clear context for when to use the tool (when you need a profile's recent reels), but it doesn't explicitly mention alternatives or when not to use it. The clarity is sufficient to select it among siblings, though exclusions are 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?

With no annotations, the description bears full responsibility for behavioral disclosure. It reveals caching behavior (free if cached) and failure policy (never charged), which is helpful. However, it does not confirm read-only status, mention rate limits, or describe any side effects. The cost hint adds some transparency.

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

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

The description is very concise (one sentence) and front-loads the primary purpose. It efficiently communicates key behavioral aspects (cost, caching, failure policy). While it could be more structured with a clear verb, it is not verbose or wasteful.

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

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

Given the absence of an output schema and no annotations, the description should provide more contextual completeness. It omits what the return data looks like (e.g., structure of comments, pagination), lacks details on URL constraints beyond the schema, and does not explain the 'limit' parameter's impact on billing. The description feels incomplete for an agent to fully anticipate the tool's behavior.

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 parameters (url, cache, limit) are already well-documented in the schema. The description adds no additional semantic context beyond what the schema provides, meeting the baseline but not exceeding it.

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 the tool retrieves comments on an Instagram post or reel, specifying the resource (Instagram post/reel) and the action (comments). This distinguishes it from other Instagram tools like instagram_details or instagram_embed, though the phrasing is a noun phrase rather than a clear verb. The purpose is specific and unambiguous.

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

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

The description provides cost and caching details but offers no guidance on when to use this tool versus alternatives (e.g., other comment tools or Instagram-specific tools). There are no instructions on prerequisites, when not to use it, or how it compares to sibling tools like facebook_comments or instagram_embed.

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

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

With no annotations, the description bears full burden. It discloses caching behavior ('cached results are free') and cost ('Costs ~1 credit') and failure policy ('failures are never charged'). However, it omits rate limits, authentication requirements, and response structure, which are important for a tool with no output schema.

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

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

The description is two sentences and very concise, with no redundant information. It front-loads the main purpose. However, it could be more effectively structured by placing the pricing and caching info after the 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 simple tool with 2 parameters and no output schema, the description is fairly complete. It covers purpose, cost, and caching. Yet it fails to specify what 'details' includes (e.g., like count, comments count, caption), which is necessary for an agent to decide if this tool meets its needs.

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

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

Schema coverage is 100%, so the baseline is 3. The description does not add meaning beyond the schema; it mentions caching but the schema already explains the cache parameter fully. No additional insight into the url parameter is provided.

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

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

The description clearly states it provides 'Details for an Instagram post or reel,' which is a specific verb+resource. It distinguishes from sibling tools like instagram_comments (comments) and instagram_summarize (summarize). However, it does not enumerate what fields are included in 'details,' leaving some ambiguity.

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

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

No usage guidelines are provided. There is no indication of when to use this tool versus alternatives like instagram_embed or instagram_basic_profile. The description only offers pricing and caching info, not contextual guidance for selection.

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?

Discloses cost of 1 credit, caching behavior, and that failures are not charged. With no annotations, this adds transparency beyond the schema.

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

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

Two sentences, front-loaded with purpose, no redundant information. 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?

Does not describe return value format (just 'Embed HTML') or any output structure. With no output schema, more detail would be helpful for completeness.

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

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

Schema coverage is 100%, with detailed descriptions for both parameters. The tool description adds no further parameter clarification, meeting baseline expectation.

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

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

The description clearly states it returns embed HTML for Instagram posts, reels, or profiles, with cost and caching details. This distinguishes it from sibling tools that fetch raw data or details.

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?

No explicit guidance on when to use this tool vs alternatives. The schema includes a note about cross-platform URL prevention, but no overall 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?

With no annotations provided, the description carries the burden of disclosing behavioral traits. It adds useful operational context: 'Costs ~2 credits; cached results are free, failures are never charged.' However, it does not mention potential rate limits, response format, or what 'native grid' entails, leaving gaps for an agent expecting more detail.

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

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

The description is two sentences: the core purpose is front-loaded in the first sentence, and supplementary cost/caching behavior is in the second. No unnecessary words or repetition of schema 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?

For a read-only search tool with thorough parameter schemas, the description provides purpose, cost, and caching behavior. It lacks an explicit statement of output structure, but 'Search Instagram posts' implies a list of posts. The absence of an output schema is partially mitigated by the clear purpose and parameter descriptions.

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 fully describes all four parameters (100% coverage), so the baseline is 3. The description adds cross-parameter context by explaining cost implications: cached results (via cache=true) are free and failures are never charged, which clarifies the practical impact of the cache and limit parameters.

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

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

The description clearly states 'Search Instagram posts by hashtag (native grid)', using a specific verb and resource. The parenthetical 'native grid' helps distinguish this from other Instagram search tools like instagram_reels_search or instagram_profile_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 implies the primary use case ('Search Instagram posts by hashtag') but does not explicitly mention when to prefer this over alternatives such as instagram_tagged_posts or instagram_reels_search. There is no exclusion or alternative guidance, so usage is implied rather than 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?

With no annotations, the description partially carries the behavioral burden by disclosing cost (~1 credit), caching benefits (free cached results), and failure policy (never charged). It does not mention authentication requirements, rate limits, or behavior for profiles with no highlights, which would be expected for full transparency.

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

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

The description is compact, but it contains redundancy: 'Flat 1 credit' and 'Costs ~1 credit' convey the same information. Otherwise, it is front-loaded with the resource type and includes pricing details without excessive length.

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

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

There is no output schema, so the description's list of fields (id, title, cover, owner) partially explains the return value. It does not mention pagination, ordering, or how to distinguish empty results, but for a simple list-albums tool, this is adequate though not 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 provides 100% coverage for all three parameters (url, cache, userId), so the baseline is 3. The description adds no parameter-level detail, but it does not need to since the schema is complete.

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

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

The description identifies the tool as retrieving persistent Story Highlight albums for a public profile, listing key fields (id, title, cover, owner). This goes beyond the tool name and distinguishes it from profile-related siblings, though it lacks an explicit verb like 'get' or 'list'.

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 phrase 'for a public profile' implies when the tool is applicable, and the focus on highlights implies a use case. However, it does not explicitly guide against alternatives like instagram_highlights_details, leaving some ambiguity for the agent.

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

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

With no annotations, the description carries the behavioral disclosure burden. It provides valuable context on pricing (flat 1 credit, cached results free, failures never charged). It does not mention rate limits or error behavior for invalid IDs, but the cost and caching transparency is a positive.

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

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

The description is concise, front-loaded with the primary function, and includes cost details in a second sentence. Every sentence earns its place 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?

For a straightforward detail retrieval tool, the description fully captures what is returned (media URLs, type, takenAt) and the cost model. Given the absence of an output schema, this is sufficient for an agent to understand the tool's behavior and integr

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 well-documented. The description adds context about caching and costs but does not explain parameter semantics beyond what the schema already provides, keeping the baseline score 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 clearly states what the tool does: returns items inside one Instagram Story Highlight album, listing media URLs, type, and takenAt. It distinguishes from siblings like instagram_highlights by specifying 'inside one Highlight album', making the purpose unambiguous.

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

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

Usage is implied: use this when you need items from a specific highlight. However, there is no explicit mention of when to use this tool versus alternatives like instagram_highlights for the list of highlights, nor any exclusions or prerequisites.

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

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

With no annotations provided, the description discloses pricing (flat 1 credit), caching (24h cache free), and failure policy (never charged), which are valuable beyond the schema. It does not cover rate limits or no-match behavior, but the core operational traits are disclosed.

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

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

Three concise sentences with the primary purpose first. Minor redundancy between 'Flat 1 credit' and 'Costs ~1 credit', but overall efficient and readable.

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

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

For a simple two-parameter, no-output-schema tool, the description covers purpose, return contents, pricing, caching, and exclusions. It lacks explicit differentiation from similar Instagram profile tools, but is sufficient for selection.

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

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

Schema coverage is 100%, so baseline is 3. The description enriches the q parameter by specifying it accepts a brand or @handle, and clarifies cache behavior by noting cached results are free, adding meaning beyond the generic schema descriptions.

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

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

The description clearly states the tool resolves a brand or @handle to a single Instagram profile and lists the output fields (id, bio, links, stats), explicitly distinguishing it from niche discovery. While it doesn't name every sibling profile tool, the verb and scope make the 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?

Provides clear context: it's for resolving specific brands/handles, not niche discovery, and mentions credit cost and caching behavior to guide when to use cache. However, it doesn't explicitly name alternative tools for comparison, so it stops short of full 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?

Given the absence of annotations, the description adds valuable behavioral context: cost (~28 credits), caching behavior (cached results free, failures never charged). It does not detail response structure or auth requirements, but the disclosed cost and cache policies are meaningful and go beyond the schema.

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

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

The description is a single, information-dense sentence that covers the core purpose, key output fields, and cost/caching. It is front-loaded and contains no redundant wording.

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

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

There is no output schema, so the description should compensate by explaining return values. It mentions some fields (isTrendingInClips, trendRank, music{}) but does not fully describe the response structure or pagination behavior. The schema covers parameters, and cost/caching is mentioned, but the description could be richer about expected output.

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

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

The schema already describes all three parameters (audio_id, cache, limit) with 100% coverage, so the baseline is 3. The description does not add any parameter-specific guidance beyond what the schema provides, such as examples or format details.

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 retrieves reels by audio ID, and specifies notable output fields (isTrendingInClips, trendRank, music{}). This distinguishes it from sibling tools like instagram_reels_search or instagram_trending_reels by its unique audio-based lookup.

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

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

The description implies the tool is for fetching reels associated with a specific audio ID, but it does not explicitly state when to use it over alternatives or mention any exclusions. The usage context is clear from the name and schema, but no direct comparison to other tools is provided.

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

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

With no annotations provided, the description carries the full burden of disclosing behavioral traits. It adds valuable context: flat 2 credits, cached results are free, and failures are never charged. The term 'Native' hints at official API usage. However, it does not mention response structure, pagination, or potential rate limits, but the pricing/caching disclosure is a meaningful addition beyond the schema.

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

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

Two sentences, front-loaded with the tool's purpose, followed by cost and caching details. However, 'Flat 2 credits' and 'Costs ~2 credits' are redundant, and the dash-separated phrase is telegraphic. Overall, it's concise and structured well, with a minor redundancy.

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

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

Without an output schema, the description should provide more context about return values, but it does list some output fields. It also covers cost and caching, which is helpful. However, it lacks details on pagination, error handling, and how the cache parameter works in practice. For a 4-parameter search tool, this is adequate but with clear gaps.

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

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

Schema description coverage is 100%, so the baseline is 3. The description lists 'datePosted' and some output fields, but does not explain the parameters more deeply than the schema already does. It adds no specific syntax, examples, or clarifications for q, cache, or limit, so it meets the baseline without going beyond.

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 does a 'Native Instagram Reels hashtag search' and lists key returned fields (views/plays, author verified/followers, datePosted). The verb 'search' plus resource 'Instagram Reels' and qualifier 'hashtag' distinguish it from many sibling tools like instagram_profile_search or instagram_trending_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?

The description implies usage for searching Instagram Reels by hashtag, but it does not explicitly state when to use this tool over alternatives such as instagram_hashtag_search or instagram_reels_by_audio_id. No exclusions or alternative recommendations are provided, so it meets the baseline for implied usage but lacks direct 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?

No annotations are provided, so the description carries the full burden. It discloses cost and caching behavior but does not describe the summary format, length, or other behavioral traits. The transparency is adequate but not 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?

The description is extremely concise—two sentences plus a schema note—with no wasted text. Every 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 the tool's simplicity (3 parameters, no output schema), the description covers purpose, cost, caching, and URL constraints. It does not describe return format, but for a summary tool, the essential information is present.

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

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

Schema coverage is 100%, with each parameter well-described in the schema. The description adds value by noting that the URL must match the tool's platform, which is not implied by the schema alone.

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 'AI summary of an Instagram Reel', using a specific verb and resource. This distinguishes it from sibling tools like facebook_summarize, tiktok_summarize, etc.

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 cost and caching guidance ('Costs ~4 credits; cached results are free, failures are never charged') and the input schema includes a clear note about cross-platform URLs. However, it lacks explicit when-to-use vs alternatives like other summarize tools.

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

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

With no annotations, the description carries the full burden and discloses useful non-obvious behaviors: ~1 credit cost, free cached results, no charge on failures, and cursor pagination. It does not mention authentication, rate limits, or exact response shape, but the billing/caching transparency exceeds typical descriptions.

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

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

The description is two concise sentences, front-loaded with the purpose and returned fields, followed by billing and caching details. Every phrase contributes useful information with no redundancy 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?

For a straightforward list endpoint with no output schema and no annotations, the description covers the core purpose, key returned fields, pagination mechanics, and cost model. It is somewhat incomplete due to missing explicit sibling differentiation and a precise response structure, but it is sufficient for a simple tool.

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

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

The input schema already covers 100% of parameters with detailed descriptions, so the baseline is 3. The description adds credit and caching context that gives meaning to the cache and limit parameters, but it does not introduce new syntax or parameter-specific details beyond what the schema provides.

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

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

The description identifies retrieval of a profile's tagged posts and lists returned fields (author id, views, hashtags/mentions), distinguishing it from siblings like instagram_channel_posts. However, it lacks an explicit action verb such as 'get' or 'list', relying on the noun phrase 'Tagged posts' to imply the operation.

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

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

No guidance is provided on when to use this tool versus alternatives like instagram_channel_posts or instagram_profile_posts. The description only mentions operational details (credit cost, caching, pagination) and does not explain when tagged posts are appropriate to fetch.

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

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

With no annotations, the description carries the full burden. It discloses cost policy (2 credits, free cache, no charge on failures) but omits critical behavioral details: what the response contains (e.g., plain text, timestamps), error handling, auth requirements, or concurrency limits. This is insufficient for an agent to fully understand the tool's 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 two sentences: the first clearly defines the tool, the second adds relevant cost and caching context. Every sentence earns its place with no fluff or repetition. It is front-loaded and easy to scan.

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

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

Given the lack of output schema and annotations, the description should provide more context: what the transcript looks like (e.g., plain text, JSON with timestamps), prerequisites (must be public reel), and error scenarios. The current description is incomplete for an agent to reliably invoke and process results.

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

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

Schema coverage is 100% with clear descriptions for all three parameters (url, cache, language). The description adds no new information about parameters beyond what the schema already provides. Baseline score of 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 clearly states the tool returns the transcript of an Instagram Reel, using a specific verb-resource combination. It distinguishes itself from sibling transcript tools by explicitly mentioning 'Instagram Reel', so there is no confusion with TikTok, YouTube, or other platform transcripts.

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

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

The description does not explicitly state when to use this tool vs alternatives. However, the input schema's URL parameter description warns against cross-platform URLs, which implies use only for Instagram Reels. The cost and caching info is provided but not as a usage guideline. No explicit when-not-to-use or alternative recommendations.

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