Social Fetch

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

Annotations already declare readOnlyHint=true and openWorldHint=true, but the description adds no behavioral context beyond restating the request. It does not mention what the response contains, whether the returned 'page' is full or paginated, or any scraping/rate-limit behavior. Since it adds nothing over the structured hints, it falls below the bar.

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?

This is a single sentence with no filler, and the core action and input are front-loaded. It earns every word and is appropriately sized for a straightforward getter.

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 five parameters are fully documented in the schema and the purpose is clear, but there is no output schema and the description does not characterize the return value or pagination behavior despite the cursor parameter. For a simple read-only fetch this is adequate, but it leaves some ambiguity about what 'page' means as a result.

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 five parameters. The description adds no parameter-level insight beyond the schema—'by URL' merely echoes the url property description. Baseline 3 is appropriate because the schema does the heavy lifting.

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

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

The description names the resource ('creator Amazon Shop storefront'), the action ('Get'), and the key input ('by URL'), so an agent can tell it apart from the many other *_get tools by resource. It is clear but generic—'Get' does not specify whether the result is raw HTML or structured storefront data—so it stops short of a top-tier purpose statement.

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 only usage signal is implied: call this when you have a public Amazon Shop storefront URL. There is no explicit when-to-use/when-not-to-use guidance, no alternatives, and no note about cases that should route elsewhere (e.g., Amazon product pages vs creator storefronts).

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 core behavioral safety profile is covered. The description adds that lookup happens by id or URL, which is useful input scoping, but it does not disclose auth needs, rate limits, or return behavior. No contradiction with annotations.

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

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

The description is a single concise sentence that front-loads the operation and input options. Every word contributes: 'Get', 'Apple Music album', 'by id or album URL'. There is no redundant or filler content.

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

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

For a simple lookup tool, the description is mostly adequate: the schema documents all five parameters and annotations cover read-only/open-world behavior. However, it does not clarify that one of url or albumId should be supplied even though both are marked optional in the schema, and it says nothing about the return shape, leaving some ambiguity for an agent deciding how to invoke it.

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

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

Schema description coverage is 100%, and the url and albumId parameters already have descriptions. The description's 'by id or album URL' essentially restates those schema entries without adding extra meaning about whether one is required, whether they are mutually exclusive, or how they relate to the required context and llm_model parameters.

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

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

States a specific verb ('Get'), resource ('Apple Music album'), and input criteria ('by id or album URL'). It clearly identifies what the tool does, though it does not explicitly differentiate it from siblings like appleMusic_track_get or appleMusic_search_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 implies this tool should be used when the agent already has an album id or URL, but it provides no explicit when-to-use guidance, exclusions, or alternatives. The sibling list includes closely related tools such as appleMusic_search_list and appleMusic_track_get, but the description never mentions them.

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

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

The annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds the detail that lookup is by id or URL, but it does not disclose behavior such as what happens when neither identifier is provided, whether one is required, or how not-found cases are handled. No contradiction with annotations.

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

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

The description is a single efficient sentence with no filler. It front-loads the core action and the two accepted identifier forms, earning its place entirely.

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 lookup, the description is mostly adequate, but it leaves an important ambiguity: the input schema marks both artistId and url as optional, while the description implies one is needed. It also does not clarify whether exactly one must be supplied or what the response contains, especially since there is no output schema.

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

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

Schema description coverage is 100%, so the schema fully documents url and artistId as optional parameters. The description's 'by id or artist URL' slightly reinforces the purpose of these parameters but does not add meaningful detail beyond what the input schema already states.

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

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

The description clearly names the verb ('Get'), the resource ('Apple Music artist'), and the input forms ('by id or artist URL'). It is unambiguous against sibling tools like appleMusic_album_get and appleMusic_track_get, though it does not explicitly name a sibling to distinguish itself from.

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 that this tool is appropriate when the agent has an artist id or URL, but it does not explicitly state when to prefer this over appleMusic_search_list or other artist lookups (e.g., spotify_artist_get). No exclusions or alternative-routing guidance is provided.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, covering the safety profile. The description adds the useful behavioral note about returning a list and using a cursor when paginated, which goes beyond the annotations but does not discuss rate limits, result limits, or auth requirements.

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, each earning its place: one states the core action and resource, the other states the return shape and pagination behavior. No filler or redundant restating of the title.

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/search tool, the description communicates the core function, the return type, and pagination handling, which are the main things an agent needs beyond the schema. It does not describe the exact result payload, but in this case the absence of an output schema is partially mitigated by the simplicity of a search-list result.

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 five parameters including query, context, llm_model, type, and conversation_id. The description adds no parameter-specific meaning beyond the keyword concept already covered by the query field, so the baseline score applies.

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

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

The description states a specific action — searching the Apple Music catalog by keyword — and notes that it returns a list. It clearly reads as a search/list tool rather than a direct getter, though it does not explicitly name any sibling tool for 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 implies usage for keyword searches of the Apple Music catalog versus direct lookups via sibling get tools, but it does not state when to prefer this tool over appleMusic_album_get, appleMusic_track_get, or other search alternatives. The pagination note gives some operational guidance but not selection 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 safety profile is covered. The description adds the id/URL retrieval mechanism but does not disclose behavior when both identifiers are supplied, when neither is, or what happens for a nonexistent track — the weak optionality of both lookup fields makes this ambiguity material.

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 9-word sentence with zero filler. The verb and resource are front-loaded, and every word carries 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?

For a low-complexity get tool with strong schema coverage and safety annotations, the description is mostly adequate, but with no output schema it omits any hint of what the response contains. It also leaves unresolved how to choose between id and URL when both are marked optional, which is a genuine completeness gap.

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

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

Schema description coverage is 100%, so the schema fully documents url, trackId, context, llm_model, and conversation_id. The description's 'by id or track URL' marginally reinforces that trackId and url are the two lookup keys, but adds no semantics beyond what the schema already states.

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

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

States a specific verb ('Get') and resource ('an Apple Music track'), plus the two lookup modes ('by id or track URL'). The platform+resource combination clearly differentiates it from sibling track getters like spotify_track_get and soundcloud_track_get, and the identifier-based retrieval distinguishes it from appleMusic_search_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 'by id or track URL' phrasing implies this tool is for retrieving a known, specific track rather than discovering one, but it never says so explicitly and names no alternatives such as appleMusic_search_list for when an ID is unavailable. No exclusions or when-not-to-use guidance is provided.

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

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

The read-only and open-world annotations already convey the safety profile, and the description adds that the returned account is scoped to the current session. It doesn't disclose behavior when no authentication is present or the exact shape of the account object, but no contradiction with annotations exists.

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

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

A single, well-formed sentence with no verbiage and the key action front-loaded. This is appropriately concise for a trivial whoami 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?

No output schema exists, so the description's mention of 'authenticated API account' is the agent's only handle on the return value. For such a simple tool this may prove suficient, but it leaves the exact response fields and edge cases (e.g., no session) implicit.

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% — all three parameters (context, llm_model, conversation_id) have detailed descriptions. The tool description itself contributes no additional parameter context, matching the baseline for a fully documented 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 names a specific verb and resource — 'get the authenticated API account' — and scopes it to the current session. This makes the tool's purpose unmistakable and clearly distinguishes it from the many platform-content getters 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?

No explicit instructions on when to use this tool or when to prefer a sibling are provided. Since no other tool in the sibling list handles authentication identity, the usage is reasonably implied by the name and description, but this falls short of 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 declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds the useful context that this is for checking remaining credit before large metered operations, but it does not add further behavioral details such as whether the call itself consumes credit, how fresh the balance is, or how the result is structured.

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

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

The description is one sentence, front-loaded with the core purpose, and contains no filler. Every word contributes to the tool's intent and usage timing.

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 full schema coverage, this is nearly complete: it states the purpose, when to call it, and implies the returned value is the remaining credit balance. The absence of an output schema means a slightly clearer statement of result format could help, but the tool's function is straightforward enough 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%, and the schema already documents context, llm_model, and conversation_id thoroughly. The description adds no parameter-level meaning, which is acceptable given 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 uses a specific verb ('Get') and resource ('remaining credit balance'), and adds the relevant context of running before large batches of metered tools. It clearly distinguishes this from the many sibling get tools by focusing on billing/credit state.

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

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

It explicitly states when to use the tool: before running large batches of metered tools. There are no obvious sibling alternatives to exclude, so the lack of an explicit 'when not to use' is not a major 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 car r readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds only the by-URL retrieval scoping and does not contradict the annotations. It contributes no context on auth requirements, error behavior for deleted/private posts, or output format, but with annotation coverage the bar is lower and the lack is a minor gap, not a failure.

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, 'Get a single Bluesky post by URL,' with zero waste. The primary verb, resource, scoping qualifier, and mechanism are all 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 low-complexity read-only fetch with full schema coverage and safety annotations, this is nearly sufficient. An agent can identify the operation and all parameter expectations. The notable gap is the absence of usage guidance to steer it away from sibling listing tools, but nothing critical to invoking the tool correctly is missing.

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

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

Schema description coverage is 100%, so all four parameters are already documented (url, context, llm_model, conversation_id). The description's 'by URL' reinforces the url parameter's role but adds no substantive meaning beyond what the schema already provides. Baseline 3 applies.

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

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

States a specific verb (Get), resource (Bluesky post), and the retrieval mechanism ('by URL'), with 'single' scoping the operation. This distinguishes it from sibling tools like bluesky_profile_get (profile, not a post) and bluesky_profile_posts_list (listing, not a single URL fetch) without needing to open the schema.

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

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

Provides no guidance on when to use this tool vs alternatives. There is no mention of when to prefer bluesky_profile_posts_list, no exclusions, and no note about restrictions (e.g. public posts only). The intended context is only implied by the name and parameter.

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 provide readOnlyHint=true and openWorldHint=true, so the description carries a lower burden. However, the description adds no behavioral context beyond that: it does not describe return format, error handling, handle normalization, or data freshness. It rephrases the schema's handle input instead of disclosing anything new.

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

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

The description is short and front-loaded: the core action and resource appear in the first sentence, and the input requirement is in the second. 'For a creator or account' adds little value, but the overall size is appropriate and no essential content is buried.

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

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

This is a simple read-only getter with full schema coverage and readOnly/openWorld annotations, so the description does not need to carry much. However, there is no output schema and the description does not indicate what fields or data the returned profile contains, leaving the agent without a clear expectation of the result payload.

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 even without param information in the description. The description's 'Accepts a handle' adds no new meaning beyond the schema's detailed handle description, and it says nothing about required fields like context or llm_model. This is acceptable because the schema covers them 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 and resource: 'Get a Bluesky profile' and identifies the required input form ('Accepts a handle'). It is clearly distinguishable from sibling tools like bluesky_post_get and bluesky_profile_posts_list by resource type, though it does not explicitly name those alternat]ves.

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 prefer this tool over alternatives. It does not mention bluesky_profile_posts_list or any other profile-related tool, and it does not state when not to use it. 'Accepts a handle' is a prerequisite, not a usage rule.

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 convey read-only and open-world behavior, and the description does not contradict them. The description adds that the result is a list and that pagination uses a cursor, which is useful but sparse — it does not mention rate limits, authentication requirements, 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?

Two short sentences, front-loaded with the core action and resource, followed by a high-value pagination note. No filler, no repetition of schema details.

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

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

Given the simple read-only nature, full schema coverage, and readOnly/openWorld annotations, the description covers the main execution concerns. The absence of an output schema means the agent only learns that the result is a list, not the precise fields per post, but for this tool's simplicity that is a minor gap.

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

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

Schema description coverage is 100%, so the schema already documents every parameter. The phrase 'by handle' reinforces the handle parameter and 'use cursor when paginated' reinforces the cursor parameter, but neither adds meaning beyond what the schema properties already state.

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'), a specific resource ('posts from a Bluesky profile'), and a clear lookup key ('by handle'). This cleanly distinguishes the tool from sibling tools like bluesky_profile_get (profile metadata) and bluesky_post_get (single post).

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

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

The intended use case is explicit: list a profile's posts by handle. It also provides a concrete pagination instruction ('use cursor when paginated'). It does not name alternative tools or state when not to use this tool, but the context is clear and no competing Bluesky listing tool exists in the sibling set.

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. The description adds useful behavioral context beyond these annotations: it explains what each mode returns (compact field digest vs. full page including Examples/SDK snippets) and specifies the accepted pathname patterns. It does not describe error handling or auth requirements, but the readOnly annotation already covers the safety profile and the description provides meaningful mode semantics.

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

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

Three sentences, each carrying essential information: the action and source, the mode behavior, and the accepted pathname formats. No filler or redundant restatement of the tool name.

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

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

Despite having no output schema, the description gives an adequate sense of the return format for both modes (compact field digest vs. full page with Examples). It clearly ties the required docsPathname to docs_search, documents mode variants, and the schema covers the remaining required params (context, llm_model) with precise instructions. An agent has enough to invoke the tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters thoroughly. The description adds minor value by explicitly tying docsPathname to docs_search and noting acceptable pathname prefixes, but this largely echoes the schema's own examples and the mode param description. Baseline 3 is appropriate.

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

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

The description clearly states the tool's function: read a corpus page using a docsPathname obtained from docs_search. It distinguishes itself from the sibling docs_search tool by specifying the read action, the accepted pathname families, and the mode options, leaving no ambiguity about what it 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 explains when to use the tool (after obtaining a pathname from docs_search) and provides specific guidance on choosing mode=outline versus mode=full for different content needs. It references docs_search as the source of the pathname, which implicitly guides the agent away from using docs_read without a prior search, though it doesn't explicitly state 'use docs_search when you don't have a pathname'.

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, so the safety profile is covered. The description adds useful routing context (docs_read defaults to outline, field-crosswalk path) but does not describe docs_search's own result behavior, ranking, or output format. There is no contradiction with annotations, so the score stays at a solid 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 sentences with the main action front-loaded and no filler. The routing to docs_read and the specific field-crosswalk path are compact and 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 read-only search tool, the description adequately covers when to use it, when not to use it, and a concrete crosswalk route. The schema fully documents all six parameters, including required context and llm_model. The only notable absence is a description of what a result looks like, which keeps this from 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 description coverage is 100%, so the baseline is 3. The description adds one domain-specific query example ('field crosswalk') but does not add meaning to the query or context parameters 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 ('Search'), a concrete resource ('SocialFetch docs'), and a clear scope ('API/SDK questions'). It also distinguishes itself from the sibling docs_read by explicitly saying response-field lookups should use docs_read instead.

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 scopes when to use this tool (API/SDK questions) and gives explicit alternatives: 'For response fields use docs_read' and a specific recipe for cross-platform field naming ('search `field crosswalk` or read /product/ask-ai/field-crosswalk'). This leaves little to inference.

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

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

Annotations already provide readOnlyHint and openWorldHint, covering the core safety and data-freshness profile. The description adds the single-ad and dual-locator behavior, but it does not disclose return-value shape, error behavior for invalid ids, or how trim/transcript affect the response. 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?

A single sentence with no wasted words, front-loading the verb, resource, and input forms. It is compact while conveying everything the agent needs at the description level.

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 fully documented 7-parameter schema, readOnly/openWorld annotations, and the simple getter pattern, the description covers the essential selection semantics. It could mention return structure or expected outputs since no output schema exists, but the tool name and sibling conventions make the result sufficiently predictable.

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 description correctly avoids restating each parameter. It does add useful relational meaning by indicating that either adId or url may be used as the locator, which is not enforced in the schema's required list (only context and llm_model are required).

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'), names a precise resource ('single Facebook Ad Library ad'), and states the two accepted locator forms ('archive id or public Ad Library URL'). This clearly distinguishes it from facebook_adLibrary_ads_search_get and from platform-specific siblings like google_adLibrary_ad_get and linkedin_adLibrary_ad_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 clearly implies the intended use: when the agent already has a specific ad identifier or public URL and wants one ad, this is the tool. It does not explicitly name the search sibling as the alternative for discovery workflows, so it falls just short of full exclusion guidance.

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

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

Beyond the readOnlyHint and openWorldHint annotations, the description adds behavioral detail: it returns a list and supports cursor-based pagination. This tells the agent what kind of response shape to expect, which is useful given there is no output schema. No contradiction with annotations.

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

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

Two short sentences with no filler. The primary action is front-loaded, and the pagination note is a valuable, efficient addition. 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 14-parameter search tool with full schema coverage and read-only annotations, the description captures the essential behavior: search, filter, return a list, and paginate via cursor. There is no output schema, so the return-type note is important. The special semantics of required params like context and llm_model are left to the schema, which is acceptable given the schema's richness.

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 every parameter is documented in the schema. The description adds only a high-level summary ('by keyword and filters'), which does not enrich parameter meaning beyond what the schema already provides. 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 states a specific verb ('Search'), a specific resource ('Facebook Ad Library ads'), and the operation's nature ('by keyword and filters', 'Returns a list'). The 'Returns a list' clause helps distinguish it from single-ad retrieval siblings like facebook_adLibrary_ad_get, though it does not explicitly name that alternative.

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

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

The description makes the core use case implicit — search ads by keyword and filters — and gives a pagination instruction ('use cursor when paginated'), but it does not explicitly state when to prefer this tool over sibling tools such as facebook_adLibrary_ad_get or other ad-library search tools. The alternative-selection guidance is absent.

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 a small behavioral detail: the return is paginated and a cursor should be used. That is modest extra context, but it doesn't disclose any rate limits, result limits, or matching behavior (e.g., partial/fuzzy matching). With annotations covering safety, 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?

Two sentences with no filler: front-loads the purpose, then gives the key input and the pagination behavior. Every sentence earns its place.

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

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

For a simple search tool with read-only annotations and a fully-covered schema, the description covers purpose, input, and pagination hint. It lacks explicit mention of result fields or limits, but there is no output schema and the tool is a list search; the 'use cursor when paginated' note is the most critical operational detail and is present.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds 'Accepts a company name', which reinforces the query parameter meaning but doesn't add format details (e.g., exact matches only vs partial). The context and llm_model params are already well-described in the schema, so no compensation is needed.

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 ('Search'), a specific resource ('Facebook Ad Library companies / advertisers'), and a clear input ('by name, accepts a company name'). The output is also identified ('returns a list'). It is clearly distinct from the sibling tools that search ads (facebook_adLibrary_ads_search_get) or retrieve a single ad (facebook_adLibrary_ad_get), though it doesn't explicitly name those siblings.

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

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

The description clearly implies when to use it: when the user wants to find companies/advertisers by name in the Facebook Ad Library. It contrasts implicitly with sibling ad-search and ad-get tools. However, it does not explicitly state exclusions or name the alternative tools, so an agent may not immediately know when to prefer facebook_company_ads_list vs this tool.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds the pagination hint ('use cursor when paginated') and the accepted input forms, which is useful. It does not specify what fields are returned, rate limits, or the fact that the Ad Library may omit some ads, but three 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?

Three short sentences, front-loaded with the primary action and resource, and the pagination note is compact. 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 list tool with 13 parameters, the description does not explain which parameters are required to be meaningful (e.g., must provide pageId or companyName), even though schema marks only context and llm_model as required. That is a notable gap in selection/correct invocation. Otherwise, with annotations covering read-only and open-world behavior, plus schema documentation, the description is nearly 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 coverage is 100%, so every parameter has at least a basic description. The tool description does not add deeper parameter semantics (e.g., that pageId and companyName are mutually exclusive, or which one takes precedence), but it does mention two key inputs ('page id or company name'). Baseline 3 is fair.

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 ('ads a company or Page is running in the Facebook Ad Library'), and the accepted inputs ('page id or company name'). It also mentions the return type ('list') with pagination usage, which distinguishes it from sibling tools that retrieve single ads (facebook_adLibrary_ad_get) or search across advertisers.

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 indicates that a page id or company name is required, which guides usage. It does not explicitly compare itself to the sibling get/search ad library tools, but the distinction is largely inferable from the naming and 'Ad Library' scope.

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 the event is fetched by URL or id, but it does not disclose expected response content, error conditions, or any limitations beyond what annotations and schema provide. It is consistent, but adds minimal behavioral 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, front-loaded sentence with zero filler. It states the action and the two acceptable input forms without wasting 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 read-only getter, the description is largely complete: it identifies the resource and the two ways to target it. It could mention that only public events are accessible or what information is returned, but the annotations and schema descriptions cover the essential safety and parameter requirements.

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

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

Schema description coverage is 100%, so the schema fully documents all parameters. The description adds marginal value by framing 'url' and 'eventId' as alternative ways to identify an event, but it does not provide meaningful semantics beyond what the schema already states.

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

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

The description states a specific verb ('Get') and resource ('Facebook event'), and clearly identifies the two input modes: URL or event id. This distinguishes it from sibling list/search tools like facebook_events_list and facebook_events_search_list, which operate without a specific identifier.

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: call this tool when you have a Facebook event URL or event id. However, it does not explicitly mention alternatives such as facebook_events_search_list when no identifier is available, nor does it state exclusions. The guidance is clear but not fully explicit.

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

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

Annotations already declare readOnly and openWorld hints, lowering the burden. The description adds that results are paginated and cursor should be used, but doesn't disclose response item shape, potential incompleteness, or any rate/access constraints beyond that.

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 brief sentences with no filler; the core purpose and pagination behavior are front-loaded.

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

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

For a simple read-only list operation, the description plus complete schema is sufficient to invoke correctly. It notes pagination and scope but, with no output schema, could add a bit more about what each returned item 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 each parameter is already documented. The description reit's 'explore URL' and 'cursor' but doesn't add meaning beyond what the schema 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?

Description states a clear verb ('List'), resource ('Facebook events'), and scope ('for a city by explore URL'), which distinguishes it from profile-level and single-event tools. 'By explore URL' also sets it apart from search-based event 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?

No guidance on when to choose this tool over siblings such as facebook_events_search_list or facebook_profile_events_list. The only implicit cue is that an explore URL is required; no when-not or alternative conditions 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?

Annotations already declare readOnlyHint=true and openWorldHint=true, covering the safety profile. The description adds useful behavioral context by stating that the tool returns a list and that pagination should be handled with a cursor. It does not contradict the annotations.

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

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

Two short sentences with no filler. The primary action is front-loaded, and the pagination note is placed directly after the return-type statement. Every word earns its place.

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

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

For a simple read-only search tool with full schema coverage and openWorldHint, the description covers the core concerns: what is searched, the return shape, and pagination. It does not explicitly differentiate from facebook_events_list, but that is a usage-guideline gap already penalized.

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 description is not required to add parameter-level detail. The only addition is the 'by name' qualifier, which already appears in the query parameter's description. 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 states a specific verb (search), resource (Facebook events), and scope (by name), which distinguishes it from generic list tools like facebook_events_list and facebook_events_list. It does not explicitly name sibling tools, but the search-by-name qualifier makes 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?

The description gives no guidance on when to use this tool versus alternatives such as facebook_events_list, facebook_event_get, or facebook_profile_events_list. There is no mention of exclusions or conditions that would route an agent to a sibling tool. The usage context at best is implied by the word 'search'.

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 no behavioral detail beyond the readOnlyHint and openWorldHint annotations already present. It does not mention return format, public-group restrictions, rate limits, or other runtime behavior; however, it does not contradict the annotations.

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

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

The description is a single, well-structured sentence with no filler. The action, resource, and identifier modes are all front-loaded and immediately actionable.

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

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

For a read-only tool with no output schema, the description is minimally viable but sparse. It does not clarify what the response contains or how to distinguish this from facebook_group_posts_list, so an agent might still be uncertain about expected output or appropriate selection.

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

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

Schema description coverage is 100%, so all five parameters are already documented in the schema. The description's mention of 'URL or group id' usefully signals that url and groupId are alternative identifiers, but this adds only marginal value over the schema.

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

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

The description clearly specifies the verb 'Get' and the resource 'Facebook group,' and it identifies the two accepted identifier forms (URL or group id). It does not explicitly distinguish itself from siblings like facebook_group_posts_list, but the resource noun is specific enough to avoid major confusion.

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

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

No guidance is provided about when to use this tool versus alternatives, nor are exclusions or sibling recommendations given. The agent must infer context from the tool name and sibling-list, which is minimal support.

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 carry the read-only safety profile (readOnlyHint=true, openWorldHint=true), and the description adds value beyond them by disclosing the return shape ('Returns a list') and the pagination contract ('use cursor when paginated'). No contradiction with annotations.

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

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

Two sentences with zero wasted words: the purpose is front-loaded, and the return/pagination note earns its place because there is no output schema to reveal that 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 moderate-complexity tool with fully documented parameters and read-only annotations, the short description is sufficient: it states the resource, the return type, and the pagination mechanism. Explicit routing to alternatives like facebook_group_get would push this to a 5, but nothing needed to invoke the tool correctly is missing.

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

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

Schema description coverage is 100%, so the schema fully documents all six parameters; the description only echoes 'by group URL' and 'cursor', which map to url and cursor. This meets the baseline expected when the schema carries the semantic load, but adds nothing beyond 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 ('List'), a specific resource ('posts from a Facebook group'), and a scoping mechanism ('by group URL'), which is clear and unambiguous. It implicitly differentiates from siblings like facebook_group_get, facebook_profile_posts_list, and facebook_post_comments_list, but it does not name any alternative explicitly.

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 intended use is implied by the purpose statement — when you need posts from a group given its URL, use this tool. However, the description provides no explicit when-not-to-use guidance or named alternatives, despite a large sibling set with closely related facebook_* 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?

The annotations (readOnlyHint=true, openWorldHint=true) already establish the core behavioral profile: a safe read over potentially ephemeral data. The description adds little beyond restating the read operation and does not disclose common Marketplace failure modes (removed listings, regional unavailability, rate limits). It is fully consistent with the annotations — 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?

One 12-word sentence, verb-first, with zero filler. The 'by item URL' clause is the only content beyond the title, and it is precisely the detail an agent needs. Ideal front-loading.

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 low-compilexity read tool with 100% schema coverage and safety annotations, the structured fields carry most of the weight. Gaps remain: there is no output schema and the description never hints at what 'details' will contain, nor what happens when a listing is stale or removed — relevant given openWorldHint. Groundly adequate, 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%, and the schema descriptions are unusually rich — they explain the url-vs-itemId tradeoff, demand an exact or 'unknown' llm_model, and warn against inventing conversation_id. The description contributes only the marginal hint that URL is the primary lookup path. Baseline 3 applies since the schema does the heavy lifting.

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

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

States a specific verb ('Get') and resource ('details for a Facebook Marketplace listing') with a clear lookup mechanism ('by item URL'). Among the large sibling list full of search tools, this single-item fetch is immediately distinguishable — no other sibling retrieves a marketplace item's details. It paraphrases the title but adds the URL-based lookup detail, so it is not a tautology.

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

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

No guidance on when to choose this tool over facebook_marketplace_search_list or facebook_marketplace_locations_search. The only selection advice lives inside the itemId parameter description ('Provide this instead of url when you already know the item id'), which governs parameter choice, not tool choice. No contexts, exclusions, or alternatives are named at the tool level.

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

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

The annotations already declare readOnlyHint=true and openWorldHint=true, lowering the burden. The description adds useful behavioral context beyond annotations: it returns a list and uses cursor pagination, which tells the agent what response shape to expect and how to page through results. It does not cover rate limits or failure modes, but the annotation coverage supports this 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?

Three short sentences with the core purpose front-loaded. The phrase 'Accepts a city or place name' lightly duplicates the schema, but the description remains tight and every sentence contributes either purpose, input, or output/pagination 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 there is no output schema, the description reasonably covers purpose, input, return type, and pagination. It could specify what fields each list item contains, but the stated purpose of obtaining coordinates makes the expected content clear enough. The main omission, naming the companion listing-search tool, belongs more to usage guidelines than 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 the baseline is 3. The description's 'Accepts a city or place name' merely restates the query parameter's schema description and adds no extra meaning about context, llm_model, or conversation_id, which the schema already documents in detail.

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 ('Facebook Marketplace locations') with an explicit purpose: 'obtain coordinates for listing search.' This distinguishes it from sibling tools like facebook_marketplace_search_list, which searches listings rather than locations. The accepted input (city/place name) and output type (list) are also stated.

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

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

The purpose 'to obtain coordinates for listing search' implies this is a precursor step to listing search, but the description does not explicitly name the intended follow-up tool or give when-not-to-use conditions. The pagination note is a call-behavior hint, not a tool-selection guideline, so the usage guidance remains mostly implied.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the agent knows this is a safe, open-world read operation. The description adds the pagination behavior ('use cursor when paginated') and the list return type, plus the keyword+near-lat/lng scoping. It doesn't disclose details like whether lat/lng are required together, what happens when no results are found, or whether the cursor is opaque and must be passed unmodified, but with annotations covering the safety profile, 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 compact sentence of 19 words, front-loads the verb and resource, and earns its place by adding the pagination guidance that is not in the schema. There is zero verbiage or repetition of structured data.

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

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

The description is complete for a read-only search list tool: it covers the core inputs (keyword, location), the output shape (a list), and pagination behavior. The parameter schema is 100% covered, annotations carry the read-only/open-world safety profile, and there is no output schema to explain. The only minor gaps are things like mutual inclusiveness of lat/lng and the meaning of 'context', but the schema itself documents those parameters sufficiently.

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 17 parameters including enums, ranges, and the deprecated count/limit relationship. The description adds the high-level notion that query + lat/lng is the core search mode and that cursor is the pagination mechanism, which somewhat exceeds the schema. However, it doesn't add detail beyond what the schema already provides for most parameters, 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 states a specific verb ('Search'), the resource ('Facebook Marketplace listings'), and the two core constraints: keyword and latitude/longitude. It is distinct from siblings like facebook_marketplace_item_get and facebook_marketplace_locations_search, though it doesn't explicitly name them. The addition of 'Returns a list (use cursor when paginated)' gives a bit of output shape, but the purpose itself 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 implies the tool is for keyword-based marketplace searches around a location, which differentiates it from facebook_marketplace_locations_search (which searches locations, not listings) and facebook_marketplace_item_get (which gets a single item). However, it doesn't explicitly state when to choose this over other facebook marketplace tools, nor does it mention prerequisites like requiring both lat and lng or how the cursor should be used beyond 'use cursor when paginated'.

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 clear. The description adds value by confirming the return is a list and warning that cursor-based pagination may be required, which is useful behavioral 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?

One sentence with no filler. The core action, target resource, and pagination note are all included efficiently, and the URL-based scoping 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 straightforward read-only listing tool, the description covers the essential inputs (URL, cursor) and the output shape (a list). It does not specify whether replies are included or excluded, but the existence of a sibling replies tool makes that inferable.

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 already documented. The description reinforces the url param ('by URL') and cursor pagination, but adds little meaningful semantic information 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 uses a specific verb ('List') and a concrete resource ('comments on a Facebook post or Reel'), scoped by URL. It does not explicitly differentiate top-level comments from the sibling facebook_post_comments_replies_list, so the distinction between tools is left to inference.

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 makes the primary use case clear — listing comments for a given Facebook post or Reel — and even hints at pagination via cursor. However, it offers no explicit guidance on when to choose this tool over facebook_post_comments_replies_list or cross-platform comment tools like instagram_post_comments_list or reddit_post_comments_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 annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds that the tool returns a list and that a cursor should be used for pagination, which is useful, but it does not disclose response fields, rate limits, or what happens when no replies 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?

The description is short and mostly front-loaded, but the sentence "Accepts a from post comments" is gramatically incomplete and confusing. A focused, correct phrase like "Accepts the replies cursor from post comments" would make the description more effective.

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-style tool, the description, together with the rich schema and readOnly annotations, covers the main behaviors: the resource, the expected input source, and pagination. The lack of an output schema is partially mitigated by the explicit statement that the tool 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?

The schema description coverage is 100%, and the schema already explains the cursor, context, llm_model, and conversation_id fields with detailed meanings. The description's phrase "Accepts a from post comments" appears to be a malformed reference to the cursor and adds no value beyond the schema.

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

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

The description clearly states a specific verb and resource: "List replies to a Facebook comment." This distinguishes it from the sibling tool facebook_post_comments_list, which lists top-level comments, and from other platforms' reply-list tools. The title reinforces the same message.

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 used after retrieving post comments via the cursor mention, but it never explicitly says when to use this tool versus alternatives like facebook_post_comments_list or instagram_post_comments_replies_list. No exclusions or conditions are stated.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the description doesn't need to cover read-only safety. The description adds useful behavioral context by noting comments and transcripts are only included 'when available', implying the tool degrades gracefully. However, it doesn't disclose the output format, what fields the response will contain, or how it behaves when the URL is invalid or not a public permalink. With annotations carrying the safety profile, 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 compact sentence: 'Get a Facebook post or Reel by URL.' It is front-loaded, directly states the resource and the required input, and contains zero filler. It could arguably be slightly more descriptive about what a return value includes, but for a retrieval tool this is appropriately sized.

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-resource retrieval tool with 100% schema coverage, no output schema, and annotations declaring read-only and open-world semantics, the description is mostly complete. An agent can determine that it provides a post/reel's content (with optional comments and transcript). The only notable gap is that it doesn't describe the shape of the return payload, but since there is no output schema and annotations cover safety, this is a minor deficiency rather than a critical one.

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

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

Schema description coverage is 100%, so the schema documents all six parameters fully. The description itself doesn't add parameter-level meaning beyond what the schema provides. The description's mention of URL retrieval aligns with the url parameter, but the context and llm_model parameters (which appear to be universal tracking fields) are not discussed. Baseline 3 is correct when the schema handles parameter documentation.

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

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

The title 'Get Facebook post or reel' and description 'Get a Facebook post or Reel by URL' state a specific verb (get) and resource (Facebook post/reel) with an input method (URL), which clearly differentiates it from sibling tools like facebook_post_comments_list or facebook_profile_posts_list. It doesn't emphasize the post-vs-reel duality as strongly as it could in the description, but 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 makes clear the tool is for retrieving a specific post or reel by its public permalink URL. It doesn't explicitly state exclusions or alternatives, but sibling tool names such as facebook_post_comments_list and facebook_post_transcript_get make the usage context inferable: this is for the post content itself, not comments or transcripts. The inclusion of 'includeComments' and 'includeTranscript' boolean flags implies this is the primary post retrieval endpoint.

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

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

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds no behavioral detail beyond the input mechanism ('by URL'), and there is no mention of failure cases like missing captions. This is adequate but not enriching.

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

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

The description is a single sentence with no filler; the key scope ('Facebook post or Reel') and mechanism ('by URL') are front-loaded. 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 low-complexity read-only fetch tool, the description plus fully documented schema is nearly sufficient. The lack of an output schema and any note about transcript availability for captioned versus uncaptioned content leaves a small gap, but it does not impede 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% with detailed descriptions for url, context, llm_model, and conversation_id, so the schema does the heavy lifting. The description only echoes 'by URL,' adding no extra meaning 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 uses a specific verb ('Get'), names the resource ('transcript'), and scopes it to 'Facebook post or Reel' with 'by URL'. This clearly distinguishes it from platform-specific siblings and from facebook_post_get, which retrieves the post itself rather than its transcript.

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

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

The description implies the trigger case: getting a transcript for a Facebook post or Reel from a URL. It does not explicitly state when to prefer facebook_post_get or other platforms' transcript tools, so it stops short of full alternative routing.

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

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

Beyond the readOnly and openWorld hints, the description adds that the tool returns a list and that pagination is handled through a cursor. This gives the agent practical expectations about the response shape and how to continue larger result sets. No contradiction with the annotations exists.

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

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

Two sentences with no filler. The core action and resource are front-loaded, the input requirement is stated, and the pagination note earns its place by conveying actionable 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?

For a simple list tool with full parameter schema coverage and safety annotations, the description conveys the URL input, the list-shaped return, and the pagination mechanism. It does not describe the event fields in the returned list, but that is not necessary for correct invocation and no output schema was promised.

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 even without description-level parameter detail. The description adds a small amount of value by indicating the URL is a profile or page URL and that cursor should be used when paginated, but the schema already documents these 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 uses a specific verb ('List') and resource ('events hosted by a Facebook profile or Page'), and states that it accepts a profile or page URL. This clearly distinguishes it from search-oriented and single-event siblings, though it does not explicitly name or contrast with near-sibling facebook_events_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 intended use case is implied: call this when the user provides a Facebook profile or page URL and wants the events hosted by that entity. However, it gives no explicit guidance about when not to use it or how it compares to facebook_events_list, facebook_events_search_list, or facebook_event_get.

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 and live-data profile. The description adds minor context by indicating the tool supports both profiles and Pages, but it does not disclose return shape, pagination, or any access limitations. With annotations present, this is acceptable but not detailed.

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

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

The description is a single sentence that is direct, front-loaded, and free of filler. It conveys the core purpose without redundantly repeating the title or schema.

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

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

For a simple read-only profile lookup with full schema coverage and safety annotations, the description is mostly sufficient. It lacks explicit guidance about the response contents, but the tool name and resource type make the expected outcome reasonably clear.

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. The description adds value by clarifying that the url parameter can also accept a username, which is not explicitly stated in the schema's parameter description.

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

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

The description states a specific verb ('Get'), a specific resource ('Facebook profile or Page'), and the lookup method ('by URL or username'). It clearly distinguishes the tool from the many facebook_profile_* list tools, since it is the one that fetches the profile/Page entity itself.

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 should be used when an agent needs a Facebook profile or Page by URL or username. However, it does not explicitly mention when not to use it or point to alternative sibling tools for profile posts, events, photos, or other related data.

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

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

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds valuable behavioral context beyond that: base credit cost, +2 per hosted asset when hostMedia=true, credit caps, and the no-surcharge-on-failed-assets policy. This billing/failure behavior is not inferable from annotations or 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?

Three terse sentences with no filler: the action and resource are front-loaded, followed by URL requirement and credit/failure policy. Every sentence earns its place and nothing is restated from the schema.

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

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

For a read-only list tool with no output schema, the description covers the required input, cost behavior, and failure policy. The only mild gap is the somewhat ambiguous 'up to 24 / 49 max' figure and no explicit mention of pagination, though the cursor parameter is already documented in the schema.

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

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

Schema description coverage is 100% with detailed parameter docs, so the baseline is 3. The description adds semantic value by explaining the cost implications of hostMedia=true, which the schema only describes in terms of hosting duration and delivery URLs. It does not restate parameter details already fully covered by 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?

Description opens with an explicit verb–resource pair ('List photos from a Facebook profile or Page') and clarifies that it accepts profile or page URLs. This distinguishes it from sibling tools that list posts, reels, events, or return profile metadata.

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

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

The description gives the core invocation context (requires a profile or page URL) and makes clear it is for photo listings, but it does not explicitly state when to prefer this tool over similar Facebook list sibling tools like facebook_profile_posts_list or facebook_profile_reels_list. No when-not or alternative routing is provided.

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

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

Given the annotations already declare readOnlyHint=true and openWorldHint=true, the description adds useful supplementary behavior: credit costs, hostMedia surcharge details, a per-asset cap, and that failed assets are not surcharged. This goes beyond what annotations provide, though it does not describe return format or pagination behavior.

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

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

Three short sentences with zero filler. The purpose is front-loaded, followed by accepted inputs and a compact cost note. Every sentence contributes useful 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 read-only listing tool with full schema coverage and clear annotations, the description covers the core purpose, accepted identifiers, and cost implications. It does not describe the return structure, but the absence of an output schema and the simple list nature of the tool make this a minor gap.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaningful extra semantics by clarifying that either a URL or pageId can be used, and by explaining the cost behavior of hostMedia. This exceeds the schema's parameter descriptions.

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

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

The description opens with a specific verb and resource: 'List posts from a Facebook profile or Page.' It also states the accepted input forms (profile URL or page id), making the tool's scope unambiguous and clearly distinguishable from sibling tools like facebook_group_posts_list or facebook_profile_photos_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 implies the tool is for profile/Page posts and not for groups or reels, but it never explicitly states when to prefer this tool over alternatives or when not to use it. With many similar Facebook siblings, more explicit routing guidance would help, but basic usage context is clear from the resource 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, and the description goes beyond them by disclosing credit costs: 1 base credit, +2 per hosted asset when hostMedia=true, a cap, and no surcharge for failed assets. This is genuinely useful behavioral context. It does not detail response shape or pagination, but read-safety is covered.

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

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

The description is short, front-loaded with purpose, and packs in useful cost behavior without excessive detail. The only minor issue is slight redundancy between 'from a Facebook profile or Page' and 'Accepts a profile or page URL.'

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 output schema, the description provides enough orientation: what is listed, what input is needed, and how hostMedia affects cost. Cursor, conversation_id, and llm_model are documented in the schema. The 'up to 24 / 49 max' phrasing is slightly ambiguous but not blocking.

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 every parameter. The description mainly reiterates that a profile or page URL is accepted, which duplicates the url schema description. The hostMedia credit note is useful but relates to cost behavior rather than clarifying parameter meaning.

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 'Reels', and the scope 'Facebook profile or Page', and notes that it accepts a URL. This cleanly distinguishes it from sibling tools like facebook_profile_posts_list, facebook_profile_photos_list, and instagram_profile_reels_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 makes it clear the tool is appropriate when someone wants reels from a Facebook profile or page, including that a URL is the required input. It does not explicitly name alternative tools or state when not to use it, but the context is clear enough for selection.

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

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

Annotations already communicate read-only, idempotent, open-world, and non-destructive behavior, so the description does not need to restate those. The description adds useful context about when to invoke the tool, but it does not disclose return format, rate limits, or other runtime behavior. No contradiction with the annotations.

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

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

A single front-loaded sentence conveys both the purpose and the usage threshold without filler. Every clause adds value, and the fallback clause is a meaningful decision heuristic for the agent.

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 meta-tool with rich parameter documentation and safe annotations, the description is largely complete: it tells the agent when to call and the schema tells it how. The lack of an output schema means return structure is not described, but 'additional tools' reasonably implies a list of tool definitions, so this is a minor gap rather than a blocking 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%, and the schema itself provides detailed guidance: llm_model is for analytics only and must not be guessed, and conversation_id must come from a prior server response without parallel calls until available. The tool description adds no parameter-specific meaning, so the baseline score 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 that the tool checks for additional tools and gives the trigger condition: when specialized capabilities might help. This immediately distinguishes it from the domain-specific getters and search tools among its siblings, which retrieve data rather than expand the available toolset.

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

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

It gives explicit when-to-use guidance: call it whenever a task might benefit from specialized capabilities, even if existing tools could work as a fallback. It does not list when-not-to-use cases, but for a discovery tool this is a clear and actionable usage rule.

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

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

Annotations already establish readOnlyHint=true and openWorldHint=true; the description adds useful behavioral detail by stating activity is returned one month per request, the response is a list, and cursor-based pagination is used. This goes beyond the annotations, though it does not discuss rate limits or event-type granularity.

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 core action, time window, input, and pagination behavior are all front-loaded and every sentence earns its place.

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

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

For a simple read-only list with 100% parameter coverage, the description combined with annotations and schema is adequate: it names the output shape, monthly window, and pagination. The main gap is the absence of routing guidance versus sibling GitHub profile tools, but the basics for invoking correctly are present.

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

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

Schema description coverage is 100%, so the structured schema already documents all six parameters thoroughly. The description only restates that a username is accepted, which adds no meaning beyond the handle field's schema description. Baseline 3 is appropriate.

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

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

The description uses a specific verb ('List') and resource ('recent public activity for a GitHub profile'), and notes the monthly pagination window. It does not explicitly name siblings, so an agent must infer how this differs from github_profile_contributions_get or github_profile_repositories_list, though 'activity' is conceptually distinct.

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

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

There is no guidance on when to choose this tool over the many GitHub profile siblings, no exclusions, and no mentions of alternatives. The description only states what the tool does, leaving selection 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?

Annotations already declare readOnlyHint=true and openWorldHint=true, so the agent knows this is a safe, read-only operation. The description adds the year-scoping behavior and username input. It doesn't describe what the graph data looks like, whether it supports handles with/without @, or how it behaves for inactive users — the schema covers the @ detail, but behavioral output remains unspecified. With annotations already carrying the safety profile, a 3 is fair.

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

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

Two sentences, no filler, front-loaded with the core purpose and time scope. Every word earns its place. The description is appropriately brief for a simple read-only lookup 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 read-only single-resource tool with 100% schema coverage and readOnlyHint/openWorldHint annotations, the description plus schema is largely sufficient. It doesn't describe the response shape, but there is no output schema and the graph's content is predictable from the name. A 4 is justified because the only notable gap is the absence of any guidance on what the graph data contains or edge cases like missing years, which is minor for this tool's simplicity.

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

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

Schema description coverage is 100%, so the schema fully documents all 5 parameters. The description adds minimal semantic value beyond restating that a username is accepted and the year is a calendar year. The 'Accepts a username' line slightly reinforces that handle can include a leading @, which the schema also states. Baseline 3 is correct because the schema does the heavy lifting.

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

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

Description states a specific verb ('Get'), resource ('contribution graph for a GitHub profile'), and temporal scope ('for a given year'), plus the primary input ('Accepts a username'). It clearly distinguishes from sibling tools like github_profile_activity_list, github_profile_get, and github_profile_repositories_list because it targets the contribution graph specifically, which no sibling name mentions.

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

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

The description conveys the core usage context: call it to retrieve a GitHub profile's contribution graph for a year, accepting a username. It does not explicitly list when not to use it or name alternatives like github_profile_activity_list, but the tool name and description make the use case clear enough. A 4 is appropriate because it gives clear context but lacks explicit exclusionary 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 safety and open-world behavior are covered. The description adds useful behavioral information beyond annotations: it says the result is a list and explicitly tells the agent to use a cursor when paginated. This is concise but meaningful disclosure of response-shaped pagination behavior.

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

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

Two short sentences, front-loaded with the main verb and resource, and every sentence earns its place. It states what the tool does, what it accepts, what it returns, and how pagination behaves, all in minimal text.

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-retrieval tool with readOnly annotations and a fully described input schema, the description supplies purpose, required input, return shape, and pagination guidance. It could have mentioned what fields each follower entry contains, but in absence of an output schema this is a minor gap rather than a blocker.

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 handle, cursor, context, lllm_model, and conversation_id. The description adds no substantive parameter semantics beyond calling the required identifier a 'username', which matches the handle parameter. This meets the baseline of 3 but does not elevate 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 uses a specific verb and resource: 'List followers for a GitHub profile' and immediately clarifies it accepts a username. It is clearly distinguishable from the sibling github_profile_following_list by naming the target as followers rather than following. The additional 'Returns a list' reinforces the expected outcome 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 gives clear functional context—list followers for a GitHub profile—but does not explicitly state when to choose this tool over alternatives such as github_profile_following_list or github_profile_get. Usage is implied by the name and the stated purpose, but no exclusions or alternative-routing guidance 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?

Annotations already carry readOnlyHint=true and openWorldHint=true, so the safe-read nature is externally declared. The description adds that a list is returned and cursor pagination should be used, though this partly duplicates the schema's cursor property.

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 operation and finished with the pagination hint. There is no filler, repetition, or unnecessary caveat.

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 covers what it returns and how pagination is handled. A description of item fields would be nice but is not essential given the title and the overall simplicity; no output schema exists, but the description gives enough to invoke it.

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

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

Schema description coverage is 100%, so handle, cursor, context, llm_model, and conversation_id are already documented in the schema. The description only rephrases handle as 'Accepts a username' and cursor as 'use cursor when paginated,' adding no new semantic meaning. Baseline 3 is appropriate.

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

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

The description states a specific verb and resource: 'List accounts a GitHub profile follows,' which clearly scopes the operation to the following list rather than the profile itself. It distinguishes from github_profile_followers_list by using 'follows,' but does not explicitly name alternatives or boundary conditions.

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 when-to-use or when-not-to-use guidance. The phrase 'Accepts a username' implies the handle parameter is needed, and 'use cursor when paginated' gives a pagination hint, but an agent must infer that followers should go to github_profile_followers_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?

With readOnlyHint=true and openWorldHint=true annotations, the description does not need to restate safety. It adds useful behavioral context by stating the tool works for both users and organizations and accepts a username. It does not mention rate limits or response shape, but the annotations already carry the main behavioral signals, and the description adds value beyond 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 short sentences with zero redundancy. Each phrase adds value: the verb, the resource, the entity scope, and the parameter are all covered efficiently. The description is front-loaded and appropriately sized.

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 lookup with a single meaningful parameter and full schema coverage, the description is sufficient. There is no output schema, so return-value details are not described, but the tool's simplicity and the annotations make the package complete enough 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 description coverage is 100%, so all four parameters are already documented in the schema. The description adds minimal extra meaning—'for a user or organization' and 'accepts a username'—which partially overlaps with the schema's handle description. With full schema coverage, the baseline of 3 is appropriate.

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

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

The description uses a specific verb ('Get') and names the resource ('GitHub profile') plus the accepted entity types ('user or organization'). This distinguishes it from the many GitHub sibling tools that target other aspects like activity, contributions, followers, or repositories. However, it does not explicitly contrast it with the closely related github_profile_* siblings, so it is clear but not maximally differentiated.

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

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

The description clearly implies when to use the tool: whenever a GitHub profile for a user or organization is needed. The sibling list provides context for alternative GitHub profile-related tools, but the description itself does not state when not to use it or explicitly point to alternatives. It gives clear context but no 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 provide readOnlyHint=true and openWorldHint=true, so the read-only/open-world aspects are covered. The description adds useful pagination behavior ('use cursor when paginated') and clarifies that the result is a list. No contradiction with annotations.

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

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

Two short sentences with the primary action front-loaded. Every clause earns its place: scope, input, return type, and pagination; there is no filler or duplicated schema detail.

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 paginated list tool, the description plus 100% schema coverage adequately convey what the tool returns and how to paginate. It does not state whether all PR states are included or how results are ordered, but openWorldHint and schema coverage make those gaps minor.

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

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

Schema description coverage is 100%, so parameters such as since, until, handle, context, and conversation_id are already fully documented. The description only re-states 'username' and 'cursor' without adding meaning beyond the schema, so it stays 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?

Starts with a specific verb 'List' and a specific resource: 'pull requests authored by a GitHub user.' This clearly differentiates it from siblings like github_profile_get, github_profile_activity_list, and github_profile_repositories_list. The title and name reinforce the same 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 when-to-use or when-not-to-use guidance and no mention of alternative tools. The only implicit cue is the scope stated in the first sentence; it never tells an agent to prefer this over related profile list tools or explains what it is not for.

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

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

Annotations already carry readOnlyHint=true and openWorldHint=true, so the description's burden is lighter. It does add that the call returns a list and that cursor-based pagination applies, which is useful beyond the schema. No contradiction with annotations.

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

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

Two short sentences with the core action and scope front-loaded, followed by the pagination caveat. No filler or redundant restating of the title.

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 full schema documentation and readOnly annotations, the description covers the essential contract: what is listed, for whom, and how pagination works. The absence of an output schema is partially mitigated by 'returns a list'; more detail about returned item fields would help but is not necessary for correct invocation.

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

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

Schema description coverage is 100%, so the description is not expected to repeat parameter details. It adds only a minimal 'accepts a username' mapping and a pagination hint, both already largely covered by the well-documented handle and cursor schema entries.

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 — 'List repositories for a GitHub user or organization' — with a clear resource and return type. It is distinct enough from profile activity/contributions/followers tools, but it does not explicitly differentiate itself from github_repositories_get, so it misses full sibling differentiation.

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

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

The description implies the main use case but provides no when-to-use guidance, no exclusions, and no pointers to alternatives such as github_repositories_get or github_profile_get. In a large sibling set, an agent gets no routing help beyond the obvious 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, which aligns with the non-destructive 'Get' wording. The description adds no additional behavioral context such as auth requirements, rate limits, or restrictions beyond the schema's 'public' mention, but for a simple read-only fetch tool the annotation coverage lowers the bar. No contradiction exists.

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

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

The description is a single, front-loaded sentence with no filler or redundancy. It states the verb and resource immediately and avoids repeating the schema content.

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

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

This is a low-complexity tool: four parameters, all fully documented in the schema, with read-only annotations covering the safety profile. An output schema is absent, but 'Get' sufficiently implies that the repository object is returned. An agent has enough information to invoke this tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description's 'by URL' only restates what the url property already documents and adds no meaning about context, llm_model, or conversation_id. Those parameters are already fully explained in the schema.

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

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

The description uses a specific verb ('Get') and a specific resource ('a single GitHub repository'), and further clarifies the access pattern ('by URL'). This distinguishes it from list-style siblings like github_profile_repositories_list and from profile-focused tools.

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

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

The description implies the main usage condition: the agent should call this when it has a specific repository URL in hand. However, it does not explicitly state when to prefer this over github_profile_repositories_list or other repository-related tools, so the guidance is implicit rather than explicit.

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

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

The readOnlyHint and openWorldHint annotations already establish safety and volatility. The description adds behavior beyond those: it returns a list and mentions pagination via cursor. Missing rate-limit or ordering detail is minor for this simple read-only list tool.

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

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

The description is a single sentence that front-loads the operation and object, then adds a parenthetical on pagination. There is no filler or redundant rewording of the title.

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 a rich schema and safety annotations, selection and single-page invocation are adequately supported. However, the instruction to 'use cursor when paginated' references a cursor that does not exist as an input property, leaving multi-page behavior underspecified. With no output schema, the description could also say a bit more about what the returned developer list 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 the schema already documents 'since,' 'language,' and the analytic/meta parameters. The description's mention of 'language and time window' simply mirrors schema fields rather than adding new semantics. Baseline 3 is appropriate.

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

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

The description uses a specific verb and resource: 'List trending GitHub developers for a language and time window.' This clearly separates it from the sibling github_trending_repositories_list and other GitHub profile tools. The return-type note reinforces that it is a list 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?

The description gives clear context for when this tool applies: a user wants trending developers, optionally constrained by language and time window. It does not explicitly name alternatives or exclusion cases, so it falls just short of a 5.

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

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

Annotations already cover the read-only safety profile (read-onlyHint=true, openWorldHint=true). The description adds what the annotations do not: the return type ('Returns a list') and pagination behavior (cursor-driven). It stops short of rate-limit or data-freshness context, so not a 5.

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

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

Two sentences with zero filler. The core purpose is front-loaded in sentence one, and the pagination hint earns its place in sentence two. Nothing repeats what the schema already provides.

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 at all, 'Returns a list' is thin on result-item shape, but 'trending GitHub repositories' is a well-known domain and the item fields are predictable. Core selection dimensions (language, time window) and pagination are covered. Small residual gap: what fields each repo entry carries.

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% per context signals, so each of the six parameters is already documented in the schema. The phrase 'for a language and time window' lightly reinforces the language and since parameters but adds no meaning beyond the schema, meeting the baseline of 3.

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

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

States the verb (list), resource (GitHub repositories), and selection scope (trending, language, time window) in one sentence. The word 'repositories' cleanly separates it from the near-twin sibling github_trending_developers_list without needing to open either schema.

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

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

The description implies use when a user wants trending repositories filtered by language or recency, but gives no explicit routing to the near-twins github_trending_developers_list or github_profile_repositories_list. With such a close sibling present, the absence of when/ when-not guidance is a meaningful 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, so safety is covered. The description adds the 'single' scope but does not mention rate limits, error behavior, or the shape of the returned creative data. No contradiction with annotations.

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

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

One sentence with zero filler; the action, resource, and input are front-loaded. It is appropriately sized for a tool that takes only one meaningful parameter plus generic metadata fields.

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?

Complete enough for a simple read-only single-resource tool: the schema documents all required params, annotations cover the safety profile, and the description identifies the sole semantic input (public URL). It does not describe return contents, but the tool name and 'creative' make the expected output clear.

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 already documented as 'Public Google Ad Transparency URL for the creative.' The description mostly repeats that phrase and does not add new parameter-level nuance. Baseline 3 applies.

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

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

States a specific verb ('Get'), resource ('single Google Ad Transparency creative'), and input method ('by public Ad Transparency URL'). The explicit 'Google' clearly distinguishes it from facebook_adLibrary_ad_get, linkedin_adLibrary_ad_get, and tiktok_adLibrary_ad_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?

Implies the use case: call when you have a public Ad Transparency URL and want one creative. However, it does not explicitly state when to use google_adLibrary_advertisers_search or google_company_ads_list instead, and it gives no 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 readOnlyHint and openWorldHint annotations already cover the safety profile. The description adds that the call returns a list and hints at pagination via cursor, which is useful operational context. However, the cursor mechanics are undefined (no cursor parameter appears in the schema) and the description doesn't say what each returned advertiser record contains.

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 search action and minimal filler. The grammar issue ('a advertiser') and the cryptic cursor tip slightly dent polish, but the definition is appropriately sized.

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 search tool, the essentials are present: what to pass (a name), what comes back (a list), and pagination behavior. With full schema coverage and readOnly/openWorld annotations, the missing return-field details are less critical, though there is no output schema to fill that gap.

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

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

Schema description coverage is 100%, with every parameter, including the administrative context and llm_model fields, already documented. The description only restates the 'name' concept already captured by 'query', adding no new parameter-level meaning beyond the schema.

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

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

The description opens with a specific verb ('Search'), a concrete resource ('Google Ad Transparency advertisers'), and a scope ('by name'), so an agent can tell it searches for advertisers rather than individual ads or companies. However, it relies on the title for the Ad Library platform label and doesn't explicitly distinguish it from related sibling tools like google_adLibrary_ad_get or google_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?

It implies its intended use case—looking up advertisers by name—but never states when to prefer it over alternatives such as google_adLibrary_ad_get or google_company_ads_list. No exclusions, prerequisites, or routeing guidance 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?

Annotations already declare readOnlyHint=true and openWorldHint=true, so the read-only and external-data characteristics are covered. The description adds practical behavior: returns a list, supports cursor pagination, and accepts either a domain or advertiser id. It does not disclose what fields each ad item contains, whether results are sorted, whether this is the correct tool for all ad types, or what happens when both domain and advertiserId are supplied.

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

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

Three sentences with no filler. It front-loads the purpose, then the identifier alternatives, then the return/pagination behavior. 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 read-only list tool with all parameters documented in the schema, the description provides sufficient operational guidance: identifier alternatives, list response, and pagination marker. Minor gaps: no mention of output item shape, no guidance on handling both domain and advertiserId, and no note that political topic requires region (though the schema covers that).

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

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

Schema coverage is 100%, so the schema already documents every parameter. The description adds the key semantic that domain and advertiserId are alternatives ('Accept a domain or advertiser id'), which is important and not fully captured by individual parameter descriptions. However, it does not clarify precedence/conflict behavior when both are provided, and the cursor semantics are partially implied by 'use cursor when paginated' and the schema's opaque-pagination description.

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

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

The description clearly states the tool lists ads from Google Ad Transparency for a company or advertiser, and it identifies the two accepted identifier forms (domain or advertiser id). It also mentions the return type is a list with cursor-based pagination, which differentiates it from ad-get and search tools among siblings.

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

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

The description states when to use the tool (when you have a domain or advertiser id and need ads from the ad library), and the schema adds clarity that topic=political requires region. It does not explicitly contrast against google_adLibrary_ad_get, google_adLibrary_advertisers_search, or facebook_company_ads_list, but the 'List' action plus 'domain or advertiser id' provides enough context for selection.

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

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

Annotations already communicate readOnlHint=true and openWorldHint=true, so the safety profile is covered. The description adds that the result includes the ancestor chain to the root story, which is useful behavior, but it does not describe response shape, ordering, or edge cases such as a comment missing from the chain.

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 the key differentiator — ancestor chain to root story — front-loaded. 'Accepts a comment id' is slightly redundant with the schema but does not add significant noise.

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 with full schema coverage and annotations, the core return value is described. Because no output schema exists, a little more detail about the chain format, order, or whether the root story itself is included would make it fully complete, but the current text is sufficient for typical 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?

Schema description coverage is 100%, so all four parameters are already documented. The description only repeats that id is a comment id and adds no extra meaning for context, llm_model, or conversetion_id, matching the baseline of 3 for fully covered schemas.

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

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

States a specific verb ('Get') and a precise resource: a Hacker News comment plus its ancestor chain to the root story. This clearly distinguishes it from the siblings hakernews_item_get and hakernews_story_comments_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 implies when to use the tool — when the caller needs the comment along with its ancestor chain — but it never names alternatives or states when not to use it. An agent must infer the boundary against hakernews_item_get and hakernews_story_comments_list without 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?

With readOnlyHint and openWorldHint already covering side effects and world closure, the description adds useful behavioral context by stating it returns a list and that pagination is supported. It does not describe item shape or rate limits, but the annotation coverage lowers the bar.

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, front-loaded, and easy to parse. It loses a point because 'Accepts a feed name' is largely redundant with the first clause and the title, adding slight verbosity without new information.

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

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

The rich schema covers required params, defaults, max values, deprecated aliases, and conversation sequencing, so the description need not repeat those. It correctly states the output kind (a list) and pagination approach. It is not a 5 because with no output schema, the returned item shape is left to inference.

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 explains each parameter including enums, defaults, maximums, deprecated aliases, and pagination mechanics. The description's 'Accepts a feed name' and 'use page/pageSize' add no meaningful semantics beyond the schema, so the baseline of 3 applies.

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

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

The description states a specific verb ('List') and resource ('Hacker News feed') and enumerates the valid feed types (top, new, best, ask, show, jobs), making it clear and distinct from sibling tools like hackernews_item_get or hackernews_search_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 a clear context for what the tool lists and provides pagination guidance ('use page/pageSize when paginated'), but it does not explicitly say when to choose this over alternatives such as hackernews_search_list or hackernews_story_comments_list. The usage is implied rather than contrasted.

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 the description adds no behavioral context beyond the predictable 'get' semantics. It does not disclose what kinds of items are returne (story, comment, job, poll), how missing or invalid ids behave, or any external API quirks. The description neither contradicts nor meaningfully enriches 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 filler and front-loads the verb and resource. It is economical, though arguably too spare to cover the important distinctions and behavioral notes. As pure conciseness it is strong, but as a complete tool description it sacrifices useful context.

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

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

For a tool with no output schema and a large set of closely related siblings, the description leaves important gaps: it does not define what an HN 'item' is, what shape the response takes, or how this relates to hackernews_story_get and hackernews_comment_context_get. An agent can identify the basic operation but cannot confidently choose or interpret this tool without additional knowledge.

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, context, llm_model, and conversation_id. The description's 'by id' merely restates the id parameter and adds no new semantic information. The baseline of 3 applies because the schema carries the full parameter-documentation 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?

The description states a clear verb and resource: 'Get a Hacker News item by id.' This is far from tautological and identifies the core operation. However, it does not explain how an 'item' differs from sibling concepts such as hackernews_story_get or hackernews_comment_context_get, so sibling differentiation is left to inference.

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 about when to use this tool instead of alternative Hacker News tools. With a large sibling list containing story_get, comment_context_get, user_get, and maxitem_get, the agent is not told which id types or scenarios map to item_get. No exclusions or conditional advice 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?

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: only 'top-level' comments are returned (excluding replies), the default thread selection behavior, and that pagination applies. The only minor blemish is recommending page/pageSize when the schema marks pageSize as a deprecated alias for limit.

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

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

Two tight sentences with the purpose front-loaded before the pagination note. Every sentence earns its place. The only deduction is the slight inaccuracy of pointing the agent to page/pageSize when the schema designates pageSize as deprecated and limit as preferred.

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 states the source resource, the month-selection behavior, and the paginated-list return shape — the essential facts an agent needs. It would benefit from hinting at what a job item contains (e.g., company, position, link to the HN comment), but the description is adequate for a simple list retrieval.

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 7 parameters, giving a baseline of 3. The description adds modest value by clarifying the month default ('latest thread') and hinting at pagination, but those facts are also present in the schema itself. The description doesn't complement the parameter semantics in any significant way.

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 a precise resource ('top-level jobs from the monthly Hacker News Who is Hiring thread'). This clearly distinguishes it from sibling tools like hackernews_search_list, hackernews_feed_list, and linkedin_jobs_search_list, which an agent could otherwise confuse it with.

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 contextual guidance about which thread is used ('latest thread, or a YYYY-MM month'), which clarifies parameter behavior. However, it never explicitly states when to prefer this tool over alternatives (e.g., hackernews_search_list), nor does it mention exclusions. Usage is implied rather than explicit.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds only the 'current' qualifier and 'largest item id' semantics, contributing little beyond what the title and annotations already convey. No contradiction with annotations, but minimal behavioral 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 efficient sentence with no waste, but it largely restates the title and tool name, so it does not fully earn its place as added value. Appropriate size, but low informational increment.

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 trivial scalar-geter with readOnly/openWorld annotations and no domain parameters, the description is minimally adequate. However, it omits useful context such as what the max item id is used for (new-item detection), and there is no output schema to clarify the return value.

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?

All three params are generic meta-parameters (context, llm_model, conversation_id) fully described in the schema at 100% coverage; the tool itself takes no domain-specfic parameters. Since there is nothing domain-specific to document, the schema carries the burden and the description need not add more.

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

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

The description states a specific verb ('Get') and a specific resource ('current largest Hacker News item id'), so the tool's function is unambiguous. However, it does not differentiate itself from sibling tools such as hackernews_item_get or hackernews_updates_get, so it earns a 4 rather than a 5.

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

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

The description offers no guidance on when to use this tool versus the many sibling HackerNews tools. There is no mention of use cases (e.g., detecting the latest item for polling), no exclusions, and no named alternatives.

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