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

Beyond the readOnlyHint annotation, the description discloses pagination behavior (next_page presence/absence), the 10-page cap, and per-request cost. These are important operational traits that help an agent plan multi-page retrieval and understand limits. No contradiction with annotations.

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

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

Three concise sentences with the core purpose front-loaded, followed by pagination mechanics and cost. There is no filler, and every sentence contributes essential 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?

With no output schema, the description covers pagination and caps but does not enumerate the fields of a review (e.g., rating, text, author). However, correct invocation is fully covered by the schema and pagination guidance, so the missing return-structure details are a minor gap.

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

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

Input schema has 100% parameter descriptions for page, app_id, and country, so the baseline is 3. The description adds no additional meaning to these parameters, instead focusing on response-level pagination, which is not parameter semantics.

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

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

The description clearly states it returns 'one page of the most recent customer reviews of an app', specifying both the resource (reviews) and the scope (one page). It is distinct from appstore_search, the only related sibling, and there is no ambiguity about what this tool does.

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

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

The description provides explicit pagination guidance: use next_page when present, it is absent on the last page, Apple caps at 10 pages, and each page costs one request. It does not explicitly name alternatives, but no alternative review tool exists, so this is sufficient.

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

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

Annotations already declare readOnlyHint=true, so the description is not responsible for that safety signal. It adds behavioral context by listing the returned fields and by noting the id's role as a bridge to appstore_reviews SEARCHING. No contradictions with annotations.

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

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

Two sentences, first states the action and result, second gives the follow-up instruction. Every word earns its place; nothing is duplicated from the schema.

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

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

Without an output schema, the description documents the return fields and the external workflow. Parameters are self-explanatory via schema. The description is complete enough for an agent to call and interpret the result correctly.

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

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

The schema describes all three parameters with 100% coverage (term, limit, country). The description adds no parameter-level meaning beyond simply confirming the search action. Since the schema fully carries the parameter semantics, the descriptive baseline is 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 names a specific action ('Searches the Apple App Store'), the resource, and the exact output fields. It also singles out the relevant sibling tool (appstore_reviews) for follow-up, making its purpose unambiguous and distinct from every sibling.

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

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

It gives a clear directive to use the returned id with appstore_reviews, which implies the intended workflow. There are no competing search tools among the siblings, so explicit 'when not to use' exclusions are not needed. It could have said more about when to prefer this over other discovery routes, but the cross-tool instruction is valuable.

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

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

Annotations already mark readOnlyHint=true, so the read-only nature is covered. The description adds the pagination contract (next_cursor/has_more) that is not in annotations, and there is no contradiction. It could mention error/rate-limit behavior, but given the annotations, this is sufficient.

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

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

Two sentences with no filler. The primary purpose is stated first, and the pagination instruction follows naturally. 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?

The tool is simple with 3 parameters fully documented in the schema. The description confirms the return includes engagement counts and introduces has_more, giving a clear mental model of the response. No output schema exists, but the description covers the essentials for correct usage.

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 each parameter is documented. The description adds the relational meaning of cursor (the next_cursor from the previous page) and the loop condition (has_more), which enriches the schema's static definitions.

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 page of a Bluesky profile's posts with engagement counts, which is specific and distinguishes it from the only sibling (bluesky_profile) that provides profile metadata. It also immediately conveys the pagination nature.

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

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

The description gives explicit pagination instructions: 'Pass next_cursor back as cursor while has_more is true.' It doesn't explicitly compare to alternatives, but there is no competing Bluesky posts tool among the siblings, and the usage context is clear from the purpose.

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

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

The annotations already declare readOnlyHint and openWorldHint, so the description doesn't need to restate safety. It adds meaningful context by saying the profile is public, listing the exact fields returned, and positioning the tool as an existence check. It doesn't cover error behavior or rate limits, but those are minor given the 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?

Two short sentences with no filler. The first sentence front-loads the return fields, and the second provides the primary use case and sibling routing.

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 one-parameter, read-only profile lookup with no output schema, the description covers the return fields and the intended use context. The handle parameter is fully documented in the schema, so nothing an agent needs to invoke the tool correctly is missing.

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

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

The schema already documents the only parameter, handle, with a format description and an example, so the description adds no new parameter semantics. With 100% schema description coverage, 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 identifies a public Bluesky profile lookup and enumerates the returned fields (display name, description, avatar, banner, counts), so an agent knows what resource is involved. It distinguishes itself from bluesky_posts by framing this as the existence-check/profile tool. It lacks an explicit action verb like 'get' or 'fetch', which keeps it just shy of 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?

It explicitly says to use this tool first to check whether a handle exists before calling bluesky_posts. This names the relevant alternative and gives a clear ordering rule. No other guidance is needed for a single-purpose profile lookup.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds the pagination behavior (one page per call, next_page/has_more contract) and the per-request cost, which are not in the annotations. It doesn't describe rate limits or error cases, but for a read-only paginated list this is solid.

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 filler. The core purpose is in the first sentence, and the pagination instruction is in the second. 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?

For a simple read-only paginated list with 100% schema coverage and readOnlyHint/openWorldHint annotations, the description is nearly complete. It explains the pagination loop and cost. It doesn't mention what fields each follower object contains, but there is no output schema and the tool is simple enough that an agent can infer the shape from the GitHub API 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 schema already documents all three parameters (handle, page, limit). The description adds the pagination contract (next_page, has_more) which gives page/limit more meaning, but it doesn't add detail beyond what the schema provides for handle. 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 states a specific verb and resource: 'One page of the accounts following a GitHub user.' This clearly distinguishes it from the sibling github_following (accounts a user follows) and github_profile. The pagination qualifier is front-loaded.

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 tells the agent when to use it and how to paginate: 'Use next_page while has_more is true; each page costs one request.' This is actionable guidance that also implies the alternative (stop after has_more is false) and the cost model.

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

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

The readOnlyHint and openWorldHint annotations already cover the safety profile, and the description adds meaningful behavioral context beyond them: results are served one page at a time, pagination is driven by next_page and has_more, and each request consumes one page/call. This cost and iteration behavior is not present in the annotations.

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

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

The description is two sentences and both are necessary: the first defines what the tool returns, and the second gives the crucial pagination rule and request cost. There is no filler or redundancy.

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

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

For a simple read-only paginated endpoint, this is complete: it explains the one-page result, how to advance to the next page, when to stop, and the per-request cost. The schema covers all parameters and the annotations cover safety, so an agent has enough information to invoke it correctly even without an 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%, so handle, page, and limit are already documented in the schema. The description adds some useful context about how the result's next_page relates to pagination, but it does not add new meaning to the individual parameters 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 states a clear verb and resource: it returns one page of the accounts a GitHub user follows. This directly distinguishes it from the sibling github_followers, which is the reverse relationship, and the title adds the pagination 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?

It gives explicit pagination usage: use next_page while has_more is true and notes that each page costs one request. It does not explicitly name alternatives or say when not to use this tool, but the clear 'follows' wording makes the context understandable without that exclusion.

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

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

The annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds value by noting that the tool can be used to confirm handle existence, implying behavior on invalid handles, and it lists the returned fields, giving context beyond the annotations.

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

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

Two concise sentences with no fluff. The first sentence front-loads the return contents, and the second gives the usage directive. Every word earns its place, and the key guidance appears early.

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 (one param), read-only, and the description covers what it returns and when to use it. It doesn't specify the exact return format, but since there is no output schema and the fields are listed, an agent can call it correctly. The only minor gap is not stating the exact behavior for a non-existent handle, but the existence-check phrasing covers that implicitly.

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 the single parameter 'handle' with an example ('torvalds') and coverage is 100%. The description does not add any additional semantic information about the parameter itself, so it relies on the schema, matching the baseline for high 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 explicitly names the resource ('Public GitHub user profile') and lists the specific fields it returns (name, bio, company, location, blog, counts, creation date), clearly distinguishing it from sibling tools like github_followers or github_repositories. The phrase 'confirm a handle exists' also clarifies its role as a lookup 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?

It gives an explicit directive: 'Use this first to confirm a handle exists before calling the other github_* tools.' This tells the agent exactly when to invoke this tool and implies it should precede other GitHub tools, effectively guiding tool selection among siblings.

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

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

Annotations already declare readOnlyHint and openWorldHint, which cover safety and dynamic data. The description adds the pagination behavior, specifically that has_more is returned and that each page is a separate request, which is beyond the annotations and very useful for agents.

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 key information (what it returns) and then gives the most critical usage instruction (pagination and cost). 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?

Given this is a paginated list tool with clear schema and annotations, the description covers the essential usage pattern. It doesn't describe the exact structure of the results (e.g., whether it includes an array of repos), but that's not required since there's no output schema and the description mentions the fields. The pagination logic and cost are the key missing pieces, which are covered.

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 with detailed descriptions for each parameter (page, limit, handle). The description doesn't add new semantics beyond reinforcing the next_page usage, which is already implied by the schema's page parameter description. 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 one page of a GitHub user's public repositories with specific fields (stars, forks, language, description), distinguishing it from sibling tools like github_profile, github_followers, etc. However, it doesn't explicitly differentiate from github_search_repositories, which is a different search target, so a slight deduction.

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

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

The description explicitly instructs when to use next_page while has_more is true, and notes that each page costs a request, which is crucial for cost management. It implicitly routes to the correct context by specifying 'user's public repositories' as opposed to search or trending 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?

Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds valuable behavioral context: it clarifies that only one page is returned per call and that pagination requires explicit next_page usage, each costing a request. This goes beyond the annotations and helps the agent manage API usage effectively. It doesn't cover rate limits or response structure, but the provided details are meaningful.

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 zero waste. The purpose is front-loaded, and the pagination guidance is concise and actionable. Every word earns its place; no redundant phrasing 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 search tool with pagination and no output schema, the description covers the essential operational details: purpose, search syntax, pagination flow, and per-page cost. It does not describe the fields returned in results, but this may be acceptable given the absence of an output schema and the tool's read-only nature. The lack of explicit rate limits is a minor gap, but overall the tool is adequately specified for an agent to call it correctly.

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

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

Schema description coverage is 100%, so the input schema already documents all three parameters (q, page, limit) with their constraints and defaults. The description does not add extra semantic meaning beyond what the schema provides; it merely reiterates pagination hints (e.g., 'use next_page') which are already implied by the page parameter description. Since the schema is comprehensive, 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 the verb 'searches', the resource 'GitHub repositories', and the specific capability 'using GitHub search syntax'. It also mentions 'returns one page of results', which distinguishes it from listing tools like github_repositories and github_trending. The title reinforces the pagination aspect, making the tool's purpose unambiguous.

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

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

The description provides explicit pagination instructions: 'Use next_page while has_more is true; each page costs one request.' This tells the agent exactly how to iterate through results. However, it does not explicitly contrast this tool with sibling search tools or state when NOT to use it (e.g., when you need a user's repositories). The guidance is strong for pagination but lacks explicit alternative selection cues.

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

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

Annotations already declare readOnlyHint and openWorldHint, covering the safety profile. The description adds genuinely useful behavioral context beyond those hints: the tool is not paginated and returns the full requested list in a single call. This helps the agent understand response behavior without needing to call or probe.

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 with no fluff. The core purpose is front-loaded, and the pagination caveat and alternative tool are given in the second sentence, making the most important operational detail prominent.

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-only list tool, this description is complete: all parameters are documented in the schema, annotations cover safety, and the description explains the non-paginated behavior and when to switch to a paginated alternative. No output schema exists, but the description appropriately identifies the result as a full list of trending repositories.

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 limit, since, and language are already fully documented. The description reinforces the daily/weekly/monthly window and single-language restriction, but does not add meaning beyond what the schema already provides.

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

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

The description states a specific purpose: returning currently trending GitHub repositories with optional time window and language filtering. It also distinguishes this tool from github_search_repositories by noting the non-paginated behavior, so an agent can tell them apart.

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

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

It explicitly says when NOT to use this tool: when pagination is needed, use github_search_repositories instead. This gives clear routing guidance relative to a closely related sibling.

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

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

Annotations already declare readOnlyHint=true, so the tool is known safe. The description adds useful behavioral context beyond annotations: it discloses that results are paginated, that next_page and has_more exist in the output, that each page costs a request, and that ordering is newest-first. This is valuable extra behavioral information, though it does not address error handling or rate limits.

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 with zero waste: the first front-loads the core purpose and ordering; the second gives essential pagination mechanics. Every word earns its place, and the description is appropriately sized for a simple paginated list 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?

The tool is simple (3 params, 1 required) and the description covers purpose, ordering, pagination, and request cost. Given there is no output schema, the mention of next_page and has_more partially compensates by revealing output shape. Minor gaps remain (e.g., behavior for unknown usernames, empty results, or error conditions), but these are not critical for correct invocation.

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

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

Schema description coverage is 100%, so the schema already documents all parameters with details (e.g., page uses next_page from previous result, limit range 1-50). The description does not add meaning beyond the schema—it references next_page/has_more which are output fields, not parameter semantics. Baseline of 3 is appropriate.

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

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

The description states a specific verb+resource: it returns one page of comments posted by a given Hacker News user, ordered newest first. This clearly distinguishes it from siblings like hackernews_submissions (user posts) and hackernews_user (profile), leaving no ambiguity about what data is returned.

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 pagination usage: 'Use next_page while has_more is true; each page costs one request.' It also implies when to use it (for comments, not submissions) by the resource wording. However, it does not explicitly name alternative tools or exclusions, leaving the distinction to be inferred from sibling names 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?

The annotations declare readOnlyHint=true and openWorldHint=true, so the safety profile is already covered. The description adds useful behavioral context: each call returns a single page, pagination depends on next_page/has_more, and each page consumes one request. This goes beyond the annotations without contradicting them.

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

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

The description is two sentences long, front-loads the core purpose and output fields, then gives concise pagination guidance. Every sentence contributes meaningful information with no filler or repetition.

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

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

For a simple paginated read-only feed tool, the description covers what the tool returns, which feed types are available, and how to page through results. The absence of an output schema is mitigated by mentioning the key returned fields and pagination contract, so an agent has enough to call it correctly.

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

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

The input schema already describes all three parameters with 100% coverage, including defaults, range, and enum values. The description mostly restates the feed enum and adds pagination context, which is helpful but does not significantly deepen parameter semantics 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 states it returns 'one page of a Hacker News feed' and enumerates the exact feed types (top, new, best, ask, show, job) and the specific fields included (title, author, points, comment count, URL). This clearly differentiates it from sibling tools like hackernews_item, hackernews_search, and hackernews_user.

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

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

The description gives explicit usage guidance for pagination: 'Use next_page while has_more is true; each page costs one request.' This tells the agent exactly how to iterate through results. It does not explicitly compare to alternatives, but the context of the sibling list and feed-type enumeration makes the intended use clear.

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

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

Annotations already declare readOnlyHint and openWorldHint. The description adds meaningful context beyond that: the full nested comment tree and the warning that popular threads can produce very large output, which helps an agent anticipate cost and response size.

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 with no filler. The first sentence states exactly what the tool returns; the second provides usage guidance. Information is front-loaded and 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 single-parameter read tool with no output schema, the description sufficiently explains the return value (full nested comment tree), the item types covered, and the appropriate use case. No critical information is missing for an agent to invoke it correctly.

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

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

Schema coverage is 100% and the single id parameter is already well documented in the schema with type, range, and an example. The description does not need to add parameter details, so baseline 3 is appropriate.

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

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

The description clearly states it returns a single Hacker News item (story, comment, job, or poll) with its full nested comment tree. This distinguishes it from sibling overview tools like hackernews_feed and hackernews_search by emphasizing the single-item, deeply nested 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?

Explicitly tells the agent to prefer hackernews_search or hackernews_feed for overviews and to call this only for a specific known item. This is direct, actionable guidance on when to use the tool versus alternatives.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds beyond annotations by revealing pagination mechanics (next_page, has_more), the single-page result boundary, and the request-cost implication ('each page costs one request'). No contradiction with annotations.

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

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

Two tight sentences with no filler. The primary action is front-loaded, and the essential pagination behavior follows directly. 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?

The description covers the core search action, pagination usage, and request cost. Given the simple parameter set and read-only annotations, no critical information is missing for an agent to invoke the tool correctly. A slight gap is the absence of any description of the result format, but no output schema exists and the pagination hints (next_page, has_more) indirectly signal the response shape.

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 q, page, and limit fully. The description's mention of next_page and has_more is useful context for the page parameter but adds no new meaning to the parameters themselves; it aligns with baseline for fully-covered schemas.

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

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

States a specific verb ('searches'), a clear resource ('Hacker News stories'), and a defined scope ('by text') plus a pagination behavior ('returns one page of results'). This clearly distinguishes it from sibling hackernews_* tools like feed, item, user, submissions, and comments, which serve different resources or actions.

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 contextual usage guidance for pagination: 'Use next_page while has_more is true; each page costs one request.' This tells the agent how to iterate through results. It does not explicitly contrast with alternatives like hackernews_feed, but the search-by-text scope implies the right condition 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?

Annotations already declare readOnlyHint=true and openWorldHint=true, and the description adds meaningful behavioral context: it returns only one page, is newest-first, and pagination requires one request per page. This goes beyond the structured annotations and explains the request-cost implication.

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 deliver the core purpose and paging behavior with no filler. The most important constraint (one page, newest first) is front-loaded, and the pagination instruction is directly actionable.

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 paginated list tool with read-only annotationschers and well-documented parameters, the description provides the essential behavioral contract. It does not explain the result item shape or error handling, but the paging instructions and request-cost warning make it sufficiently complete for an agent to call it correctly.

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

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

The input schema already documents all three parameters with 100% coverage, so the description does not need to repeat them. It slightly reinforces how page relates to next_page, but it does not add significant semantic detail 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 states a specific resource ('stories a Hacker News user submitted') and a clear ordering ('newest first'), which distinguishes it from sibling tools like hackernews_feed or hackernews_user. The verb 'submitted' makes the operation unambiguous, and the paginated scope 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 gives clear pagination guidance: use next_page while has_more is true and notes each page costs one request. It does not explicitly name alternatives or state when not to use this tool, but the context for iterative fetching is well explained.

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

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

Annotations already declare the operation read-only and open-world, and the description adds useful context by enumerating the returned fields and warning that it does not list posts. It does not cover edge cases like nonexistent usernames or rate limits, but the safety profile is already carried by 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?

Two short sentences convey the tool's purpose and direct the agent to the appropriate sibling tools. The distinguishing information is front-loaded, 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 one-parameter, read-only profile lookup, the description is complete: it states what data is returned and when to use an alternative tool instead. No output schema exists, but the listed fields sufficiently describe the return value for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, and the only parameter, username, is documented with a concrete example ('e.g. pg') in the schema. The tool description adds no additional parameter-level guidance, 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 specifies the resource and the fields returned (karma, about text, creation date, submission count), so an agent can infer this is a profile metadata lookup. It lacks an explicit action verb like 'get' or 'fetch', but the resource and data are specific. The second sentence also differentiates it from the submission/comment listing siblings.

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

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

The description explicitly directs the agent to use hackernews_submissions or hackernews_comments when the goal is to list what a user posted. This is a clear when-not condition, and the opening sentence makes the intended use case (accessing profile metadata) unambiguous.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the read-only and open-world nature is covered. The description adds conditional behavior: fields are null when not public, and data only appears when the account exposes it. This is valuable context beyond the annotations.

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

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

The description is a single, information-dense sentence with zero fluff. It front-loads the resource and enumerates the exact fields returned, making it efficient for an agent to parse.

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

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

For a one-parameter read-only tool with no output schema, the description adequately conveys return value (defined fields) and edge behavior (null when not public). It could mention error cases (e.g., nonexistent username) but that is not critical for typical usage. Overall, it provides sufficient context to invoke correctly.

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

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

The schema for the single username parameter has a clear description (username without @, example provided) and 100% coverage. The tool description adds no additional parameter-specific semantics, 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 clearly states the tool retrieves public business contact details (email, phone, address, external URL) for an Instagram account. This is a distinct resource from sibling tools like instagram_profile (profile info) or instagram_latest_posts (posts), so it is easily distinguishable.

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 – obtain contact details for an Instagram account – but does not explicitly state when to use this tool instead of siblings, nor does it mention any exclusions or alternatives. The purpose is self-evident, but there is no explicit routing 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?

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds valuable behavioral context: it discloses the response structure (assets array, resolution, expiry, assets[0] as best), which is not present in the schema or annotations. This goes beyond what structured fields provide.

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

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

Two compact sentences with zero redundancy. The first sentence front-loads the core purpose (downloadable assets, resolution, expiry), and the second sentence provides the key response-structure hint (assets[0] best). Every word contributes.

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

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

With one well-documented parameter, no output schema, and read-only annotations, the description covers the essential return behavior: asset types, resolution, expiry, and the ordering guarantee. It is slightly light on error cases or additional fields, but for a simple lookup tool it is sufficiently complete for correct invocation.

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

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

Schema description coverage is 100%, so the shortcode parameter is already well-documented with format and example. The tool description does not add additional parameter semantics, only indirectly references the resource type (post/reel/carousel). Baseline 3 is appropriate when the schema carries the load.

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

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

The description clearly identifies the tool's function: retrieving download URLs for all assets (videos, images, thumbnails) from Instagram posts, reels, or carousels, including resolution and expiry. It goes beyond the title by specifying the asset types and the 'assets[0] is the best primary asset' detail.

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 download URLs are needed (by focusing on downloadable assets), but it does not explicitly state when to use this tool versus alternatives like instagram_media or instagram_reel. There is no exclusionary guidance or naming of sibling tools, leaving the agent to infer the choice from 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?

Annotations already declare readOnlyHint=true and openWorldHint=true, so the agent knows this is a safe read operation. The description adds that the result contains stories with media URLs, which is useful output context. It does not mention pagination, rate limits, or any other behavioral constraints, so it provides only moderate additional transparency beyond the annotations.

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

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

The description is one short sentence that front-loads the core purpose ('The stories inside one Instagram highlight, with media URLs') and then gives the id source. No filler or redundancy.

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

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

For a single-parameter read-only tool with no output schema, the description adequately covers what the tool returns and how to obtain the id. It does omit details like error behavior or media URL format, but these are not essential for correct invocation. Given the tool's low complexity, it is sufficiently 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 has 100% description coverage, with the parameter description already explaining that highlight_id should come from instagram_highlights and giving an example. The tool description only repeats this relationship ('Get the id from instagram_highlights') without adding new semantic detail. Therefore 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 states a specific action: retrieving the stories inside one Instagram highlight, and notes that it includes media URLs. It also directs the user to obtain the highlight_id from instagram_highlights, which disambiguates it from the sibling tool that lists highlights. This clearly identifies the resource and 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 tells the agent where to get the required id ('Get the id from instagram_highlights'), establishing a prerequisite workflow. However, it does not explicitly state when not to use this tool or compare it with other media retrieval tools like instagram_media_by_id or instagram_reel. The usage context is implied rather than fully elaborated.

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 readOnlyHint and openWorldHint annotations already present, the description's addition of the returned fields (ids, titles, covers) adds useful context. It does not contradict annotations, and for a simple read-only listing tool, this level of disclosure is sufficient.

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

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

The description is two sentences with no redundant wording. The purpose is front-loaded, and the pointer to the sibling tool is placed immediately after, making it efficient 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?

For a tool with one parameter, no output schema, and annotations covering safety, the description provides enough information to call it correctly. It specifies what is returned and how to proceed to the next level, so no critical information is missing.

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

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

The only parameter, username, is fully documented in the schema with an example, and the description does not add further semantic details. Since schema coverage is 100%, the baseline of 3 is appropriate; the description simply reinforces the required input without enriching 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 the tool lists an Instagram account's story highlights with their ids, titles, and covers. It uses a specific verb 'List' and resource 'Instagram account's story highlights', and the distinction from the sibling instagram_highlight is obvious because that tool is explicitly named for getting items from a highlight.

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 directly instructs the agent to use instagram_highlight with an id to get its items, which clarifies when to use this tool versus its sibling. It effectively communicates the relationship and the correct next step without ambiguity.

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

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

Annotations already provide readOnlyHint and openWorldHint, and the description adds that no Instagram call is made yet the operation still counts as one API request. This is useful context for rate-limit and cost awareness beyond what annotations convey.

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

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

Two sentences with the core operation front-loaded, followed by a concise usage note. No filler or redundant explanation.

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 one-parameter converter, the description, schema, and annotations together cover input, safety, behavior, and usage. Since there is no output schema, an explicit note about the exact return value shape would make it fully complete.

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

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

Schema coverage is 100% and the schema already documents media_id as a numeric string with an example. The description repeats 'numeric' but adds no meaningful parameter-level detail beyond the schema.

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

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

States a specific conversion from a numeric media_id into the shortcode used in post URLs, and names the downstream tools that require this form. This clearly differentiates it from the reverse tool and other Instagram tools in the sibling 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?

Explicitly instructs when to use this tool: before instagram_media or instagram_download, which take a shortcode rather than a numeric id. This gives the agent a direct decision rule for choosing it over 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?

Annotations include readOnlyHint=true and openWorldHint=true, so the agent knows it's a safe read operation. The description adds the 'first page only' limitation, which is behavioral context. But it doesn't mention pagination, rate limits, or that the output may vary in structure. With annotations already covering safety, a 3 is reasonable.

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: one states the core function and scope, the second routes to an alternative. No wasted words, front-loaded with the key information. Exemplary conciseness.

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

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

For a single-parameter read tool with a clear purpose and sibling alternative, the description is largely complete. It lacks details on output format, but with no output schema this is a minor gap. The specific sibling guidance helps agents choose correctly. Overall, adequate for its 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 description coverage is 100%: the 'username' property already says 'Instagram username without @, e.g. nasa'. The description adds no extra meaning beyond what the schema provides. 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 states a specific verb and resource ('most recent posts of an Instagram account'), and scopes it to 'first page only'. It does not explicitly name the sibling 'instagram_posts' in the description, but the sibling exists and the description hints at an alternative for older posts. Purpose is clear, but differentiation from 'instagram_posts' relies on the sibling list rather 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?

It explicitly says 'Use instagram_posts instead when you need older posts', providing a clear alternative and condition. No exclusions are given, but the primary usage is obvious from the description. This is strong guidance but could be improved by also noting that other social platforms have separate 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?

Annotations already declare readOnlyHint=true and openWorldHint=true, so the description does not need to restate safety. It adds useful behavioral context by listing the returned content categories and clarifying that the tool handles post, video, and carousel forms.

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 with no filler. The main purpose and content scope are front-loaded, and the alternative-tool guidance is placed in the second sentence 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?

For a single-parameter read-only tool, the description is complete: input, resource scope, return content, and sibling routing are all covered. No output schema exists, but the description lists the key returned fields sufficiently 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?

The schema already fully documents the single shortcode parameter with an example, so the description adds little beyond restating the source. With 100% schema coverage, the baseline 3 is appropriate.

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

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

The description states exactly what the tool returns: details of one Instagram post, video, or carousel, including caption, likes, comments, and media URLs. It clearly identifies the shortcode as the input and distinguishes itself from the instagram_media_by_id sibling.

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

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

The description explicitly names instagram_media_by_id as the alternative and gives the condition for using it: when the numeric media id and owner's username are already available. This leaves no ambiguity about when to choose this tool.

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

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

Annotations already declare readOnlyHint and openWorldHint, so safety is covered. The description adds concrete behavioral context by enumerating the returned fields (caption, likes, comments, media URLs) and clarifying the required identifier form, which partially substitutes for the missing 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?

Two sentences, no filler, with the core behavior stated first and the routing guidance second. 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 simple two-parameter read tool, the description fully covers what the tool does, what it returns, which identifier to pass, and which sibling to use instead when the identifier type differs. No output schema is needed here because the description already names the key return 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 coverage is 100%, with both username and media_id already documented with examples. The description reinforces that media_id is numeric and username is the owner, but adds little beyond the schema's own 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 states the tool returns details of one Instagram post (caption, likes, comments, media URLs) identified by owner and numeric media id. It also distinguishes itself from instagram_media by explicitly calling out the numeric-id lookup path versus the shortcode path.

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

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

The description gives an explicit when-to-use alternative: use instagram_media instead when only the shortcode is available. This tells an agent exactly which tool to pick based on available identifier type.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, covering safety and external mutability. The description adds meaningful behavioral detail beyond annotations: each page costs one request and the cursor/has_more pagination lifecycle. No contradiction with the annotations.

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

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

Three short sentences with no wasted text. The core purpose is front-loaded, followed by the pagination contract and cost note, which are the most important 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?

For a paginated read-only tool with fully documented parameters, the description covers the key non-obvious aspects: pagination via next_cursor, the has_more condition, and per-page cost. No output schema exists, but the description gives enough operational context to call and iterate 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% for username, count, and cursor. The description references cursor and next_cursor in a pagination workflow but does not add meaning beyond what the schema already documents, so the baseline of 3 is appropriate.

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

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

The description clearly states it returns 'one page of an Instagram account's post history', identifying both the resource and paginated nature. It is distinguishable from siblings like instagram_latest_posts through the explicit pagination focus, though it does not explicitly name the alternative.

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

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

It provides concrete pagination instructions: pass the returned next_cursor as cursor while has_more is true. However, it does not say when to use this tool instead of instagram_latest_posts or instagram_media, leaving the choice to inference.

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

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

Annotations already disclose read-only and open-world behavior. The description adds useful context about what profile fields are included and the existence-check use case, but does not mention behavior for private/nonexistent accounts or any response quirks.

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 with no filler. The first sentence front-loads the resource and returned fields; the second gives a concrete usage instruction.

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 one-parameter, read-only profile lookup, the description is nearly complete: it lists the key returned fields and suggests when to call it. It could additionally mention error behavior for missing/private accounts, but 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 description coverage is 100% and fully documents the username format and example. The tool description adds nothing about the parameter, so it meets the baseline but no more.

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

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

States a specific resource (Instagram account) and enumerates the returned content: bio, links, follower/following/post counts, verification, and business category. This clearly distinguishes it from siblings like instagram_posts and instagram_contact.

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 says to use this tool first to check whether an account exists, which is a clear usage context. It does not name alternatives or state when not to use it, so it stops short of a full routing guide.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, covering safety and external behavior. The description adds the specific fields returned, which is useful context but not new behavioral traits beyond what annotations imply.

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 with zero waste. The core purpose and field list are front-loaded, and the sibling routing is in the second sentence, making it highly concise and 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?

For a single-parameter tool with no output schema, the description adequately informs the agent of expected return fields and the alternative tool. It could mention whether the operation works for a confirmed reel only, but given the simple nature, it is sufficiently complete.

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

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

Schema coverage is 100% and fully documents the shortcode parameter with a concrete example. The description adds no additional parameter semantics, so the baseline of 3 is appropriate.

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

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

States the specific purpose: details of one Instagram reel, and lists the exact data fields (views, likes, comments, caption, video URL, audio attribution). It clearly distinguishes from instagram_media by naming the sibling and the condition for using it.

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

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

Explicitly directs to use instagram_media when the shortcode is not confirmed to be a reel, providing a clear alternative. Could be more comprehensive (e.g., prerequisites), but the core routing guidance is present.

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

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

The annotations already declare readOnlyHint and openWorldHint, and the description adds a valuable behavioral nuance: no call to Instagram is made, but the operation still counts as one API request. This helps an agent set expectations about cost/behavior beyond what structured annotations convey.

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

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

The description is only two sentences, with the core conversion behavior stated first and the workflow guidance second. Every sentence earns its place, and there is no filler or repetition of structured data.

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

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

For a single-parameter conversion utility with readOnlyHint and openWorldHint annotations, this description is fully sufficient. It explains what the tool does, how it behaves relative to API calls, and how it fits into the broader Instagram workflow via instagram_media_by_id.

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

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

Schema description coverage is 100%, and the parameter schema already includes a clear description with a concrete example (DbtErSrlB2J). The tool description does not add any further parameter-level detail, 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 states a specific verb ('Converts') and resource ('post shortcode into its numeric media_id'), and directly contrasts with instagram_media_by_id by explaining that tool needs the numeric ID. This makes it immediately distinguishable from the sibling instagram_id_to_shortcode and instagram_media_by_id.

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

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

The description explicitly says to use it before instagram_media_by_id and explains why: that tool needs a numeric id rather than the shortcode. This provides clear context and a concrete workflow, though it does not explicitly list when not to use it or name the reverse-conversion sibling.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the description does not need to re-establish safety. It adds useful behavioral context by specifying what the returned profile contains (title, description, avatar, verification, links) and that the enumeration happens in a single call, implying no pagination or multiple requests are needed.

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, each earning its place: one defines the resource and its contents, the other states the intended use and aggregating behavior. No filler or redundant restatement of the title is present.

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

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

For a simple one-parameter read-only tool with no output schema, the description adequately conveys what the response will contain. It stops short of mentioning error cases or formatting details, but the schema and annotations cover the essential invocation context.

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

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

The schema covers 100% of the single parameter, including a clear description and example ('e.g. linktree from linktr.ee/linktree'). The tool description adds no parameter-level detail, 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 identifies the resource (a Linktree page) and the action (enumerate every link it publishes in one call), listing the page components returned. This distinguishes it from the many sibling tools targeting Instagram, TikTok, YouTube, GitHub, and other platforms.

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 'Use it to enumerate every link the page publishes in one call' gives a clear context for using the tool. However, there is no explicit guidance on when not to use it or which sibling to prefer as an alternative, though no competing Linktree sibling exists.

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

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

Annotations already declare readOnlyHint and openWorldHint. The description adds context about what data the profile returns (counts, verification, privacy) and confirms it's a public resource, which is useful behavioral information. No contradictions.

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

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

Two sentences, front-loaded with the data contents, followed by a usage directive. No filler or redundancy; every word contributes to the agent's understanding.

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

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

For a single-parameter read-only tool with no output schema, the description lists the expected return fields and explains its purpose in the workflow. It is fully sufficient for an agent to call it correctly.

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

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

Schema coverage is 100% for the single 'username' parameter, which already includes a description and example. The tool description adds no additional parameter-level semantics beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states it returns the public profile of a TikTok account, listing specific data fields (nickname, bio, counts, verification, privacy). It also distinguishes itself from sibling tiktok_video by explicitly mentioning its role in checking account existence.

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

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

Provides explicit usage guidance: 'Use this first to check an account exists before calling tiktok_video.' This tells the agent when to use it and points to the alternative tool, giving clear decision criteria.

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

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

Annotations already establish readOnlyHint=true, so no safety surprise. The description adds the 'public' scope and enumerates the response contents, reinforcing that this is a lightweight read operation with no mutation or hidden side effects.

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

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

Two tight sentences with no filler. The result content is front-loaded, followed by the invocation condition, making it easy to scan and act on.

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

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

For a single-parameter, read-only tool with a fully documented schema, the description covers what the call returns and how to obtain the id. It does not explain error behavior or availability, but that is a minor gap given the simple contract.

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

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

Schema coverage is 100%, and the schema already documents video_id with a pattern and example. The description adds the practical origin of the id ('parsed from the video's URL'), which is helpful but complementary; the schema does the essential work.

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 ('one public TikTok video') and specifies the returned detail categories (view/like/share/comment counts, duration, cover, audio). It also distinguishes itself from the sibling tiktok_profile by focusing on a single video rather than a 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 states an explicit precondition ('once you have a numeric video id') and gives source guidance ('typically parsed from the video's URL'), so an agent knows when to call it. It does not name alternatives or exclusions, but the context is clear enough for this simple tool.

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

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

Annotations already mark readOnlyHint=true, and the description's 'Public' tag reinforces rather than adds. It adds useful behavioral context such as existence checking and live status, but it does not describe behavior for missing channels or the response shape; no contradiction.

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

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

Two sentences with no filler: the first lists the returned data fields, and the second gives usage ordering relative to twitch_videos. 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 one-parameter public read tool with no output schema, the description is nearly complete: it lists the returned fields and tells the agent when to call it. It stops short of describing the non-existence response, but the existence-check wording implies that behavior adequately.

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 fully documents the only parameter, handle, with a type, minLength, and example, so the description adds no parameter-specific meaning. A baseline of 3 applies because schema description coverage is 100%.

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

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

The description names the exact resource (public Twitch channel) and the data fields it returns, including followers, partner/affiliate status, and live status. It also explicitly frames the tool as an existence check before calling twitch_videos, distinguishing it from the relevant sibling.

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

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

It gives an explicit directive: 'Use this first to check a channel exists before calling twitch_videos,' establishing the primary context and naming the alternative. It does not enumerate when not to use it, but the single same-platform sibling and the 'first' ordering make the guidance clear.

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

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

Annotations already provide readOnlyHint and openWorldHint, so the description does not need to cover safety. It adds genuinely useful behavioral detail beyond annotations: results are not paginated, and callers should raise the limit rather than paginate. It does not describe ordering or return shape, but this is secondary for a simple read-only listing.

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 with no filler, and the core behavior is front-loaded before the pagination caveat. Every clause contributes information an agent needs.

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 read tool with a fully documented schema, the description covers what is returned and how to request more results. It could be improved by explicitly routing agents away from twitch_profile, but nothing essential is missing for making a correct call.

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

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

Schema description coverage is 100%, so the schema fully documents handle and limit. The description adds mild value by explaining the intent behind limit ('raise limit for more results in a single call'), but it does not add meaning to handle beyond what the schema already provides.

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

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

The description clearly identifies the resource as a Twitch channel's recent videos and enumerates the video types (past broadcasts, highlights, uploads), which distinguishes it from a profile or contact tool. It lacks an explicit verb like 'list' or 'retrieve' and does not name twitch_profile, so it is clear but not maximally differentiated.

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

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

There is no guidance on when to choose this tool over twitch_profile or other siblings. The only usage note, 'not paginated: raise limit for more results,' is a how-to instruction rather than a when-to-use or when-not-to-use statement.

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

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

The annotations already declare readOnlyHint=true, so no mutation risk needs explanation. The description adds useful behavioral detail beyond the annotations: only public videos are returned, the response includes a channel block, and views/age are presented as display strings in metadataText rather than structured numeric fields. This helps set agent expectations about the return shape.

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 with no filler. The main result is front-loaded, and the important caveat about views and age being display strings is delivered compactly. 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 simple one-parameter, read-only tool with no output schema, the description provides enough context to call the tool correctly: the resource, the scope ('public'), the included channel block, and a notable formatting detail. It does not exhaustively enumerate all video fields, but the description is reasonably complete given the tool's simplicity and annotation coverage.

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

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

The schema covers the only parameter, handle, with a clear description and example, so schema coverage is 100%. The description adds no new parameter-level meaning. Per the baseline for high schema coverage, 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 identifies the resource: a YouTube channel's public videos plus the channel block containing title, description, and avatar. It is distinguishable from the sibling tools, which largely target Instagram, TikTok, GitHub, and other platforms, so an agent can infer this is the YouTube video listing tool. However, it lacks an explicit verb such as 'list' or 'retrieve', so the purpose is clear but slightly less direct.

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 by the description: when an agent needs a YouTube channel's public videos or channel metadata, this is the tool. There is no explicit when-to-use or when-not-to-use guidance, and no alternative YouTube tool exists among siblings to warrant an exclusion. This is adequate but not strongly instructive.

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