freshcontext

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

Annotations already declare readOnlyHint=true and openWorldHint=false. The description adds meaningful behavioral context: the tool operates solely on caller-provided context and does not perform any fetching or external calls, which goes beyond the annotation information.

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

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

The description is two sentences long, front-loaded with the core purpose, and every phrase earns its place. It avoids redundancy and clearly communicates the tool's role and boundaries.

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 adequately covers the tool's essential scope and non-retrieval behavior. With no output schema, it does not detail the return format, but 'decision-ready output' gives a general expectation. The schema is complete, so the description is sufficient for correct invocation.

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

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

Schema description coverage is 100%, with all parameters (now, intent, profile, signals) having clear descriptions. The tool description does not add parameter-specific details beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description clearly states the verb 'Evaluate' and the resource 'caller-provided candidate context,' with the outcome being 'decision-ready output.' It explicitly distinguishes this tool from fetch/extract siblings by noting what it does not do (fetch, crawl, scrape, browse, read folders, call adapters).

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

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

The description provides clear context: this is the primary FreshContext judgment path and does not retrieve data, implying it should be used when candidate context is already available. It implicitly differentiates from sibling extract/search tools but does not explicitly name an alternative tool for retrieval.

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

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

Annotations include readOnlyHint=true, which already signals a safe read operation. The description adds context beyond that by mentioning the official API and specifying the return format (titles, authors, dates, abstracts). It does not cover rate limits or errors, but given the annotations, this is sufficient.

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

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

The description is two concise sentences. The first states the purpose and API usage, the second explains input options and output. Every word earns its place, and key information 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?

With only one parameter, no output schema, and simple behavior, the description is complete. It explains the input format, the output fields, and the API source. No critical details are missing for effective use.

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

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

The schema has 100% coverage for the single 'url' parameter, with a description that already explains it can be a search query or a full arXiv API URL. The main description repeats this information without adding significant new meaning, so it meets the baseline of 3 but does not exceed it.

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

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

The description clearly states the tool's function: "Search arXiv for research papers via the official API." It uses a specific verb ('search') and resource ('arXiv'), and distinguishes itself from sibling tools by naming the source. The return fields are also specified, leaving no 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 provides clear context for use: it searches arXiv for research papers and accepts either a topic or a full arXiv API URL. It does not explicitly mention alternatives or exclusions, but the name and description make it obvious when to use this tool over siblings like extract_scholar or extract_reddit.

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, and the description adds value by specifying the expected return format (version numbers, release dates, entries) and input flexibility. It does not contradict annotations and gives useful behavior context beyond the structured hints.

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

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

Two sentences with no filler: the first states the core purpose, the second details accepted inputs and outputs. Information is front-loaded and every word contributes to comprehension.

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

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

For a simple read-only tool with one parameter and no output schema, the description covers purpose, input format, and output content. This is sufficient for an agent to select and invoke the tool correctly in most scenarios.

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% as the single 'url' parameter is fully described with an example. The tool description repeats this information without adding new semantics, so it meets the baseline for well-documented schemas but does not enhance parameter understanding.

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

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

The description uses a specific verb ('returns') and identifies the resource (update history/changelog), clearly distinguishing it from sibling extract_* tools. It states accepted inputs (GitHub repo URL or npm package name) and output (version numbers, release dates, entries), making the tool's purpose unambiguous.

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

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

The description implies when to use the tool: when you need changelog data for a GitHub repo or npm package. However, it does not explicitly mention alternatives or exclusion criteria relative to sibling tools like extract_github or package_trends, leaving usage inference to the agent.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds useful context by listing the exact sources (SEC, USASpending, GDELT, changelog, Stooq), but does not disclose behavioral traits like potential latency, result aggregation format, or failure modes, which is a minor gap for a multi-source tool.

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

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

The description is two sentences, front-loaded with the key value proposition, and lists sources compactly. Every word earns its place, with no redundancy or fluff.

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

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

Given the tool's complexity (5 sources) and lack of output schema, the description should clarify what the caller receives—e.g., a synthesized landscape report, per-source JSON, or structured data. It currently only says 'company intelligence,' which is vague. The source list helps, but the return shape and how to interpret results remain unclear.

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

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

Schema description coverage is 100%, so parameters are already documented. The description does not add any param-specific meaning—it does not clarify which sources depend on ticker vs company vs github_url, leaving the existing schema descriptions as the sole source.

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

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

The description clearly identifies the tool as single-call company intelligence and lists five specific data sources, distinguishing it from sibling tools like extract_finance_landscape or extract_gov_landscape. However, it lacks an explicit action verb like 'extracts' or 'retrieves', relying on the tool name for that.

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

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

The phrase 'Most complete single-call company intelligence' provides clear context for when to use this tool (when broad multi-source intelligence is needed in one call). It implicitly differentiates from the individual category tools by enumerating the combined sources, but does not explicitly state when to choose an alternative or mention exclusions.

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

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

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds value by disclosing the data source (Stooq), the lack of an API key requirement, and the output format (quote/OHLC/volume with timestamps). 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 two succinct sentences that front-load the core value proposition ('No-key stock quote data via Stooq') and then explain input and output. No wasted words.

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

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

For a simple one-parameter tool, the description covers purpose, input, and output format. It does not describe data granularity, timezone, or limitations, but these are not critical given the tool's simplicity and the absence of an output schema. The return value description is sufficient.

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

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

The input schema has a single parameter 'url' with a description clarifying it expects ticker symbols. The description echoes the comma-separated format but does not add additional parameter semantics beyond the schema. With 100% 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 clearly identifies the tool's function: retrieving stock quote data from Stooq without an API key. It distinguishes itself from the sibling extract_finance_landscape by focusing on quote/OHLC/volume data rather than broader company landscape. The verb 'extract' is implicit in the name, but the description explicitly states it 'returns' data.

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 stock quote retrieval but does not explicitly state when to use this tool over alternatives like extract_finance_landscape. It lacks exclusions or comparative guidance. The 'No-key' mention is a distinguishing feature but not a usage guideline.

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

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

The annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is clear. The description adds value by detailing the specific data sources and the 'unified report' behavior, but it does not disclose other behavioral traits such as rate limits, response format details, or error handling. Overall, it provides some context beyond the annotations without contradicting them.

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

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

The description is extremely concise, consisting of two short sentences that immediately convey the composite nature and the list of sources. It is front-loaded with the purpose and uses a clear list delimiter. Every word contributes to the understanding, making it an exemplar of efficient writing.

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 composite tool integrating five sources, the description gives a high-level overview but omits details about the report structure, how sources are weighted or combined, and any prerequisites (e.g., whether company_name is needed for all searches). While the schema and annotations fill some gaps, the absence of an output schema makes the 'unified report' phrase vague. The description is adequate but not fully complete for a tool of this complexity.

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

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

The input schema covers 100% of parameters with descriptions for tickers, company_name, and github_query. The tool description does not add any additional parameter-specific semantics, merely implying the use of tickers via 'Stooq quote data'. With high schema coverage, the baseline of 3 is appropriate; the description does not compensate for any gaps but also does not need to.

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 as a composite financial intelligence extractor, listing five distinct data sources and indicating a unified report output. This differentiates it from siblings like extract_finance or extract_reddit by emphasizing the combined multi-source nature. The lack of an explicit verb (e.g., 'Fetches') is minor given the tool name and the source enumeration.

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 situations requiring comprehensive multi-source financial intelligence, but it does not explicitly state when to prefer this over simpler tools like extract_finance or provide exclusions. The '5-source unified report' phrase gives context that this is for aggregated insights, not single-source queries. No explicit alternatives are mentioned.

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

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

Annotations already declare readOnlyHint=true, so the read-only nature is known. The description adds data freshness (updated every 15 min) and return fields, but does not disclose other behavioral traits like pagination, rate limits, or query semantics. 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?

Two sentences with front-loaded purpose and no wasted words. The key facts (global scope, language count, update frequency, return fields) are packed efficiently.

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

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

For a simple one-parameter tool with no output schema, the description adequately explains what it returns (articles with source country, language, date). It lacks explicit details about query argument usage, but the schema covers that, so completeness is strong.

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 documents the 'url' parameter as a query string. The tool description adds no additional parameter context, so the baseline of 3 applies.

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

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

The description clearly states the tool retrieves global news articles from GDELT, with explicit scope (every country, 100+ languages) and return fields (source country, language, date). It uses a specific resource (GDELT) and distinguishes itself from sibling tools like extract_hackernews or extract_reddit.

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 global news intelligence, and the 15-minute update cadence and language coverage provide clear context. However, it doesn't explicitly mention alternatives or when not to use, so it falls 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 declare readOnlyHint=true and openWorldHint=true, covering the safety profile. The description adds minimal behavioral context, such as the ability to pass an empty query for all recent tenders, but it does not disclose return format, pagination, or rate limits. No contradiction with annotations.

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

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

The description is one efficient sentence, front-loaded with the core purpose and followed by parameter usage. Every word contributes, with no fluff or repetition.

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

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

Given the simple tool (one parameter, no output schema, safe read-only annotations), the description is largely sufficient. It covers the purpose and usage modes. It does not describe the returned structure, but openWorldHint and the straightforward nature of a search tool make that acceptable.

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 the single parameter 'url' described as 'Keyword, agency, or empty for latest tenders'. The tool description adds no new meaning beyond the schema; it essentially repeats the same usage guidance. The parameter name 'url' is slightly misleading, but the description clarifies it is not a URL.

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: 'Singapore Government procurement opportunities (GeBIZ via data.gov.sg)'. It uses a specific verb ('Search') and resource (procurement opportunities from GeBIZ/data.gov.sg), and the mention of Singapore distinguishes it from sibling tools like extract_govcontracts.

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

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

The description provides clear usage context by specifying search modes: 'Search by keyword, agency name, or empty for all recent tenders'. This tells the agent how to invoke the tool, but it does not explicitly contrast with alternatives such as extract_govcontracts, though the Singapore scope implies that.

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 read-only and open-world behavior. The description adds useful context by specifying 'real-time data' and 'timestamped freshcontext', plus listing the fields returned. It goes beyond annotations, though it omits potential limitations like rate limits.

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

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

The description is a single sentence that front-loads the primary action and resource, followed by a concise list of extracted data and output characteristics. Every phrase adds value without redundancy.

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

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

With no output schema, the description must convey return expectations. It lists data fields and mentions timestamps, but the term 'freshcontext' is vague and does not clarify the response format. Adequate for a simple tool but leaves room for ambiguity.

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

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

The schema fully covers the single URL parameter with format and example, and the description does not add further parameter semantics. With 100% schema coverage, the baseline score of 3 applies.

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

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

The description clearly states the tool's purpose: extracting real-time data from a GitHub repository, listing specific data elements (README, stars, forks, last commit, topics). This distinguishes it from sibling extraction tools for other domains.

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

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

The description implies usage when needing data from a specific GitHub repository, but it does not explicitly provide when-to-use guidance, exclusions, or alternatives. No mention of when to prefer this over related tools like search_repos.

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 tool's safety and nature. The description adds that it returns amounts, dates, and agencies, which is useful but does not go into depth about data freshness, pagination, or limitations. This is modest value beyond annotations.

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

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

The description is three short sentences that front-load the main purpose, then succinctly list search options and return fields. No unnecessary words or redundancy; every sentence contributes to understanding.

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

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

For a simple tool with one parameter and no output schema, the description covers the core purpose, accepted query types, and return fields. It does not describe the return structure, but the mention of amounts, dates, and agencies gives a sufficient high-level view for a basic extraction tool.

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

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

Schema description coverage is 100% for the single parameter, and the description essentially repeats the schema's description while adding an example ('Palantir'). The parameter name 'url' is ambiguous and not clarified by the description, so the added value is minimal.

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

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

The description clearly identifies the tool as retrieving US federal contract awards from USASpending.gov, which distinguishes it from sibling extraction tools. It specifies concrete search dimensions (company name, keyword, NAICS code), making the purpose unambiguous and actionable.

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

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

The description provides clear context: it is for US federal contract data and can be searched by company name, keyword, or NAICS code. However, it does not explicitly mention when not to use it or offer alternative tools, so it lacks explicit exclusions.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the description need not reiterate safety. The description adds useful behavioral context beyond annotations: it explicitly reveals that the tool aggregates data from multiple distinct APIs into a single report, which is a non-obvious behavioral trait. No contradictions with annotations.

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

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

The description is a single, information-dense sentence with a clear list of sources. It is efficient with no redundant words, though it could be slightly improved by separating the sentence or adding clarity on the report structure. Overall, it is concise and well-structured.

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

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

Given there is no output schema, the description should explain the return value more thoroughly. While it lists the four components of the report, it does not describe the report's format, key metrics, or potential limitations. This is adequate but leaves gaps for an agent needing to interpret the output.

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

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

Schema description coverage is 100% for both parameters (query and github_url), so the schema fully describes them. The description does not add additional parameter-specific meaning beyond what is already in the schema, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: to produce a composite government intelligence report combining four specified sources. It uses a specific verb ('extract' implied by the name) and resource ('government intelligence'), and the enumeration of sources distinguishes it from sibling extraction tools that focus on a single source.

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 on what the tool covers (four sources) and implies it is the unified version when multiple sources are needed, but it does not explicitly name alternatives or exclusion criteria. Agents can reasonably infer when to use this tool versus single-source siblings.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, covering the safety profile. The description mentions two modes (top stories vs search results), but does not add detail on pagination, rate limits, or return format, which are beyond the annotations.

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

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

Two short sentences: the first states the primary purpose, the second clarifies input flexibility. No redundant content or filler; the key information 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?

With only one parameter, full schema coverage, and read-only/open-world annotations, the description is adequate for correct invocation. It does not describe the output structure, but the purpose statement ('extract top stories or search results') implies the return type. Slightly more detail on expected output would make it fully complete.

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

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

Input schema fully documents the single 'url' parameter with concrete examples (HN URL, Algolia API URL, plain query). The description repeats this information nearly verbatim, adding no meaningful new semantics beyond the schema's 100% 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?

Clearly states it extracts top stories or search results from Hacker News, with a specific verb and resource. The tool name and sibling pattern make it stand out among other extract_* 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?

Provides clear context on what the tool does and what inputs it accepts (HN/Algolia URL or plain search query), but does not explicitly list alternatives or exclusions. The sibling names make the intended use obvious, so it meets the 'clear context, no exclusions' bar.

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

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

Annotations already declare readOnlyHint and openWorldHint, covering safety. The description adds nothing about operational behavior like how sources are queried, how results are aggregated, or what the output looks like. It merely lists sources without explaining the process.

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 tool's purpose. The list of sources is compact, though slightly dense with colon-separated items. It earns a high score for brevity without losing core information.

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

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

The tool integrates six data sources and is designed for idea validation, but the description does not explain what the agent should do with the result, what format the response takes, or how to interpret the composite. With no output schema and no return-value guidance, the description is incomplete for such a complex tool.

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

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

The input schema has full coverage of the single 'idea' parameter with a clear description ('Your idea, problem space, or keyword'). The tool description does not add additional semantics about how the parameter is interpreted, but since schema coverage is 100%, the baseline of 3 applies.

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

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

The description clearly identifies the tool as an idea validation composite and enumerates the six data sources it integrates (e.g., HN pain signals, YC funded competitors, GitHub crowding). This distinguishes it from sibling tools like extract_company_landscape or extract_hackernews, though the phrasing 'Idea validation composite' is more of a noun phrase than an explicit verb+resource 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 description implies the tool is for idea validation but provides no explicit guidance on when to use it versus alternatives. It does not mention any exclusions, prerequisites, or compare itself to sibling tools such as extract_landscape or package_trends.

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

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

Annotations already indicate read-only and open-world behavior. The description adds the composite nature (queries three sources) and that each source has its own freshness, but does not disclose potential rate limits, failure modes, or how freshness is represented. This is useful but not rich 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?

Three short sentences, front-loaded with 'Composite tool', followed by action and output. No superfluous 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?

No output schema, so description must convey return value, which it does at a high level ('unified landscape report with each source's own freshness'). However, it does not detail the report structure or behavior on partial source failures, leaving some gaps for a multi-source tool.

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

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

Schema covers 100% of the single parameter with a clear example. Description adds that the topic is used to query the three sources, which is a minor addition. Baseline of 3 applies as 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 it is a composite tool that queries GitHub, HN, and npm simultaneously and returns a unified landscape report. This clearly distinguishes it from single-source siblings like extract_github or extract_hackernews, and from other domain-specific landscape tools by specifying the exact sources.

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 cross-source landscape across GitHub, HN, and npm is needed, contrasting with individual source extractors. However, it does not explicitly name alternatives or state when not to use it, leaving some inference required.

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

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

Annotations already declare readOnlyHint and openWorldHint, which cover safety and open-world behavior. The description adds value by disclosing the exact return fields and the scope ('recent' launches), giving the agent a clear expectation of the tool's output. There is no contradiction with annotations, and the behavioral disclosure is sufficient for a read-only extraction tool.

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

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

The description is two sentences, front-loaded with the primary action, and directly lists the returned fields. Every word earns its place; there is no redundancy or filler. It is efficiently structured and immediately comprehensible.

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

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

For a tool with one simple parameter, no output schema, and solid annotations, the description is complete: it covers the input (search/URL) and the output (specific fields). The tool's simplicity means no additional details (e.g., pagination, rate limits) are necessary for an agent to invoke it correctly.

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

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

The input schema fully describes the single parameter 'url' as 'Search query or PH topic URL', and the description repeats this ('by keyword/topic search or a PH URL'). Since schema coverage is 100%, the description adds no meaningful semantics beyond the schema. Baseline of 3 is appropriate.

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

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

The description clearly states the tool's function: 'Extract recent Product Hunt launches by keyword/topic search or a PH URL.' It specifies the verb (extract), the resource (Product Hunt launches), and the output fields (name, tagline, votes, comment count, topics, launch date). This differentiates it from sibling tools that target other platforms (e.g., extract_hackernews).

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

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

The description provides clear usage context by indicating the two input modes: 'keyword/topic search or a PH URL.' This tells the agent when to use the tool (when Product Hunt data is needed) but does not explicitly mention when not to use it or compare it with alternatives. The context is clear, but exclusions are 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 mark this as read-only (readOnlyHint=true) and open-world (openWorldHint=true), so the description's main contribution is noting that it returns specific post metadata. It adds some context ('recent posts') but does not disclose rate limits, pagination, or what 'recent' means, which are common Reddit API behaviors.

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 compact two-sentence structure with no filler. It front-loads the core action and immediately follows with return-value details, making every sentence informative.

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

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

For a single-parameter tool with no output schema, the description covers both the accepted input forms and the fields returned per result. It is sufficiently complete for straightforward extraction, though it could optionally mention result limits or sort order, which is not critical.

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

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

The single parameter 'url' is already well-described in the schema ('Subreddit name e.g. r/MachineLearning or search URL'), and the tool description largely repeats that same guidance. With 100% schema coverage, the description adds no new parameter-level meaning beyond restating the existing example.

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 'Extract[s] recent posts from a subreddit' and explicitly lists the returned fields (title, subreddit, author, score, comment count, post date). This specific verb-object-resource combination distinguishes it from sibling extract_* tools like extract_hackernews or extract_github.

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

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

The description provides clear usage context: it accepts a subreddit name like 'r/MachineLearning' or a Reddit search/listing URL. While it doesn't explicitly mention when not to use it or name alternatives, the input scope is unambiguous enough for an agent to select this tool for Reddit post extraction.

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 safe-read nature. The description adds a valuable behavioral disclosure: Scholar only provides the publication year, not an exact date, capping freshness confidence at medium. This goes beyond annotations with useful data quality 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 two sentences: the first delivers the core purpose, the second adds a concise limitation. No wasted words or redundant 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?

Given the simple one-parameter schema and annotations, the description provides the necessary purpose, expected output fields, and a key limitation. The lack of an output schema is compensated by the explicit list of fields (title, authors, year, snippet). It fully covers the tool's scope.

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

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

The input schema fully documents the single `url` parameter with a description and format, so the schema carries the parameter semantics. The description merely restates that it takes a Scholar URL without adding format or usage details, 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 uses a specific verb ('Extract') and resource ('Google Scholar search URL') and enumerates the extracted fields (title, authors, year, snippet). This clearly distinguishes it from sibling tools like extract_arxiv or extract_reddit.

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

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

The description implies usage context by specifying the input type (Google Scholar URL) and output fields, but lacks explicit guidance on when to prefer it over alternatives or when not to use it. The clarity of the resource makes the intended use evident, but it doesn't name alternative tools or exclusions.

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

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

Annotations already indicate readOnlyHint and openWorldHint, so the description adds context about EDGAR full-text search and the legal nature of 8-K filings. Yet it does not disclose potential limitations such as date ranges, pagination, or specific search syntax, which would be valuable for a search tool.

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

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

The description is concise, with two sentences that front-load the purpose and method in the first sentence and provide context and usage in the second. Every word adds value; no filler.

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

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

For a simple single-parameter tool with annotations covering safety and open-world behavior, the description is fairly complete: it states what it does, how to call it, and the meaning of 8-K. The lack of output schema and detailed return format is acceptable, though a note about result size or limitations would push it higher.

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

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

The schema describes the single parameter 'url' as 'Company name, ticker, or keyword', and the tool description repeats this, giving clear semantics. However, the parameter name 'url' is misleading since it expects a search term, and the description does not provide examples or format details, so it doesn't add much beyond the schema.

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

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

The description clearly identifies the tool as retrieving SEC 8-K filings via EDGAR full-text search, with a specific resource and method. It also explains the nature of 8-K filings, distinguishing it from other extract_* tools, though it doesn't explicitly name an 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 implies usage for material event disclosures by defining 8-K, and provides a direct instruction to pass a company name, ticker, or keyword. However, it does not explicitly state when to prefer this tool over siblings like extract_finance or other SEC-related tools.

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

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

The description adds a meaningful behavioral caveat about data freshness ('Freshness is unknown') which goes beyond the readOnlyHint and openWorldHint annotations. It does not disclose potential scraping limitations or rate limits, but the freshness note is valuable context for an open-world data source.

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

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

The description is two sentences, front-loaded with the action, and includes the key return fields and a caveat without any wasted words. It is well-structured and easy to parse.

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

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

Without an output schema, the description meaningfully lists the per-company data returned (name, batch, status, tags, description) and notes the freshness caveat. For a single-parameter scraping tool, this is sufficient context.

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

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

The single parameter 'url' already has a full description in the schema with an example, and the description's reference to 'ycombinator.com/companies search URL' aligns with that. With 100% schema coverage, the description adds no extra 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 clearly states the specific action (scrape YC company listings) and the source URL type, distinguishing it from sibling extract_* tools. It also lists the exact data fields returned, leaving no ambiguity about the tool's function.

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

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

The description implies the tool is for scraping YC company listings but does not explicitly state when to use it over alternatives or provide exclusions. There is no mention of prerequisites or use cases where another tool would be more appropriate.

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

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

Annotations already declare the tool as read-only and open-world, so the baseline is covered. The description adds the specific data aspects (version history, release cadence, last updated) but does not address output format, pagination, or other behavioral traits. 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, compact sentence that directly states the tool's scope. Every word earns its place, and it is front-loaded with the key information.

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

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

For a simple one-parameter tool with a thorough schema and annotations, the description adequately covers the main returned data categories. However, since there is no output schema, a little more detail on the exact response structure would make it more complete.

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

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

The single parameter 'packages' is already fully described in the schema with a clear example ('langchain' or 'npm:zod,pypi:fastapi'), which provides 100% coverage. The tool description adds no further parameter-level 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 identifies the tool's function: providing npm and PyPI package metadata, specifically version history, release cadence, and last updated. It is specific about the resource and data types, and it distinguishes itself from the sibling extract_* tools which focus on other domains.

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

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

The description provides no guidance on when to use this tool versus alternatives. It simply states what it does without any context on use cases, selection criteria, or exclusions.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds valuable context beyond these: it indicates real-time freshness badges and the specific sources, which helps set expectations about result freshness and scope. It does not disclose details like pagination or rate limits, but for a read-only open-world search, this is adequate.

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

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

The description is two concise sentences, front-loaded with the primary action and resource. It includes the most relevant differentiators (freshness badges, sources) without unnecessary filler, earning a 5.

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

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

For a simple 2-parameter tool with no output schema and annotations covering safety, the description is largely sufficient. It specifies sources and a key output trait (freshness badges), though it could mention the meaning of max_length or return format. Given the low complexity and good annotation coverage, this is a 4 rather than a 3.

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 50%: the 'query' parameter has a helpful description with an example, but 'max_length' has no description. The tool description does not add any semantic detail for the parameters, leaving max_length's meaning and purpose undocumented. This is a middle-ground score because the primary parameter is well-explained but the secondary one is not.

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 'Search' and the resource 'real-time job listings', with specified sources (Remotive + HN Who is Hiring). This distinguishes it from sibling tools like search_repos and extract_* tools, making the tool's purpose unambiguous and specific.

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

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

The description implies usage for finding job listings from the two named sources, providing clear context for when to use the tool. However, it does not explicitly state when not to use it or name alternative tools, so it stops short of a 5.

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

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 it's a safe, open-ended read. The description adds one useful behavior detail: 'Returns top results by stars,' but it does not mention result limits, pagination, or other operational specifics. This adds some context beyond annotations but remains limited.

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

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

Two sentences with zero waste. It front-loads the action and resource, then adds the key behavioral detail about star-based ranking. Perfectly concise for a tool with one parameter.

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

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

Given the tool's simplicity—one parameter, clear annotations, and no nested objects—the description covers the essential behavior. The absence of an output schema does not require a detailed return description per the rules, and the star-ranking note provides sufficient context. A slightly richer mention of result count or sorting options would push it to 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?

The schema provides 100% coverage for the single 'query' parameter with an example ('mcp server typescript'). The description's 'matching a keyword' adds no new meaning, so the baseline score of 3 applies.

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

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

The description clearly states the action (Search), resource (GitHub repositories), and scope (matching a keyword). It distinguishes itself from the sibling extract_* tools by focusing on keyword-based search rather than extraction from specific sources.

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 use case—searching repos by keyword—but does not explicitly state when to use this over alternatives or when not to use it. With many sibling extract tools, a note on preferring this for broad repo discovery would be valuable.

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