Social Fetch

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

Annotations already declare readOnlyHint=true and openWorldHint=true, which cover the operation's safety and dynamic nature. The description adds no further behavioral context (e.g., that it might return a large payload or highlight pagination). With annotations covering the safety profile, a score of 3 is appropriate—the description is consistent but does not enrich 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 sentence with zero redundancy. It fronts the purpose and method. No wasted words, and it effectively communicates the tool's core function.

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 fetch tool with no output schema, the description is sufficiently complete. It states what to provide (URL) and the operation. The cursor parameter is documented in the schema, so its presence is known. The tool seems complete for the intended use; only minor missing context like return format could be added, but it's not critical.

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 provides clear definitions for both 'url' and 'cursor'. The description adds no extra meaning about these parameters. Baseline 3 applies because the schema carries the burden, and the description doesn't need to repeat 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 states a specific verb ('Get'), a clear resource ('creator Amazon Shop storefront'), and the method ('by URL'). This distinguishes it from the many sibling platform tools, which are all similarly named but target different services. An agent can immediately understand what this tool does and when it applies.

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

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

The description clearly implies the tool is used to fetch an Amazon Shop storefront when you have its URL. It does not explicitly mention alternatives or when not to use it, but given the sibling list, there is no direct alternative for Amazon Shop, so ambiguity is minimal. The 'by URL' phrasing sets a clear prerequisite. Cursor for pagination is not mentioned, though it appears in the schema, which slightly reduces 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 provide readOnlyHint=true and openWorldHint=true, covering the safety profile. The description adds the input methods but does not describe return format, authentication needs, or any other behavioral traits. It does not contradict annotations and adds minimal extra context beyond the schema.

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

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

The description is a single, front-loaded sentence with no fluff. It efficiently conveys the action and input options, making it appropriately sized for a simple get 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 incomplete in terms of context. Both parameters are optional in the schema, but the description says 'by id or album URL', implying one is needed—this ambiguity is unresolved. There is no information on return values (no output schema), no guidance on choosing between id and URL, and the openWorldHint suggests data might be incomplete, which is not addressed. More context is needed for an agent to invoke this 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%: both url and albumId have descriptions. The description repeats the same information ('by id or album URL') without adding format details or clarifying that at least one parameter is effectively required, despite the schema marking both as optional. This creates ambiguity but the schema already documents the parameters adequately.

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 action (Get), the resource (Apple Music album), and the two input forms (id or album URL). This distinguishes it from sibling tools like appleMusic_artist_get and appleMusic_track_get, which target different resource types.

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

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

There is no explicit guidance on when to use this tool versus alternatives. It does not mention exclusions, such as 'for tracks use appleMusic_track_get', nor any conditions that would select this tool over others. Usage context is only implied by the resource name.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the description only needs to add context beyond those. It confirms it's a read operation but adds no details about rate limits, pagination, or what happens with invalid inputs. This is adequate given the simple read-only nature and annotation coverage.

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

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

The description is a single, clear sentence with no unnecessary words. The essential information (action, resource, and how to specify it) is front-loaded and immediately understandable.

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

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

Given the tool's simplicity and lack of an output schema, the description is minimally complete. It doesn't specify what the response contains (e.g., artist details like name, genres), but for a straightforward get operation this might be sufficient. A bit more detail about the return value would improve completeness.

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

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

Schema coverage is 100%, so both parameters (url and artistId) already have descriptions. The tool description adds little beyond repeating that either an id or URL can be used; it doesn't clarify that at least one is required or what happens if both are provided. This meets the baseline but adds minimal value.

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 action (Get), the resource (Apple Music artist), and the two ways to specify it (by id or URL). It distinguishes the tool from siblings like appleMusic_album_get and appleMusic_track_get by naming the specific resource type.

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

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

No explicit guidance on when to use this tool versus alternatives. It doesn't mention that search (appleMusic_search_list) should be used when an id or URL is unknown, nor does it state any prerequisites or exclusions. The usage is only implied by the description.

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

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

Annotations already declare readOnlyHint and openWorldHint, so description doesn't need to repeat safety. It adds pagination note (use cursor) which is useful. However, it doesn't describe result structure or error behavior.

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

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

One concise sentence with a useful pagination note. Front-loaded with purpose. 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 simple catalog search with two params covered by schema, the description is adequate. It states the search scope, return type (list), and pagination hint. It doesn't detail output fields, but with no output schema, a minimal note may suffice.

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

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

Schema description coverage is 100%, so both parameters are documented. The description adds no extra semantics beyond 'by keyword' which aligns with query. It doesn't explain the type enum or any nuances.

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 (search) and resource (Apple Music catalog), and clarifies it returns a list. Distinct from sibling getters like appleMusic_album_get which retrieve specific items.

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

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

No guidance on when to use this vs alternative getters. It could mention that search is for discovery and then use getters to retrieve details, but it doesn't.

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 description's 'Get' adds little. It does not contradict annotations, but it also does not disclose any additional behavioral traits (e.g., return format, availability conditions). Given the annotation coverage, a 3 is appropriate.

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

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

A single, concise sentence that contains no unnecessary words while conveying the core function. It is appropriately front-loaded and efficient.

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

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

For a simple getter with two optional parameters and no output schema, the description covers the essential information. It lacks details about the response structure or potential regional limitations, but given the simplicity and annotation coverage, it is largely sufficient.

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

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

Schema description coverage is 100% with both 'url' and 'trackId' documented. The description merely echoes that these are the two available inputs without adding meaning beyond the schema. Baseline of 3 holds as the schema carries the semantic weight.

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

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

The description clearly states the tool's action (Get), the resource (Apple Music track), and the input methods (id or URL). It effectively distinguishes this from sibling tools like appleMusic_album_get and appleMusic_artist_get by specifying 'track'.

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

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

There is no guidance on when to use this tool versus appleMusic_search_list or other alternatives. No prerequisites, exclusions, or context about when a track ID vs URL is preferred are provided.

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

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

The description adds only the phrase 'for this session' beyond what annotations already declare (readOnlyHint=true). It discloses the read-only nature implicitly, consistent with annotations, but does not elaborate on potential errors (e.g., unauthenticated state) or return specifics. Given annotations cover the safety profile, the minimal extra context warrants a middle score.

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

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

The description is a single, front-loaded sentence with zero waste. It immediately states the action and the object, leaving no room for verbosity. This is an exemplary concise and structured definition.

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

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

For a zero-parameter, no-output-schema tool, the description is fully complete. It tells the agent exactly what the tool returns (the authenticated API account) and when it applies (this session). There are no missing details an agent would need 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?

The tool has zero parameters, and the schema reflects this with no properties. Per the rubric, a zero-parameter tool receives a baseline of 4 because there are no parameter semantics to clarify. The description's mention of 'authenticated account' adequately orients the user to what is returned, even though no params exist.

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 'Get the authenticated API account for this session' clearly states the specific verb (get) and resource (authenticated API account). It is distinct from all sibling tools, which target external platforms, by focusing on the session's own auth identity. 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 clear context: it retrieves the account associated with the current session. While it does not explicitly name alternatives or exclusions, it is unique among siblings (none other deal with auth identity), so the usage context is implicit and sufficient. A score of 4 reflects clear context without explicit when-not guidance, which is acceptable given the tool's uniqueness.

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 'metered tools' context, which is useful but not essential behaviorally. No side effects or additional constraints are disclosed, but that's fine given the simplicity of a read-only balance check.

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

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

A single, front-loaded sentence that conveys the purpose and the usage condition without any fluff. Every word earns its place, and there is no redundant information.

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

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

For a no-parameter, read-only tool with no output schema, the description fully explains what it does and when to use it. An agent can confidently call this without needing additional documentation. The lack of a stated return format is acceptable for a simple balance query.

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?

With zero parameters and 100% schema coverage (trivially), the baseline is 4. The description adds no parameter-specific details because there are none, and the schema is empty, so the description doesn't need to compensate for anything.

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 action (get), the resource (remaining credit balance), and the specific context (before running large batches of metered tools). This makes it distinct from all sibling tools, none of which touch billing or credit.

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 when to use this tool: 'before running large batches of metered tools.' This provides a clear, actionable condition for invocation. There are no alternative billing tools in the sibling list, so no exclusions are needed.

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

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

The annotations already declare readOnlyHint=true and openWorldHint=true, covering the read-only nature and the possibility of external changes. The description does not add behavioral context beyond the purpose (e.g., side effects, auth requirements, rate limits). It neither contradicts the annotations nor enriches them, so a baseline score is appropriate 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?

The description is a single, focused sentence: 'Get a single Bluesky post by URL.' It is front-loaded with the essential verb and resource, and contains no filler or redundant information. Every word serves a purpose, achieving maximum conciseness for a simple GET tool.

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

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

For a simple one-parameter, read-only retrieval tool, this description is nearly complete. It specifies the input (URL) and the action (get), which is sufficient for an agent to invoke it. The absence of an output schema is mitigated by the expected behavior of a 'get' tool, and annotations cover safety. The only minor gap is that it doesn't explicitly state what the response contains, but that is typical for such tools and not a significant omission.

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 schema fully documents the 'url' parameter as 'Link to the Bluesky post.' The description's phrase 'by URL' is redundant with the schema and adds no new meaning. With high schema coverage, the baseline of 3 applies; there is no additional semantic value provided.

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

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

The description states a specific verb ('Get'), a specific resource ('a single Bluesky post'), and the method of identification ('by URL'). This clearly distinguishes it from sibling tools like bluesky_profile_get (which fetches a profile by handle) and bluesky_profile_posts_list (which lists posts for a profile), making the purpose unambiguous.

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

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

The description gives clear context for when to use the tool: when you have a URL to a specific Bluesky post. It does not explicitly mention when not to use it or point to alternatives, but the 'by URL' condition effectively implies the use case, and sibling tool names provide natural differentiation. This aligns with clear context without explicit exclusions.

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

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

The annotations already declare readOnlyHint=true and openWorldHint=true, covering the safety profile. The description adds no additional behavioral context—no mention of return format, error handling, rate limits, or what happens with invalid handles. Since the description carries minimal weight and annotations cover the essential traits, this is adequate but not enriched.

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, efficient sentence. It is front-loaded with the primary action and resource, with no wasted words. It earns full marks for 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?

Given the tool has one parameter, no output schema, and simple read-only annotations, the description is minimal but not fully complete. It does not explain what profile data is returned (e.g., handle, display name, bio) or any error behavior. For a simple lookup, this may suffice, but the lack of detail on return value leaves some ambiguity.

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 fully documents the 'handle' parameter, including the option to have or omit a leading @. The description's statement 'Accepts a handle' is redundant with the schema and adds no new semantics. It meets the baseline for high schema coverage.

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

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

The description clearly states the verb 'Get' and the resource 'Bluesky profile', specifying it is for a creator or account. This distinguishes it from siblings like bluesky_post_get and bluesky_profile_posts_list. The phrase 'for a creator or account' adds slight redundancy but ensures the scope is understood.

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

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

The description does not explicitly state when to use this tool versus alternatives, nor does it mention exclusions or prerequisites. However, the clear resource and platform in the name make the intent obvious, and the sibling list includes related post/list tools that are implicitly different. There is no direct guidance on when not to use it, so it earns a midpoint score.

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, lowering the burden. The description adds that the result is a list and pagination is handled via cursor, which is helpful but somewhat redundant with the schema's cursor parameter description.

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

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

A single focused sentence with no fluff. The core action is front-loaded and pagination guidance is compactly appended.

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, the description together with the schema and annotations covers the essentials. No output schema exists, but the return shape (a list) and pagination hint are 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 description coverage is 100%, so the baseline is 3. The description mentions 'by handle' and cursor usage but adds little beyond what the schema already documents for each parameter.

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

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

The description uses a specific verb ('List') and names the resource ('posts from a Bluesky profile by handle'). It clearly distinguishes from sibling tools like bluesky_post_get (single post) and bluesky_profile_get (profile details).

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

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

Usage context is implied: this tool lists posts of a specific Bluesky profile via handle. However, it does not explicitly name alternatives or state when not to use it (e.g., for a single post or for searching posts across profiles).

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 read-only nature is covered. The description adds valuable behavioral detail: the default mode, what 'outline' returns (compact field digest), what 'full' includes, and accepted pathname patterns. 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 a single, compact sentence that front-loads the action and uses no filler. It packs essential information (default mode, full mode usage, accepted pathname formats) with zero waste.

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

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

For a read-only tool with a well-documented schema and annotations, this description is complete. It explains the source of the pathname, the mode options, and the pathname constraints. No output schema exists, but the description hints at what 'outline' and 'full' return, covering the agent's needs.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description enhances this by clarifying mode semantics ('compact field digest' vs 'Examples/SDK snippets') and giving example pathnames, adding useful context 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 verb ('Read'), a resource ('corpus page'), and the source ('from docs_search'), clearly distinguishing this from its sibling docs_search. It also specifies the pathname format, leaving no ambiguity about what the 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?

It indicates that the pathname comes from docs_search, implying a two-step workflow, and explains when to use 'full' mode (for Examples/SDK snippets). It does not explicitly state when not to use this tool or name alternatives, but given its unique role as a doc reader, the guidance is clear and 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 and openWorldHint=false, covering the safety profile. The description adds scope context (API/SDK questions) and a routing hint, but does not describe return format, pagination, or behavior on no results. With annotations present, this is adequate but not richly descriptive, matching the calibration example that scored 3.

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 the primary purpose stated first, followed by a clear routing to the sibling tool and a specific search hint. Every sentence earns its place, and the structure is front-loaded with the core function.

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 all parameters documented, no output schema, and read-only annotations, the description covers the essential purpose, routing, and usage context. It could mention what the tool returns (e.g., doc snippets) but that is implied by 'search docs.' Given the annotations and schema coverage, this is nearly complete.

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

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

Schema description coverage is 100%, so all three parameters (query, limit, currentDocsPathname) are fully documented in the schema. The description does not add parameter-specific details beyond what the schema provides; it only suggests search terms. Baseline 3 is appropriate since the schema carries the parameter documentation.

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

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

The description clearly states the tool performs searches on SocialFetch docs for API/SDK questions, a specific verb+resource+scope. It also distinguishes itself from the sibling docs_read by explicitly saying docs_read is for response fields, 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?

The description provides explicit routing: 'For response fields use docs_read' and gives specific search guidance for cross-platform naming ('search field crosswalk or read /product/ask-ai/field-crosswalk'). This tells the agent when to use this tool versus alternatives and how to construct effective queries.

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 the read-only and external-data nature. The description adds little beyond the fact that it retrieves a single ad. It does not mention potential failure modes, normalization, or the effect of 'trim' and 'includeTranscript' in detail, but given the annotations, the bar is lower and a 3 is appropriate.

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, concise sentence that front-loads the core purpose. It contains no redundant or distracting information, 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 straightforward single-ad retrieval tool with no output schema, the description is mostly complete. It does not explicitly state what happens if the ad is not found or describe the return shape, but given the openWorldHint and the simplicity, this is a minor gap. The optional parameters are self-explanatory via the schema.

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

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

Schema coverage is 100%, so all four parameters are documented. The description clarifies that url and adId are alternative locators, which adds a tiny bit of meaning beyond the schema. However, it adds no new information about 'trim' or 'includeTranscript' beyond their schema descriptions, so a baseline 3 is suitable.

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 a single Facebook Ad Library ad using either an archive id or public URL. This directly distinguishes it from search and list tools in the same domain, such as facebook_adLibrary_ads_search_get or facebook_company_ads_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?

By specifying retrieval 'by archive id or public Ad Library URL', the description implies the tool is appropriate when the user has a specific ad identifier. It does not explicitly warn against using it for searching or list all ads, but the wording makes the usage context reasonably clear.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds that it returns a list and advises using a cursor for pagination, which is useful. However, it does not discuss rate limits, authentication, or any other behavioral traits beyond the return type and pagination hint.

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 purpose is stated upfront, followed by the return type and pagination guidance. 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 has 11 parameters and no output schema. The description is minimal but the schema covers all parameter semantics and annotations cover safety. It notes pagination, which is important for a search tool. However, it does not provide an overview of how filters interact or any use-case context, which could be valuable given the tool's 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% – every parameter has a detailed description including enums and formats. The description only refers to 'keyword and filters' at a high level, adding little beyond what the schema already provides. Baseline 3 is appropriate given the complete schema coverage.

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

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

The description states the tool searches Facebook Ad Library ads by keyword and filters, which is a specific verb and resource. The name itself disambiguates from sibling tools on other platforms, though the description does not explicitly contrast with them. It is clear enough to distinguish the operation.

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

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

No guidance is provided on when to use this tool versus alternatives such as facebook_adLibrary_ad_get (for a single ad) or ad library search tools on other platforms. The description only states what the tool does, not the conditions for selecting it over 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. The description adds a useful behavioral detail: it returns a list and mentions cursor-based pagination. This goes beyond what annotations provide, giving agents a concrete expectation about response structure and how to handle large result sets.

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

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

The description is two sentences, front-loaded with the purpose, and includes the pagination note without any fluff. Every sentence earns its place, and the critical details (what it does, acceptance criteria, pagination) are presented efficiently.

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 search tool with readOnly and openWorld annotations, the description covers the core usage: search by company name and handle pagination. It does not explain how to use the cursor in detail, but that is likely a standard pattern. The absence of an output schema and the simplicity of the API makes this adequate, though a brief note about the return format's shape would push it to a 5.

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

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

Schema coverage is 100%, so the parameter itself is fully documented. The description adds semantic value by stating the query is a 'company name', which narrows the meaning beyond the generic 'Search query text'. This clarifies what kind of input is expected, exceeding the baseline.

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

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

The description clearly states a specific verb ('Search') and resource ('Facebook Ad Library companies / advertisers by name'), and notes it accepts a company name and returns a list. It is clear what the tool does, but it does not explicitly differentiate itself from sibling tools like facebook_adLibrary_ads_search_get or facebook_company_ads_list, so it falls short of a top score.

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

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

The description implies usage context: you use this when you have a company name and want to find the matching advertiser. It also mentions pagination handling. There is no explicit guidance on when not to use it or alternatives, so it gets a 4 rather than a 5.

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

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

The annotations already declare readOnlyHint=true and openWorldHint=true, so the read-only and open-world nature are known. The description adds one piece of behavioral context: 'use cursor when paginated', which is useful. However, it doesn't elaborate on return format, error conditions, or any other behavioral traits. Given the annotations carry much of the load, a score of 3 is appropriate—it adds value without overloading.

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

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

The description is two concise sentences with zero fluff. The primary purpose is front-loaded in the first sentence, and the second sentence covers input options and return behavior. Every word serves a purpose, making it optimally 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?

Given the low parameter count (10 but all optional) and thorough schema descriptions, the tool description covers the essential information: purpose, primary input options, and pagination. It doesn't mention the implications of providing both pageId and companyName or neither, but that's a minor gap. The openWorldHint annotation indicates results may be non-exhaustive, which the agent should know. Overall, it's complete enough for an agent to call 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 all 10 parameters are documented in the schema. The tool description merely restates the dual input option ('Accepts a page id or company name'), which is already present in the schema descriptions for pageId and companyName. No additional semantic depth is added, justifying the baseline score of 3.

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

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

The description clearly states the verb ('List') and resource ('ads a company or Page is running in the Facebook Ad Library'), which is specific and unambiguous. It doesn't explicitly differentiate from the sibling facebook_adLibrary_ads_search_get, but the function's scope (list all ads for a given company/Page) is distinct enough that an agent could infer the difference from the name and description combined.

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

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

The description offers no guidance on when to use this tool versus alternatives such as facebook_adLibrary_ads_search_get or facebook_adLibrary_companies_search. It states that it accepts a pageId or companyName, but doesn't explain when one would choose this list endpoint over a search or a company lookup. This leaves the selection decision to the agent based solely on the tool name.

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

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

Annotations already declare readOnlyHint and openWorldHint. The description adds the retrieval mode ('by URL or event id') but does not disclose other behavioral aspects such as response format, error conditions, or handling of missing/conflicting inputs. Since annotations cover the safety profile, this is a moderate addition.

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, tight sentence with no filler. The action and key identifiers are front-loaded, and every word contributes to the meaning. It is an exemplar of concise specification.

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

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

The tool has two optional parameters but logically requires at least one; the description does not clarify this. It also omits what the tool returns (no output schema) and any caveats about using both or none. For a getter with no output schema, an agent needs more context to call it correctly, leaving significant gaps.

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

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

Schema description coverage is 100%, and both parameter descriptions in the schema already convey their meanings. The tool description merely restates 'by URL or event id' without adding any new semantic detail beyond what the schema provides, so it does not compensate beyond the baseline.

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

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

The description clearly states the specific action ('Get'), the resource ('Facebook event'), and the two identification methods ('by URL or event id'). It precisely distinguishes what this tool does from other sibling tools that list or search events, making the purpose unmistakable.

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

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

No guidance is given on when to use this tool versus alternatives like facebook_events_search_list or when to prefer url over eventId. The description only states the purpose but offers no contextual direction on selection criteria or required inputs, leaving the agent to infer usage.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the description carries a lighter burden. The description adds the key behavioral detail of pagination ('use cursor when paginated') and confirms the return type is a list. 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?

Two sentences with zero fluff: the first states the core operation and input, the second covers the return type and pagination. The information is front-loaded and 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 moderately simple list tool with three params, an existing output schema is absent, and annotations cover safety, the description is nearly complete. It tells the agent what it returns and how to paginate, which is the critical runtime behavior. Minor gaps remain, such as error behaviors or what the list items contain, but these are not essential for calling 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 each parameter (url, time, cursor) is already documented in the schema. The description only briefly alludes to 'explore URL' and 'cursor' without adding deeper semantics or examples, so it adds no value beyond what the schema already provides. 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 action ('List'), the resource ('Facebook events for a city'), and the method ('by explore URL'). This distinguishes it from siblings like facebook_events_search_list (which likely does a keyword search) and facebook_event_get (singular event), though it doesn't explicitly name alternatives. The purpose is unambiguous and specific.

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 this tool is for when you have a city's explore URL, but it gives no explicit guidance on when to prefer this over comparable siblings like facebook_events_search_list or facebook_profile_events_list. No exclusions or alternative conditions are provided, leaving the selection largely to inference.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds the valuable behavioral detail that the tool returns a list and supports pagination via cursor. This goes beyond the annotations by explaining the return shape and how to navigate pages.

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

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

The description is compact and front-loaded: it states the core purpose in the first clause and adds the key return/pagination detail in the second sentence. No filler or redundancy. 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 search tool with a single required parameter and optional cursor, the description covers the essential information: what is searched (by name) and how pagination works. Given the absence of an output schema, mentioning that it returns a list is helpful, though it could hint at the structure of the list items. Overall, adequate for an agent to use 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%: both 'query' and 'cursor' are described explicitly in the input schema. The description adds little beyond the schema—it echoes the 'by name' concept and the pagination hint. This is a case where the schema does the heavy lifting, so a baseline of 3 is appropriate.

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

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

The description states a specific action ('Search Facebook events by name') and clearly indicates the resource and scope. It differentiates from siblings like facebook_event_get (singular) and facebook_events_list (likely a non-search list) by the explicit 'by name' qualifier and the 'Returns a list' note.

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

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

No explicit guidance is given on when to use this tool versus alternatives. It does not mention when to prefer this over facebook_events_list, facebook_event_get, or facebook_profile_events_list. The usage context is only implied by the name and 'by name' phrasing, which is insufficient for an agent to make routing decisions without inspecting other 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 safety profile is covered. The description adds no behavioral context, such as what happens when both url and groupId are provided, whether the group must be public, or any rate-limit/auth requirements. Since annotations carry the burden, a 3 is appropriate — the description doesn't contradict them, but it doesn't enrich the behavioral picture.

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

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

A single sentence with no wasted words. The core purpose and identification methods are front-loaded, and everything present serves a function. Perfectly concise.

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 get tool, the description is functionally sufficient: it states what and how. However, it lacks any indication of return format or extra context (e.g., does it return member count, description, etc.), though no output schema exists. Given the tool's simplicity and the safety annotations, this is adequate but not rich.

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

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

Schema description coverage is 100% — the schema already documents each parameter's purpose (URL vs numeric id) and constraints. The description's 'by URL or group id' essentially restates this, adding no new meaning beyond the schema. Baseline 3 is correct when the schema does the heavy lifting.

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

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

The description clearly states the action ('Get'), the resource ('a Facebook group'), and the two identification methods ('by URL or group id'). It distinguishes from siblings like facebook_group_posts_list by focusing on the group itself rather than its posts, though it doesn't explicitly name the sibling for contrast.

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

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

No guidance on when to use this tool vs alternatives. There is no mention of 'use this to retrieve group metadata' or 'if you need posts, use facebook_group_posts_list'. The sibling list includes relevant alternatives, but the description does not point to them, leaving the agent to infer usage context.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, covering the read-only nature and potential incompleteness. The description adds value by noting the response is a list and advising pagination via cursor. This goes beyond the annotations without contradicting them, providing helpful runtime behavior.

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

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

The description is two short sentences with no redundancy. The core action ('List posts from a Facebook group by group URL') is front-loaded, and the pagination note is concise. Every word contributes meaning.

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 states the return type (a list) and pagination mechanism, which is sufficient for an agent to correctly invoke the tool. While it does not detail the post object structure, the absence of an output schema and the simplicity of the tool make this acceptable. It is complete enough for correct use.

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

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

The input schema provides 100% coverage for all three parameters (url, cursor, sortBy), including detailed descriptions and an enum with explanations for sortBy. The tool description adds no additional parameter semantics beyond what the schema already offers, so it meets the baseline without excelling.

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

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

The description states the verb 'List', the resource 'posts from a Facebook group', and the input 'by group URL'. It clearly distinguishes this tool from siblings like facebook_group_get (which retrieves group info) and facebook_profile_posts_list (which lists a profile's posts). The phrase 'Returns a list (use cursor when paginated)' further specifies output type.

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 basic usage (list posts by URL) but does not explicitly mention when to use this tool over alternatives or any exclusions. While the name and description make the use case obvious, there is no guidance on when not to use it or how it differs from related list tools. This leaves some inference to the agent.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the read-only, external-fetch nature is covered. The description adds nothing beyond 'Get details', which is consistent but does not provide extra context such as error behavior or rate limits. It does not contradict annotations.

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

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

The description is a single sentence, front-loaded with the action and resource. It is minimal and to the point, with no unnecessary words.

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

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

For a simple get operation with no output schema, the description is adequate but has gaps: it does not clarify that at least one of url or itemId must be provided (both are optional in the schema), nor does it describe what 'details' includes. Given the tool's complexity, a bit more context would be helpful, but it is still usable.

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

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

Schema description coverage is 100%, so both parameters (url and itemId) are documented with clear meaning. The tool description adds no new semantic insight beyond the schema, so the baseline 3 applies.

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

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

The description clearly states the action ('Get details') and the resource ('Facebook Marketplace listing'), and it distinguishes from search/list siblings by targeting a single item. However, it only mentions URL as the locator while the schema also supports itemId, so it's slightly incomplete.

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

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

The description provides no guidance on when to use this tool versus alternatives like facebook_marketplace_search_list or facebook_marketplace_locations_search. The parameter description for itemId hints at when to use it, but the tool description itself is silent on tool selection criteria.

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

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

Annotations already declare readOnlyHint and openWorldHint, covering safety and variability. The description adds that it returns a list and mentions cursor pagination, useful behavioral context beyond annotations. No contradictions exist.

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

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

Three short sentences, each earning its place: purpose, parameter, and return behavior. No redundancy or fluff.

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

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

For a one-parameter read-only search tool with no output schema, the description provides the essential info: purpose, input, return type, and pagination hint. It could specify output item fields, but given the simplicity, it is adequate.

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

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

Schema coverage is 100% and the schema describes 'query' as a city or place name. The description repeats this ('Accepts a city or place name') without adding format, examples, or additional constraints, so it adds little beyond the schema.

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

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

States a specific verb (search), resource (Facebook Marketplace locations), and the purpose (obtain coordinates for listing search). This clearly distinguishes from sibling tools like facebook_marketplace_search_list or facebook_marketplace_item_get, which serve different functions.

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

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

The description implies the tool is a precursor to listing search by stating 'to obtain coordinates for listing search', providing clear context for when to use it. It does not explicitly name alternative tools or exclusions, but the purpose is clear enough for an agent to decide.

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 practical behavior on pagination ('use cursor when paginated'), which goes beyond annotations. It does not contradict annotations. The lack of depth (e.g., rate limits, response format) is mitigated by 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 with no fluff, front-loading the core purpose and adding a pagination tip. It is concise but not overly sparse, efficiently conveying the essential behavior.

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 14 parameters and no output schema, the description only covers keyword and location, omitting the extensive filter options (price, condition, sort, etc.) that are documented in the schema. An agent might not realize these capabilities are available. The pagination tip is helpful, but the description does not convey the tool's full expected behavior or return structure beyond 'a list'.

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 detailed descriptions. The description does not add additional meaning beyond what the schema provides; it only reinforces the role of query/lat/lng. This meets the baseline of 3 for high schema coverage.

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

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

The description clearly states the action ('Search'), resource ('Facebook Marketplace listings'), and key parameters ('by keyword near a latitude and longitude'), making it easy to distinguish from siblings like facebook_marketplace_item_get (single item) and facebook_marketplace_locations_search (locations). The purpose is specific and unambiguous.

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

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

The description does not provide any guidance on when to use this tool versus alternatives. It does not mention exclusions, prerequisites, or scenarios where another sibling tool would be more appropriate. For a search tool with many sibling marketplace tools, this is a notable gap.

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 properties. The description adds a useful behavioral note about pagination ('use cursor when paginated'), which goes beyond the annotations. It does not describe rate limits, auth, or error behavior, but with annotations covering the read-only aspect, the added pagination detail justifies a mid-range score.

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

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

The description is two short sentences, front-loaded with the core purpose ('List comments...') followed by a concise output/pagination note. There is no fluff or repetition. It is efficient and well-structured, though it could arguably be even more direct about the output format, but it earns a high score for being appropriately concise.

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 main action and pagination but leaves a notable gap: it says 'by URL' implying the url parameter is required, yet the input schema lists no required parameters. This could mislead an agent into thinking url is mandatory when it is technically optional (or the schema is an oversight). It also does not mention the optional feedbackId parameter, though the schema covers it. Given the tool's simplicity and comprehensive schema, the description is mostly complete but has this ambiguity.

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 schema already documents each parameter (url, cursor, feedbackId) with clear descriptions. The description's mention of 'by URL' and 'use cursor when paginated' reinforces but does not add new meaning beyond the schema. Since the schema fully covers parameter semantics, a baseline of 3 is appropriate; the description adds minimal extra value.

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

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

The description clearly states the verb (list), the resource (comments on a Facebook post or Reel), and the method (by URL). This distinguishes it from a generic list tool, though it does not explicitly differentiate from the sibling facebook_post_comments_replies_list, which is for comment replies. The 'by URL' qualifier adds precision. It is not a tautology and provides a specific, actionable purpose.

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

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

The description provides no explicit guidance on when to use this tool versus alternatives. It mentions pagination ('use cursor when paginated') but does not note that for comment replies one should use facebook_post_comments_replies_list, nor does it clarify when to use this over facebook_post_get or other list tools. The usage context is implied from the name, but no explicit when-to-use/when-not-to-use instructions are given.

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

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

Annotations already declare readOnlyHint=true, so the description doesn't need to restate safety. It adds a pagination note: 'Returns a list (use cursor when paginated).' This is useful behavioral context beyond the schema. However, it omits any mention of error handling, rate limits, or the structure of the returned list, and the incomplete sentence about the cursor reduces clarity.

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

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

The description is short but contains a broken, incomplete sentence: 'Accepts a from post comments.' This is not just concise; it's ungrammatical and confusing. The structure is not front-loaded effectively, as the key action is stated first but followed by a garbled clause. Wasteful and error-prone.

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 provides minimal return info ('Returns a list') and pagination guidance. It does not explain what fields or structure the replied list contains, but for a simple one-parameter list tool this might be adequate. However, given the ambiguity of the 'Accept a' phrase, an agent might be unsure of the exact input format despite the schema. Overall, it meets the minimum but has room for improvement.

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 (cursor) with a precise description of where it comes from and how to paginate. The description's phrase 'Accepts a from post comments' adds no value and is actually less clear than the schema. Since schema coverage is 100%, the baseline is 3, and the description does not enhance 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 states the verb and resource clearly: 'List replies to a Facebook comment.' It distinguishes from sibling facebook_post_comments_list by focusing on replies. However, the phrase 'Accepts a from post comments' is incomplete and vaguely worded, which slightly reduces clarity.

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

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

No explicit guidance on when to use this tool versus alternatives like facebook_post_comments_list. The description hints that it takes a cursor from post comments, implying a prerequisite, but does not explicitly state the workflow or contrast with other comment-listing tools. The agent is left to infer usage context.

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

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

Annotations declare readOnlyHint=true and openWorldHint=true, so the description does not contradict them. However, the description adds no behavioral details beyond the action itself—it does not mention what the response contains, any authentication requirements, or rate limits. With the annotations covering the read-only nature, the description provides minimal extra value but is consistent with the structured metadata.

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

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

The description is a single sentence with no wasted words. It is appropriately brief for a simple get operation and does not attempt to restate the schema. It could optionally include a sentence about the response format, but the current length is efficient and focused.

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

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

There is no output schema, and the description does not indicate what the returned object will contain (e.g., post text, media, timestamps). While the tool is simple and the schema is descriptive, the absence of any return-value guidance or distinction from sibling tools leaves an agent uncertain about the output. Given the lack of output schema, the description should have at least mentioned that the result includes the post/reel content, but it only states the action.

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

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

The schema has 100% description coverage for the three parameters (url, includeComments, includeTranscript), each with a clear explanation. The tool description adds nothing beyond what the schema already conveys. Since the schema fully documents the parameters, the description does not need to repeat them, so a baseline score of 3 is appropriate.

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

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

The description clearly states the action (get) and the resource (Facebook post or Reel) with the input being a URL. It is not a tautology, and it distinguishes the tool from other Facebook getters like facebook_event_get or facebook_group_get, though it doesn't explicitly contrast them. The phrasing 'get a post or reel by URL' is specific enough for an agent to understand the primary purpose.

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

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

The description provides no guidance on when to use this tool versus alternatives such as facebook_post_comments_list or facebook_post_transcript_get. There are no use-case hints, no exclusions, and no mention of alternative tools that might be preferred under different conditions. An agent is left to infer the appropriate context solely from the tool name and schema.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, which tells the agent this is a safe, non-mutating operation that can handle unknown inputs. The description adds the fact that it works for both posts and Reels and that a URL is required—useful but not substantial beyond the annotations. It does not contradict the annotations, nor does it disclose additional behaviors like error handling or rate limits. Given the annotation coverage, a 3 is appropriate.

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

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

A single, front-loaded sentence: 'Get the transcript for a Facebook post or Reel by URL.' Every word earns its place—verb, object, scope, and input method are all conveyed. There is zero redundancy or filler, making it extremely concise and easy 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 simple, read-only tool with one parameter and no output schema, the description covers the essential information: what it retrieves (transcript), what it operates on (Facebook posts and Reels), and how to invoke it (providing a URL). The annotations cover safety (read-only) and flexibility (open-world). Nothing critical is missing for an agent to call this tool correctly, though it could optionally mention the transcript format or behavior when no transcript exists.

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

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

The schema has 100% coverage for the single required 'url' parameter, with a clear description: 'Link to the Facebook post or reel whose transcript should be returned.' The tool description only repeats 'by URL,' adding no new meaning or format details. With the schema fully documenting the parameter, the baseline of 3 is correct.

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 ('Get') and a precise resource ('transcript for a Facebook post or Reel by URL'). It clearly indicates what the tool returns and distinguishes it from other platform-specific transcript tools in the sibling list (e.g., instagram_post_transcript_get, youtube_video_transcript_get) by its explicit Facebook scope. No ambiguity remains about the tool's function.

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

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

The description implies usage: when you have a Facebook post or Reel URL and need its transcript. However, it does not explicitly state when to use this tool over alternatives (e.g., facebook_post_get for post metadata) or when not to use it, such as if a transcript is unavailable. The guidance is minimal and relies on the tool name and context rather than explicit instructions.

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

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

The description adds that it returns a list and mentions pagination via cursor, which goes beyond the readOnlyHint and openWorldHint annotations. It provides useful behavioral detail without contradicting the annotations.

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

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

Three concise sentences each serve a distinct purpose: the action, the input, and pagination. No fluff, and the core purpose is front-loaded.

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

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

For a simple read-only list tool with two documented parameters, the description covers the essential facts: what it does, what it accepts, and how to handle pagination. The lack of an output schema is mitigated by the clear statement that it returns a list.

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

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

Schema description coverage is 100%, so both parameters have full descriptions. The description's mention of 'profile or page URL' and 'use cursor when paginated' adds no new information 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 verb (list) and resource (events) scoped to a Facebook profile or Page, clearly distinguishing it from sibling list/search tools. It identifies the input type (profile or page URL) and is unambiguous.

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

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

It clearly implies the tool is for retrieving events for a specific profile/page via URL, providing clear context. However, it does not explicitly exclude alternatives like facebook_events_list or search tools, so it lacks exclusions.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, covering safety and data openness. The description adds the nuance that both URL and username are accepted (though the schema only mentions URL), which is a small behavioral detail. However, it does not mention authentication requirements, rate limits, or what happens if the profile is inaccessible. Given the annotation coverage, the description adds modest value, warranting a 3.

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, concise sentence that communicates the core action and input method without any filler. It front-loads the purpose and avoids unnecessary elaboration, making it highly efficient for an agent to parse.

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

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

The tool has a simple signature with two optional parameters and lacks an output schema. The description explains what it does and how to call it, but does not disclose the shape of the response (e.g., what profile fields are returned). While a profile getter typically returns standard fields, the absence of any indication about return content or potential errors (e.g., non-existent profiles) leaves a gap in completeness. Given the low complexity, a 3 is appropriate—it is functional but could be more informative.

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 parameters, both with descriptions. The tool description enriches the 'url' parameter by stating that a username is also acceptable, which is not captured in the schema's parameter description ('Facebook public profile or page URL'). This additional semantic guidance aids the agent in accepting username values, elevating it above the baseline 3.

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

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

The description clearly states the action ('Get') and the resource ('Facebook profile or Page'), and specifies the input method ('by URL or username'). It distinguishes this tool from sibling list tools like facebook_profile_posts_list and facebook_profile_photos_list by focusing on the core profile/page entity, making its 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 implies its usage context: it is the primary tool to fetch a Facebook profile or page's basic information. While it does not explicitly contrast with siblings, the tool name and surrounding siblings (e.g., facebook_profile_posts_list) make it clear that this is for the profile itself, not its lists. The mention of 'public' hints at access scope, but no explicit when-not or alternative routing is provided, so a slight deduction from 5 is warranted.

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

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

Annotations already mark the tool as readOnlyHint=true and openWorldHint=true. The description adds useful cost-related behavior: 'Credits: 1 base; hostMedia=true adds +2 per hosted asset (up to 24 / 49 max). Failed assets are not surcharged.' This discloses pricing and failure handling beyond what annotations provide, though it does not mention pagination 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?

The description is two sentences, front-loaded with the core purpose, then concisely conveying cost details. Every sentence adds value; there is no fluff or redundancy.

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

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

For a listing tool with three parameters (all documented in schema) and no output schema, the description covers the purpose, input requirement (URL), and essential cost behavior. It does not explain return format, but since it is a list tool, that is likely self-evident. The hostMedia behavior and credit structure are sufficiently explained.

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 in the schema. The description adds extra meaning for 'hostMedia' by explaining the credit surcharge and up-to limits, which is not in the schema. This contextual cost information helps the agent decide on parameter values.

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

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

The description states a specific verb ('List') and a clear resource ('photos from a Facebook profile or Page'), matching the tool name and title. It unambiguously identifies what the tool does and is easily distinguishable from other facebook_* tools like facebook_profile_posts_list or facebook_post_get.

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

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

The description gives clear context: it accepts a profile or page URL and lists photos. There are no competing tools for listing Facebook profile photos, so exclusions or alternatives are not needed. The input requirement is clearly stated, providing enough guidance for when to use it.

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 provide readOnlyHint and openWorldHint, but the description adds valuable context: the credit cost structure (1 base, +2 per hosted asset) and the behavior that failed assets are not surcharged. This goes beyond annotations and helps the agent anticipate costs and 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 concise sentences with no filler. The primary purpose is front-loaded, then cost details are provided. Minimal but complete.

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

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

For a read-only list tool with no output schema, the description covers input selection, cost behavior, and the hostMedia option. Pagination is not mentioned, but the cursor parameter is in the schema, so the agent can infer it. 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%, so parameters are fully documented. The description adds meaning by clarifying that url and pageId are alternatives for specifying the target, and explains the hostMedia effect (hosts for 90 days, adds cost). This enhances the schema.

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

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

The description clearly states 'List posts from a Facebook profile or Page' – a specific verb and resource. It distinguishes from sibling tools like facebook_group_posts_list and facebook_profile_photos_list by explicitly mentioning profile/Page scope. Also clarifies the input methods (URL or page 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?

It specifies that this tool is for profiles or Pages, which implicitly distinguishes it from group posts or other list tools. It also explains the URL/pageId alternatives. However, it doesn't explicitly say when not to use it or name alternative tools, but the scope is clear enough.

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

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

The description goes beyond the readOnlyHint annotation by detailing credit costs: '1 base; hostMedia=true adds +2 per hosted asset (up to 24 / 49 max). Failed assets are not surcharged.' This provides operational context such as cost implications and limits, which is valuable for an agent managing budgets.

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

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

The description is concise with two sentences: first states purpose and input, second lists credit costs. It front-loads the core purpose, then provides essential operational details 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?

The description covers the tool's purpose, input, and costing, but lacks details about the response structure or error handling. Since there is no output schema, an agent might need to infer the return format. However, for a list tool with clear parameters and read-only annotation, this is a minor gap; a mention of pagination or response fields would improve completeness.

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

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

Schema description coverage is 100%, so all parameters are documented. The description adds cost and limit semantics for hostMedia ('adds +2 per hosted asset'), enriching its meaning beyond the schema's 'hosts source media for 90 days' with actionable pricing details.

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

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

The description clearly states it 'List Reels from a Facebook profile or Page,' specifying the verb, resource, and content type. This distinguishes it from sibling tools like facebook_profile_posts_list or facebook_profile_photos_list which target different content types.

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

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

No explicit guidance on when to use this tool versus alternatives. It does not name facebook_profile_posts_list or instagram_profile_reels_list as alternatives, nor does it state conditions for choosing one over the other. The context is implied by the name but not articulated.

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 bar for additional behavioral disclosure is lower. The description adds valuable details about pagination via cursor and the one-month-per-request limit, which are beyond the schema. It does not contradict annotations.

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

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

The description is three concise sentences with no fluff. The main purpose is front-loaded, and pagination guidance is included efficiently.

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 behavior and pagination but does not describe the structure of the returned list (e.g., what fields each activity item contains). Without an output schema, this is a gap for an agent that needs to process the results. It is adequate for basic invocation but incomplete for deep data 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 the schema documents all parameters. The description mentions accepting a username and returning a list, but does not add significant semantic meaning beyond what the schema already provides. 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 ('List'), resource ('GitHub profile activity'), and adds clarifying details ('recent public activity', 'one month per request'). This clearly distinguishes it from sibling tools like github_profile_contributions_get or github_profile_repositories_list, which focus on different aspects of a GitHub 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 implies usage for retrieving a profile's activity timeline but does not explicitly mention alternatives or when-not-to-use conditions. It provides context like 'one month per request' and pagination, but does not route to sibling tools for different data needs (e.g., followers, repositories).

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 doesn't need to cover safety. It adds that it accepts a username and year, but does not describe return format or other behavioral traits. Given the annotations, this is adequate but not rich.

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

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

The description is two concise sentences, front-loaded with the resource and purpose. No wasted words, all information is relevant and efficiently delivered.

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

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

There is no output schema, and the description does not explain what the returned contribution graph contains (e.g., daily contributions, total count). However, the concept of a contribution graph is widely known, and the openWorldHint suggests the agent should expect flexible data. Still, a note on response structure would improve completeness.

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

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

Schema description coverage is 100%, with both parameters fully described (handle with length constraints and default, year with min/max and default). The description adds no additional meaning beyond what the schema already provides, so it meets the baseline without enhancing 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 action ('Get') and the specific resource ('contribution graph') for a GitHub profile, with the optional year context. It is specific enough to differentiate from sibling tools like github_profile_get (profile info) and github_profile_activity_list (activity feed).

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

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

The description implies usage for retrieving contribution graphs for a specific year, which is clear context. However, it does not explicitly mention alternative tools or when not to use this tool, so it lacks exclusions but provides enough directional 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 indicate readOnlyHint and openWorldHint, so the description need not repeat that. It adds the note about returning a list and using cursor for pagination, which is helpful but not extensive.

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 that front-load the purpose and add the pagination note. No filler words; each 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 list tool with no output schema, the description covers the core purpose and pagination. It doesn't describe the shape of the list items, but that may be acceptable given the tool's simplicity and existing schema 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 input schema already documents both parameters with descriptions; schema coverage is 100%. The description adds a redundant note about accepting a username and clarifies pagination behavior, but doesn't add substantial new 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 clearly states the verb 'List' and the resource 'followers for a GitHub profile', which is specific and unambiguous. It does not explicitly differentiate from sibling tools like github_profile_following_list, but the name and wording make the purpose 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?

No guidance is provided on when to use this tool instead of alternatives such as following lists or profile details. The description only states the action without contextual cues or exclusions.

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

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

Annotations already declare readOnlyHint=true, so the read-only nature is covered. The description adds that the tool 'Returns a list' and advises 'use cursor when paginated', which provides some behavioral context about the return type and pagination. However, it does not disclose the structure of list items (e.g., usernames, profile objects) or how to detect further pages beyond the cursor parameter. This provides moderate value beyond the annotations but is not rich.

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

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

The description is three short sentences with zero fluff. The core purpose is front-loaded, followed by input and return/pagination hints. Every sentence earns its place, making it highly efficient and scannable.

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

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

For a simple tool with two parameters and readOnly annotations, the description is mostly adequate but leaves a notable gap: the exact composition of the returned list. Since there is no output schema, the agent is left wondering whether the list contains usernames, full profile objects, or something else. The pagination hint is useful, but the missing return format detail reduces completeness.

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

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

Schema description coverage is 100%; both handle and cursor have clear descriptions. The description adds little beyond that: 'Accepts a username' restates the handle parameter, and 'use cursor when paginated' echoes the cursor's schema description. Since the schema already carries the full semantic weight, 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 states the verb 'List' with a specific resource 'accounts a GitHub profile follows', which clearly distinguishes it from the sibling tool github_profile_followers_list. The clause 'Accepts a username' further specifies the input, and the title reinforces the action. This is unambiguous and unique among many similar profile-related tools.

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

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

The description does not explicitly explain when to use this tool versus alternatives like github_profile_followers_list or github_profile_get. It only states the function without any context on selection criteria, prerequisites, or exclusions. The agent must infer usage from the name and title, which is not sufficient 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=true and openWorldHint=true, so the read-only nature is covered. The description adds the behavioral detail that it works for both users and organizations, which is not in the annotations. No side effects or auth requirements are mentioned, but given the annotations and tool simplicity, 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 short sentences that front-load the core purpose. The second sentence is somewhat redundant but not wordy. The structure is efficient and clear, though it could be tightened further.

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 one parameter and no output schema. The description mentions the scope (user or organization) and establishes it as a profile getter. It does not specify response fields, but for a profile getter this is often implicit. The annotations cover safety, making the description adequate 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% and the schema already describes the handle parameter, including the leading @ detail. The description's phrase 'Accepts a username' adds no new meaning beyond the schema. Since the schema fully documents the parameter, 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 and resource: 'Get a GitHub profile' for a user or organization. It clearly differentiates from sibling tools by naming the GitHub platform and the profile resource, distinguishing it from activity lists, contributions, and repositories tools.

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

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

Usage is implied: when you need the basic profile of a GitHub user or org. However, it does not explicitly mention alternatives like github_profile_repositories_list or github_profile_contributions_get, so there is no when-not-to-use guidance. The sibling list suggests this is the base profile getter, but the description alone does not clarify when to prefer it over related tools.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the description appropriately does not repeat that. It adds value by specifying return type ('Returns a list') and pagination behavior ('use cursor when paginated'), which goes beyond the schema. 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 tightly written sentences with no fluff. The main purpose is front-loaded, and the pagination hint is concise and actionable. Every word earns its place.

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

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

Given the tool is a simple read-only list with no output schema, the description covers the essential return type and pagination. It does not mention rate limits or response shape details, but those are not critical for a read-only list operation. The description is complete for an agent to call 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 all four parameters are fully documented in the schema. The description adds little beyond restating 'accepts a username', which is already in the handle parameter description. Baseline of 3 is appropriate since schema carries the semantic burden.

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

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

Description clearly states the verb 'list' and the specific resource 'pull requests authored by a GitHub user'. The sibling set includes github_profile_repositories_list, github_profile_followers_list, etc., so this definition distinctly identifies the operation without ambiguity.

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

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

The description implies usage by stating 'accepts a username' and 'returns a list' with pagination note. While it doesn't explicitly name alternatives like github_profile_repositories_list, the purpose is obvious from context. It lacks an explicit 'use when' but provides clear functional 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 state readOnlyHint and openWorldHint, so the description doesn't need to repeat that. It adds value by noting the return is a list and that pagination uses a cursor. This goes beyond annotations and clarifies expected behavior without 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 concise sentences with no fluff. The core action is front-loaded, and the pagination note is placed at the end. Every word contributes to the tool's description.

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

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

Given the tool's moderate complexity and full schema coverage, the description is adequate. It mentions returning a list and pagination, which covers the main runtime behavior. No output schema exists, but the return type (list) is stated. The description doesn't enumerate fields, but that's not required when the schema and annotations cover parameters and safety.

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 each parameter (handle, sort, type, direction, cursor) already documented. The description adds minimal extra semantic value beyond the schema, such as 'use cursor when paginated,' which is already implied by cursor's schema. Baseline 3 is appropriate because the description doesn't need to compensate for missing schema info.

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

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

States a specific verb and resource: 'List repositories for a GitHub user or organization.' This clearly distinguishes from sibling tools like github_profile_get, github_profile_activity_list, and github_repositories_get, which have different scopes. The mention of both user and organization covers the handle parameter's flexibility.

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 minimal guidance on when to use this tool. It says 'Accepts a username' and 'use cursor when paginated,' which addresses input and pagination, but does not explicitly contrast with alternatives like github_profile_activity_list or github_repositories_get. No when-to-use or when-not-to-use conditions are given.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, covering safety and external data access. The description adds the scoping detail of fetching a single repo by URL, which is not in annotations. It does not contradict annotations and provides sufficient clarity for a read operation.

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

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

The description is a single, front-loaded sentence with zero filler words. It states the action and target efficiently. No unnecessary elaboration.

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 single-get tool with one parameter and no output schema, the description adequately covers what it does and how to specify the target. The lack of return format details is acceptable given the low complexity and clear purpose. It is complete enough for an agent 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?

Schema description coverage is 100%: the 'url' parameter is fully documented as 'Full public GitHub repository URL.' The tool description merely says 'by URL' and adds no additional semantic detail beyond the schema. Baseline 3 is appropriate since the schema already explains the parameter fully.

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 ('get'), a resource ('single GitHub repository'), and a method ('by URL'). This clearly distinguishes it from sibling tools like github_profile_repositories_list (lists a user's repos) and github_trending_repositories_list (trending list). It is precise and unambiguous.

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

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

The description implies usage via 'by URL' – if you have a repository URL, use this tool. However, it does not explicitly state when to prefer it over alternatives, nor does it mention exclusions (e.g., not for listing). It lacks direct comparison with sibling tools, so guidance is only implied, not explicit.

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

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

The description discloses the return type ('Returns a list') and pagination behavior ('use cursor when paginated'), adding value beyond the readOnlyHint and openWorldHint annotations. It does not contradict annotations and provides useful operational detail for a likely read-only list endpoint.

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, concise sentence with a parenthetical about pagination. It front-loads the core action and scope, contains no redundant words, and efficiently conveys the essential 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 read-only list tool with two optional parameters and no output schema, the description covers the primary usage and pagination. It could benefit from describing the shape of the returned developer objects, but current coverage is adequate for correct invocation given the schema and annotations.

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

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

Schema description coverage is 100%, so both parameters (since and language) are adequately documented in the schema. The description only restates that these parameters exist ('for a language and time window') without adding new syntax, format, or interaction details, making the baseline 3 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 action ('List'), the resource ('trending GitHub developers'), and the key parameters ('for a language and time window'). It also distinguishes from the sibling github_trending_repositories_list by naming 'developers' explicitly, making the purpose unambiguous.

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

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

The description provides no guidance on when to use this tool versus alternatives, such as github_trending_repositories_list. It does not mention any conditions or exclusions, leaving the agent to infer that this is for developers rather than repositories, which is already evident from the name.

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

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

The annotations already declare readOnlyHint=true and openWorldHint=true, covering the safety profile. The description adds value by stating that the tool returns a list and advises using a cursor when the result is paginated. This gives the agent practical invocation guidance beyond what the annotations alone provide. 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?

The description is extremely concise: two sentences, both informative. The main action and filters are front-loaded, and the return type and pagination hint follow naturally. There is 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?

Given the tool's simplicity, the description covers everything an agent needs: it states what it does, the filters, the return type (list), and pagination handling. Since there is no output schema, the description appropriately explains the return value. Annotations cover the safety profile, so nothing else is missing for a filtered-list read operation.

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

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

Schema description coverage is 100%, so all three parameters (since, language, spokenLanguageCode) are already documented in the schema. The description briefly mentions 'language and time window' which maps to existing parameters but adds no additional syntax or behavioral details. Baseline 3 is appropriate because the schema carries the full 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 action (List), the resource (trending GitHub repositories), and the primary filters (language and time window). This is specific enough to distinguish it from sibling tools like github_trending_developers_list (which lists developers) and github_profile_repositories_list (which lists a specific user's repositories), so an agent can immediately understand its purpose.

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

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

The description implies usage: when you need trending repositories, you use this tool. However, it does not explicitly mention alternatives or when not to use it. Since the sibling list includes similar trending tools, a note like 'use for trending repositories; for trending developers use github_trending_developers_list' would improve clarity. This is implied usage, not explicit 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 provide readOnlyHint=true and openWorldHint=true, covering the safety profile. The description adds only that the URL must be 'public' and the result is 'single', but does not disclose response format, error behavior, or any other operational details. This is adequate given 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, compact sentence with no waste. It front-loads the action and the key input requirement, making it easy to parse quickly.

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

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

For a simple get-by-URL tool with one parameter and read-only annotations, the description is nearly complete. It does not describe the return payload, but the tool name and the presence of sibling ad-library get tools (e.g., facebook_adLibrary_ad_get) imply a standard retrieval response. The lack of an output schema shifts some burden, but overall the context is sufficient.

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

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

The schema already documents the url parameter with the note 'Public Google Ad Transparency URL for the creative.' The description's phrase 'by public Ad Transparency URL' essentially repeats the schema, adding negligible new meaning. With 100% schema coverage, a baseline of 3 is appropriate.

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

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

The description precisely names the verb ('Get'), the resource ('Google Ad Transparency creative'), and the input discriminator ('by public Ad Transparency URL'). It clearly distinguishes from sibling tools like google_adLibrary_advertisers_search or google_company_ads_list, and from ad-library fetchers on 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 description implies the tool is for fetching a known ad by URL, but it does not explicitly state when to use this versus the sibling search or list tools. An agent must infer that this tool is appropriate only when a public URL is already available.

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's safety profile is covered. It adds the important behavioral detail that the result is a list and that pagination uses a cursor, which is beyond what annotations or the schema provide. This is genuinely useful context for an agent.

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

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

The description is two short sentences, front-loaded with the primary action. It includes a useful note about cursor pagination without any fluff. Every sentence earns its place, and the length is appropriate for the tool's complexity.

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

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

Given the lack of an output schema, the description does mention the return is a list and cursor-based pagination, which is helpful. It covers the main functional aspects. It could potentially detail what fields are returned, but for a simple search tool with well-defined parameters, it is reasonably complete.

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

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

Schema coverage is 100%—both query and region have descriptions in the schema. The description repeats that it accepts an advertiser name, which does not add meaningful value beyond the schema. However, it does not introduce any conflicting or confusing parameter info, so it meets 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 clearly specifies the action (search), the resource (Google Ad Transparency advertisers), and the criterion (by name). It also notes the return type (list) and pagination approach, distinguishing it from siblings like google_adLibrary_ad_get and google_company_ads_list which have different purposes.

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 that it accepts an advertiser name, implying a use case, but does not explicitly contrast with alternative tools or provide when-to-use/when-not-to-use guidance. It lacks explicit exclusionary language that would help an agent decide between this and similar search tools in the sibling list.

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

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

The description adds behavioral notes about pagination via cursor and that it returns a list, which complements the readOnlyHint and openWorldHint annotations. It does not contradict the annotations, but it does not disclose rate limits, authentication, or return structure details.

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 core purpose is front-loaded, and the essential details (domain/advertiser id, cursor pagination) are conveyed 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?

Given the large number of optional parameters (9) and the absence of an output schema, the description is minimal. It does not mention the available filters (topic, region, platform, dates) though these are documented in the schema, and it does not describe the returned list's contents beyond being a list. Adequate but could be more helpful.

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 parameters with descriptions. The description reinforces the primary choice between domain and advertiserId and mentions cursor usage, but it does not add meaning beyond what the schema already documents for each parameter.

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

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

The description states a specific verb 'List' and resource 'ads' within 'Google Ad Transparency', and clarifies it accepts a domain or advertiser id. This clearly distinguishes it from sibling tools like google_adLibrary_ad_get (single ad) and google_adLibrary_advertisers_search (advertiser search).

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

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

The description implies usage when you have a company domain or advertiser id, but it does not explicitly mention alternatives or when not to use this tool. It lacks exclusions or comparison to related Google ad tools, so guidance is left 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 mark the tool as readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds value by specifying the behavioral trait of returning the ancestor chain to the root story, which is not in the annotations. However, it does not disclose potential edge cases (e.g., invalid id, non-comment id) or the exact return structure, so it falls short of rich disclosure.

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

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

Two sentences, zero fluff. The first sentence front-loads the core action and result; the second clarifies the input. Every word earns its place, and the structure is optimal for quick comprehension.

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 tool with one parameter and no output schema, the description adequately conveys what is returned (comment plus ancestor chain). It does not mention error handling or output format, but those are minor gaps given the tool's low complexity. Overall, it is sufficiently complete 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?

The schema description for the single parameter id already states 'Hacker News comment id' with 100% coverage. The description's phrase 'Accepts a comment id' simply reiterates the schema without adding additional semantics. Since schema coverage is high, the baseline is 3, and no extra meaning is provided.

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

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

The description states a specific verb and resource: it gets a Hacker News comment including its ancestor chain to the root story. This clearly differentiates it from generic item retrieval (hackernews_item_get) or comment listing (hackernews_story_comments_list) and leaves no ambiguity about the tool's function.

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

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

The description implies when to use this tool: when you need the full ancestor chain of a comment, not just the comment itself. However, it does not explicitly exclude alternatives like hackernews_item_get for single-item retrieval, so it lacks explicit 'when-not' guidance. Still, the context is clear and sufficient for an agent to infer the appropriate use case.

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 that it returns a list and hints at pagination ('use page/pageSize when paginated'), which provides some behavioral context beyond the annotations, but does not elaborate on response structure. 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 core action and feed types are front-loaded, and the pagination note is placed logically. 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 tool with no output schema, the description is thin on return value details. It says 'Returns a list' and hints at pagination, but does not describe item fields or the pagination contract (e.g., hasMore/nextPage) that the schema's page description references. The open-world annotation suggests variability, but the description does not clarify what a consumer should do with the returned items. It is minimally adequate given the schema's pagination hints, but leaves room for improvement.

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 fully documents all four parameters with descriptions (feed enum, page, limit, pageSize). The description does not add additional semantic meaning beyond the schema; it only repeats the existence of pagination. Baseline 3 applies because schema 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 clearly states the verb 'List' and the resource 'Hacker News feed', and enumerates the exact feed types (top, new, best, ask, show, jobs). This distinguishes it from sibling search or item-specific tools like hackernews_search_list or hackernews_story_get, even without explicit comparison.

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

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

The description gives no guidance on when to use this tool versus alternatives such as hackernews_search_list, hackernews_story_get, or other listing tools. It does not mention exclusions or preferred contexts, leaving the agent to infer when browsing feed categories is appropriate.

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 readOnlyHint=true and openWorldHint=true already communicate safety and openness. The description adds nothing about return format, error conditions, or what constitutes an 'item'. It merely restates the function without enriching the behavioral context beyond what annotations provide.

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

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

The description is a single, front-loaded sentence with no filler. It communicates the core action and input immediately, making it easy for an agent to parse quickly.

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 full schema coverage and annotations, the description is nearly sufficient. The only gap is that it does not clarify what kind of item is returned (story, comment, etc.), but given the low complexity, this is a minor omission.

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

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

Schema description coverage is 100% for the single id parameter, which is described as 'Hacker News item id'. The tool description adds no further meaning, but since the schema already documents the parameter adequately, 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 action ('Get') and the resource ('a Hacker News item by id'). It is unambiguous but does not differentiate from sibling tools like hackernews_story_get or hackernews_comment_context_get, which also fetch HN content. The verb and resource are specific enough for basic identification.

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

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

No guidance is provided on when to use this tool versus the many hackernews_* siblings. There is no mention of whether this returns stories, comments, or other items, nor any hint about when to prefer it over hackernews_story_get or hackernews_maxitem_get. The agent must infer usage from the name alone.

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=true and openWorldHint=true, so the safety profile is covered. The description adds behavioral details beyond that: it returns a list (not a single item), supports pagination via page/pageSize, and clarifies that it fetches only top-level jobs from the thread. This goes beyond the annotations, though it does not detail output structure 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, front-loaded with the core function and pagination note. No filler, no redundancy. The description is appropriately sized for the tool's simplicity.

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

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

For a list tool with no required parameters and no output schema, the description explains the thread scope, pagination, and return type. It doesn't disclose the structure of each job listing, but given the simplicity and the presence of readOnly/openWorld annotations, it is sufficiently complete for an agent to call it correctly. Minor gap: no explicit mention of what fields each job row contains.

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

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

Schema description coverage is 100%, so all four parameters have descriptions. The tool description only reiterates pagination and month selection, adding no new semantic info beyond what the schema already provides. Per the rubric, this earns the baseline score of 3.

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

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

The description clearly states the verb and resource: 'List top-level jobs from the monthly Hacker News Who is Hiring thread'. It also specifies the optional month and distinguishes this tool from generic Hacker News listing tools like hackernews_feed_list or hackernews_story_comments_list by naming the specific thread type.

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

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

The description provides clear context on when to use this tool: specifically for the monthly Who is Hiring thread, with an optional month parameter to pin a particular thread. It does not explicitly name alternatives or exclusions, but the purpose is unambiguous enough that an agent would know to choose this tool over generic Hacker News feed or comment listers.

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 the safety profile. The description adds that it returns the 'current largest' id, implying dynamism, but does not describe return format, pagination, or any edge cases. Since annotations carry the main behavioral disclosure, the description adds minimal but non-contradictory context.

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

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

The description is a single, precisely worded sentence with no superfluous information. It is front-loaded with the action and resource. Perfectly 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 simple getter with no parameters, no output schema, and annotations already present, the description is complete. It states exactly what the tool returns and implies it is read-only. Nothing an agent needs to invoke it correctly is missing.

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

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

There are zero parameters, and the schema coverage is 100% (empty schema). Per rubric, baseline is 4 for no parameters. The description does not need to explain parameters, and it doesn't add or omit anything relevant.

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

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

The description uses a specific verb ('Get') and clearly identifies the resource ('current largest Hacker News item id'). It unambiguously distinguishes this tool from Hacker News siblings like hackernews_item_get (fetches a specific item) or hackernews_feed_list (lists stories). The purpose is fully 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?

No guidance is given on when to use this tool versus alternatives, nor any context for its typical application (e.g., polling new content, tracking the latest item). The description is purely functional and provides no exclusions or alternative hints. An agent would have to infer usage.

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

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

Annotations already declare readOnlyHint=true, so the description adds little beyond that. 'Returns a list' is trivial, and the pagination hint is already fully specified in the schema. No additional behavioral traits (e.g., result format, error conditions, rate limits) are disclosed.

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

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

Two short sentences, front-loaded with the core purpose, and no unnecessary words. Every sentence earns its place, making it highly concise 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 16 parameters and no output schema, the description is insufficient. It implies keyword-only search, but the tool supports filtering by author, domain, type, date range, and more. An agent relying on this description would miss the full capability and might incorrectly assume query is always required.

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 all 16 parameters documented. The description merely repeats keyword and pagination without adding any new meaning or clarifying parameter interplay (e.g., that query can be omitted when author/domain/url is set).

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

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

The description clearly states 'Search Hacker News by keyword', identifying the verb (search), resource (Hacker News), and a specific scope (keyword). This distinguishes it from the many other search tools for other platforms 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?

The description gives no guidance on when to use this tool versus alternatives, no context, and no exclusions. It simply states the action without helping the agent decide when to prefer it over other Hacker News search or list 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 doesn't need to re-state safety. It adds value by noting the result is a list and that pagination via cursor is supported. This directly informs callers about the return type and how to navigate multiple pages, which is beyond 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?

The description is two sentences with zero waste. It front-loads the core purpose and includes the key operational hint about pagination. Every sentence earns its place, making it easy for an agent to parse quickly.

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

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

The tool has no output schema, so the description bears the burden of explaining the return value. It states 'Returns a list' but does not describe the fields or structure of the comment items, nor any error behavior. Given the simplicity of the operation and the schema's detailed parameter descriptions, it is adequate but could be more informative about the actual list contents.

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 id, limit, and cursor thoroughly. The description adds only marginal emphasis ('by id', 'use cursor when paginated') which partly reinforces but does not significantly extend the schema. Baseline 3 is appropriate as the schema carries the semantic 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 states a clear verb and resource: 'List comments on a Hacker News story by id.' This precisely distinguishes it from siblings like hackernews_item_get (which fetches a single item) and hackernews_comment_context_get (which gets context around a comment). The phrase 'by id' and the schema's 'comment tree' further clarify the scope.

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

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

The description implies usage for listing comments on a story and warns to use cursor when paginated, which is helpful. However, it does not explicitly state when not to use this tool or mention alternatives on the same platform (e.g., hackernews_item_get for retrieving a single comment). The guidance is clear in context but lacks explicit exclusions or comparisons.

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 carries a low burden for safety disclosure and does not contradict them. The description adds little beyond the literal fetch — no mention of what a non-existent id returns or any edge behavior — but this is acceptable 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?

A single compact sentence that is front-loaded and contains zero filler. Nothing could reasonably be cut, and 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 one-parameter read-only fetch with full schema coverage and safety annotations, the description is adequate. It omits details like not-found behavior and response shape, but given the tool's simplicity and the absence of an output schema requirement, these are minor gaps.

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

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

Schema description coverage is 100%; the schema fully documents the id parameter. The description's 'by id' roughly restates the schema rather than adding new semantic detail, which is fine but earns only the baseline for high-coverage cases.

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

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

Description states a specific verb and resource ('Get a Hacker News story by id'), which is clear on its own. However, it does not differentiate from the near-identical sibling hackernews_item_get — the HN API's generic item type versus the story subtype — leaving an agent to guess whether these overlap or differ in 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?

No guidance on when to choose this tool over alternatives. With siblings like hackernews_item_get, hackernews_feed_list, and hackernews_story_comments_list, there is no explicit when-to-use or when-not-to-use direction, so the choice between story_get and item_get is left entirely 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?

The description adds that it returns item IDs and usernames, and the term 'recently changed' implies a time-bound feed. It does not contradict the readOnlyHint and openWorldHint annotations, but it doesn't clarify what 'recently' means (e.g., last hour, last day) or whether there are limits. The annotations carry the read-only safety profile, so this is acceptable but not rich.

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

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

A single, clear sentence that front-loads the primary purpose. No fluff, and every word adds value.

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

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

For a zero-parameter tool with annotations covering read-only and open-world behavior, the description is sufficient: it states what is returned (IDs and usernames) and the temporal scope. It could be more specific about the time window or list format, but the overall complexity is low and nothing critical is missing.

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

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

The tool has zero parameters, so baseline 4 applies. The description doesn't need to explain parameters, and it doesn't introduce any ambiguity.

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

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

The description states a specific action ('Get') and a clear resource ('recently changed Hacker News item ids and usernames'), so an agent can tell it's a retrieval tool. However, it doesn't explicitly differentiate from siblings like hackernews_feed_list or hackernews_item_get, relying on the name to imply the update-focused 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?

There is no guidance on when to use this tool versus the many hackernews_* siblings. No mention of prerequisites, use cases, or explicit exclusions, leaving the agent to infer from the name alone.

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 scope. The description adds that it returns a list and hints at pagination ('use page/pageSize when paginated'). However, it does not elaborate on error behavior, rate limits, or what happens for invalid usernames, so it adds only modest value beyond 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 highly concise—three short clauses that front-load the core purpose, then add return type and pagination notes. There is zero waste, and every piece of information 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 list tool, the description is adequate but not complete. It doesn't differentiate from sibling user-related lists, doesn't mention that 'limit' is preferred over 'pageSize', and doesn't describe the list items' content beyond being comments. With no output schema and a simple use case, a 3 reflects that it covers the essentials but leaves some contextual gaps.

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

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

Schema coverage is 100%, with all parameters described in the input schema. The description repeats 'username' and adds a pagination hint, but it does not clarify the preference for 'limit' over 'pageSize' (as mentioned in the schema) or provide any additional semantic context beyond what the schema already offers. 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 ('List'), resource ('a Hacker News user's comments'), and ordering ('newest first'). It is unambiguous and easily distinguished from sibling tools like hackernews_user_submissions_list or hackernews_story_comments_list by the clear 'user's comments' phrasing.

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

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

There is no guidance on when to use this tool versus alternatives. It does not mention exclusions, prerequisites, or why an agent should choose this over hackernews_user_favorites_list or other user-related list tools. The usage context is only implied by the name and description.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the read-only nature is disclosed. The description adds the pagination detail: 'use page when paginated; 1-based,' which is useful and not redundant. However, it does not elaborate on any rate limits, error conditions, or the structure of the returned list beyond saying 'Returns a list.' Given the annotations cover the main behavioral trait, a 3 is appropriate.

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

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

The description is a single sentence that packs the essential information: what the tool does and a critical pagination note. There is no fluff or repetition. It is front-loaded with the purpose and keeps the pagination caveat in a parenthetical, making it easy to scan. 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 a simple read-only list operation. Annotations already convey openness and read-only safety. The schema fully defines parameters, including defaults and billing notes. The description covers pagination and return type. Given the lack of an output schema, the description could optionally detail the list item fields, but for a typical favorites list, the absence is not a critical gap. Overall, 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?

The input schema already provides full descriptions for both parameters: username is 'Hacker News username (case-sensitive)' and page is 'One-based HTML favorites page number. Default: 1. Each page bills 1 credit.' With 100% schema coverage, the description adds no extra semantic value beyond what the schema states. It only rephrases the pagination hint. Thus, the baseline of 3 is justified.

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 'List favorites for a Hacker News user by username.' It specifies the action (list), the resource (user favorites), and the parameter (username). This distinguishes it from sibling Hacker News tools like hackernews_user_comments_list and hackernews_user_submissions_list, which target different content types. The purpose is unambiguous.

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

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

The description provides no explicit guidance on when to use this tool versus alternatives such as hackernews_user_comments_list or hackernews_user_submissions_list. It does not mention exclusions, prerequisites, or specific scenarios. The only hint is the name and the mention of 'favorites,' but the description itself offers no decision support for an agent choosing among the many user-content list 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, so the read-only nature is covered. The description adds no additional behavioral context, such as authentication requirements, rate limits, or what the profile contains. It contributes no value beyond what the annotations and the verb 'Get' already 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 a single, clear sentence that is perfectly concise and front-loaded. Every word earns its place, with no fluff or redundancy.

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

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

For a simple get operation with one parameter and no output schema, the description is minimally adequate. It names the resource but does not hint at what fields the profile contains or any edge-case behavior. It's sufficient for an agent to know it fetches a user profile, but it lacks depth that more complex tools would require.

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

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

Schema coverage is 100%, with the username parameter already described as 'Hacker News username (case-sensitive)'. The tool description adds no further detail about the parameter, so it doesn't enhance schema semantics beyond 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 clearly states the action ('Get') and the resource ('Hacker News user profile'), with the parameter 'username' implied. It is unambiguous and distinguishes from sibling tools that fetch comments or submissions, though it doesn't explicitly name alternatives.

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

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

No guidance is provided on when to use this tool versus related Hacker News tools like hackernews_user_comments_list or hackernews_user_favorites_list. The description simply states what it does, leaving the agent to infer usage context without explicit exclusions or alternatives.

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

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

While annotations declare readOnlyHint=true and openWorldHint=true, the description adds meaningful behavioral facts: it lists specific content types (stories, polls, jobs), sorting order (newest first), and pagination hints (use page/pageSize). This goes beyond the safety profile conveyed by annotations and gives the agent useful operational expectations. It does not discuss error handling or rate limits, but that is minor given the simple read-only nature.

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 efficient: three short sentences deliver the core purpose, content scope, and pagination hint with minimal fluff. The main action is front-loaded. It loses a point for using 'page/pageSize' instead of the schema-preferred 'limit', which introduces slight imprecision, but overall it is well-structured and easy 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 simple read-only list tool with no output schema, the description covers the essential operational aspects: what is returned, order, and pagination. It does not detail the exact return structure, but that is expected without an output schema. The lack of explicit comparisons to sibling tools is a minor gap, but overall the information is sufficient 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%, so the baseline is 3; the description adds no additional meaning beyond what the schema already provides for parameters. It mentions 'page/pageSize' but omits the preferred 'limit' parameter, and slightly conflicts with the schema's deprecation note on pageSize. It does not clarify or enrich parameter usage, so it neither adds value nor detracts significantly, staying at the baseline.

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

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

The description states a specific verb ('List') targeting a clear resource: a Hacker News user's 'stories, polls, and jobs' with a defined order ('newest first'). This distinguishes it from sibling tools like hackernews_user_comments_list or hackernews_user_favorites_list by naming the content types explicitly. The purpose is unambiguous and actionable.

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 context by naming the resource type (stories, polls, jobs) but does not explicitly contrast with alternatives. It never says 'use this for submissions, not comments' or mentions sibling tools. The differentiation relies on the tool name and sibling naming patterns rather than explicit guidance, so it meets the 'implied usage' level but not a clear 'when/when-not' directive.

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

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

Annotations already disclose readOnlyHint=true and openWorldHint=true, so the base bar is lower. The description adds valuable behavioral context: it notes that Instagram may not always expose all metadata ('when Instagram exposes them') and explains pagination handling. 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 with no filler. The core purpose is front-loaded, and the pagination note is practical. There is a minor grammatical typo ('a audio id' instead of 'an audio id'), but it does not detract from clarity. Every word earns its place.

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