countries

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

Annotations already cover read-only and idempotent behavior, and the description adds valuable context beyond annotations: it discloses that probing Anthropic incurs direct costs to the user ('you pay Anthropic directly'), describes external API call behavior, and details the return structure. This is meaningful additive transparency, though it omits edge-case behavior like missing API key errors.

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

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

The description is three sentences, front-loaded with the core action and output, then cost details, then return format, then use cases. Every sentence earns its place with no redundancy, making it appropriately sized 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?

No output schema exists, so the description compensates by providing the return structure (per-model {score, confidence, signals, raw_response} + combined view). It also covers cost, default behavior, and use cases. However, it does not address potential error conditions (e.g., unsupported model names or missing API key for Anthropic), leaving it slightly incomplete.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds some context about the default model and cost implications, but these are already partially in the schema's model description. It does not provide additional semantics for parameters like 'entity' or 'context' 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 clearly states the tool's function with a specific verb ('Probe') and resource ('one or more LLMs'), and explains the output (visibility score 0-100). However, it does not explicitly distinguish this tool from similar siblings like scan_competitor_ai_presence, so it lacks explicit 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 provides clear usage context by listing use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains the default vs. paid model choice (Workers AI free, Anthropic BYO key). It gives clear context on when to use, but does not name alternatives 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 read-only, idempotent, open-world, and non-destructive behavior. The description adds beyond that: it routes to other tools, fills arguments, returns structured answers with stable pipeworx:// citation URIs, works on every tier, and is described as one fast call. This gives useful behavioral context without contradicting 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 long but information-dense, front-loaded with the key instruction 'PREFER OVER WEB SEARCH' and clear examples. Lists and domain coverage are justified, and references to alternatives are valuable, though it is slightly verbose.

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 explains what answers look like (structured data, citations) and covers discoverability, routing, domain coverage, examples, and alternative escalation paths. It is strong for a general-purpose question routing tool, with only minor gaps around edge-case failures or response limits.

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 aliases clearly. The description reinforces that the parameter is a natural-language question, and gives examples, but it does not add new detail beyond what the schema already provides, so the baseline of 3 is appropriate.

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

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

The description clearly identifies the tool as the default entry point for factual questions requiring authoritative structured data, with a specific verb ('routes the question') and a broad but scoped resource (5,566 tools across 1,462 verified sources). It distinguishes itself from sibling tools like ask_pipeworx_grounded and deep_research.

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?

Explicit guidance says to prefer this over web search, start here for most questions, and 'step up only when needed' with named fallback tools for grounded answers and broad research. It also clarifies that breaking-news and opinion-style queries are handled here.

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, open-world, idempotent, non-destructive behavior. The description adds important context about the experimental nature, the current absence of an active candidate, that it fully works without fallback, and that its responses are compared against the stable router. No contradiction with annotations found.

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

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

The description is compact and front-loaded with the key 'beta' identity, followed by relevant operational state, usage direction, and a clarifying caveat. It is slightly dense and includes specific detail like the 2026-07-26 retirement date, but that detail helps explain the current 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?

The description covers the tool's scope, current state, how it relates to ask_pipeworx, and the full working router status. Although there is no output schema, the claim of 'same response shape as ask_pipeworx' provides enough grounding for a tool that is explicitly a beta twin.

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 is fully documented: question is the required natural-language field and all five aliases are explicitly listed. The description only restates that arguments are the same as ask_pipeworx, so it does not add meaning beyond the schema's existing high coverage.

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

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

The description clearly identifies this as 'Beta version of ask_pipeworx' and explains it is an identical universal router with the same 5,566 tools, arguments, and response shape. It differentiates from the stable ask_pipeworx sibling by framing it as the experimental edge with candidate routing improvements.

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

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

The description explicitly says to 'Use it exactly like ask_pipeworx when you want the newest routing' and notes that results are compared against the stable router. It does not enumerate exclusions or alternatives like ask_pipeworx_grounded, but the primary use case is clearly 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?

Goes beyond the read-only/idempotent annotations by detailing the exact success return shape, the full set of refusal reasons, and the behavior of refusing when data doesn't directly answer. Also discloses the extra cost relative to ask_pipeworx, which is not captured in any annotation.

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

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

The description is compact yet information-dense: opens with the core purpose, explains the mechanism, specifies return/refusal shapes, gives usage guidance, and closes with the cost trade-off. Every sentence contributes new value with no redundancy or filler.

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

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

Given the absence of an output schema, the description fully compensates by specifying the success payload, all refusal reason enums, and when/how refusals occur. It also situates the tool against ask_pipeworx, covers use cases, and identifies the extra cost. This is complete for a question-answering tool.

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

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

The input schema already documents the `question` field and its aliases (q, text, input, query, prompt) with 100% coverage. The description adds no additional parameter-level detail beyond the schema, so it meets the baseline but doesn't exceed it. The mention of 'fills arguments' is behavioral, not parameter-specific.

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 is a 'hallucination-resistant answer mode for high-stakes reads' that routes like ask_pipeworx and extracts answers strictly from tool results. Distinguishes itself from the sibling ask_pipeworx by noting it costs an extra LLM call and is for scenarios where facts must not be invented.

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

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

Explicitly says 'Use whenever an answer will be quoted, cited, or acted on' and lists high-stakes domains. Also gives a clear alternative: 'prefer ask_pipeworx for casual lookups,' making the when-to-use vs. when-not-to-use boundary unambiguous.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false, so the safety profile is already known. The description adds far more: resolver contract with confidence levels and alternatives, blocking low-confidence/closed-market paths, wide-spread illiquidity handling, cancellation-rule parsing, and news fallback flags. This is rich behavioral transparency beyond the annotations.

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

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

Though long, the description is tightly structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, SAFETY, RESOLUTION-RULE RISK). Every sentence adds specific, non-redundant information. The main purpose is front-loaded, and no filler exists.

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 comprehensively covers result shapes, edge cases (low-confidence, closed markets, wide spreads), fan-out behavior, and rule-based risks. It is fully sufficient for an agent to understand what the tool returns and how to handle failure modes, given the tool's complexity.

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

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

Schema description coverage is 100%; the schema already explains market, depth, and include_raw. The description does not add material parameter-level guidance beyond the schema (e.g., it does not explain depth tradeoffs or include_raw size implications any further). Per the rubric baseline, a 3 is appropriate.

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

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

The description opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly distinguishes from siblings by describing the resolver, classifier, fan-out, and comparison output. The 'Use for' examples reinforce the intended use case.

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 usage context with explicit 'Use for' examples ('should I bet on X', 'what does the data say about Y'). However, it does not explicitly mention when NOT to use it or name alternatives (e.g., polymarket_edges, ask_pipeworx), so it stops short of a full when/when-not guide.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds significant behavioral context: data sources (SEC EDGAR/XBRL, FAERS, FDA), handling of off-calendar fiscal years, sorted results by primary metric, and paired data with citation URIs. 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 front-loaded with trigger phrases and a clear purpose. Each sentence adds value: parallel call efficiency, type-specific data, sorting behavior, and citations. Though moderately long, it is dense and free of 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 discloses return format (paired data + citation URIs), sorting behavior, and the specific data fields retrieved. It covers edge cases like off-calendar fiscal years. The only minor ambiguity is "primary metric," but overall it is complete for an agent to invoke correctly.

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

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

Schema coverage is 100% with descriptions for type and values, but the tool description adds substantial meaning: what each type pulls (company financials; drug adverse events), acceptable inputs for each (tickers/CIKs vs drug names), and the 2–5 range is reiterated with examples. This goes well 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 tool's purpose: side-by-side comparison of 2–5 companies or drugs in one parallel call. It uses specific trigger phrases like "Compare X and Y" and "X vs Y" and distinguishes itself from siblings by emphasizing it replaces sequential single-pack lookups.

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

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

The description provides explicit usage guidance: "ALWAYS PREFER over sequential single-pack lookups when comparing entities" and gives concrete example intents (which is bigger/better, rank these companies). It differentiates between company and drug types and says it replaces 8–15 sequential lookups, implicitly telling when not to use single-entity tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds value by listing the return fields (name, capital, region, currency details), which is not provided by annotations. It does not contradict any annotation.

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

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

The description is a single concise sentence with clear purpose, examples, and return fields. It is well-structured, front-loaded with the verb, and every word serves a purpose.

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

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

Given the single parameter, existing output schema, and rich annotations, the description covers all essential aspects: purpose, example inputs, and output fields. No critical information is missing for an agent to correctly invoke the 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 fully describes the 'currency' parameter with 100% coverage, including examples and accepted formats ('eur', 'usd', 'dollar'). The description's examples repeat the schema examples and add no new parameter semantics.

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

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

The description uses the specific verb 'Find' with a clear resource ('countries using a currency') and is easily distinguished from sibling tools like countries_by_language and countries_by_region. The examples (EUR, USD) further clarify the domain.

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 needing countries for a given currency) but does not explicitly mention alternatives or provide exclusions. For instance, it does not say 'for countries by language, use countries_by_language'. Thus, it provides clear context but lacks explicit guidance relative to sibling tools.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds context about the return payload (name, capital, region, population, official language status), which goes beyond the annotation hints. 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?

The description is a single sentence that front-loads the action and resource, then specifies expected outputs. Every word contributes, with no 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?

With one parameter, a complete schema, and an output schema, the description sufficiently covers the tool's behavior and return values. No additional context is needed for a simple lookup tool.

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

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

Schema coverage is 100% with a clear parameter description and examples. The tool description's examples ('Spanish', 'Mandarin') are redundant with the schema, so it does not add significant additional meaning beyond the baseline.

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

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

The description uses a specific verb ('Find') and clearly identifies the resource ('countries') and the filtering criterion ('where a language is spoken'). It also lists the returned fields, making it distinct from sibling tools like countries_by_currency or countries_by_region.

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 use case: when you need countries for a given language. It gives examples but does not explicitly mention alternatives or exclusion scenarios, 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 provide strong safety signals (readOnlyHint=true, destructiveHint=false), which lowers the bar for behavioral disclosure. The description adds useful context by listing return fields, but does not mention any other behavioral traits such as case sensitivity, error handling, or pagination. This is adequate but not rich.

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

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

The description is a single sentence that immediately states the action, provides an example, and lists output fields. Every word earns its place, 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?

For a simple one-parameter tool with a clear output schema and comprehensive annotations, the description is complete. It covers the core functionality and return values, and the schema handles the parameter details. There are no missing pieces that would prevent 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 coverage is 100%, and the schema documents the 'region' parameter with allowed enum values (africa, americas, asia, europe, oceania). The description's examples ('Africa', 'Europe', 'Asia') are capitalized, which could conflict with the lowercase schema values, creating minor ambiguity. It adds no new parameter meaning beyond what the schema already provides.

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

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

The description clearly states the action ('List all countries in a region') and the specific resource scope. It distinguishes itself from sibling tools like countries_by_currency and countries_by_language by focusing on region filtering, and mentions the return fields (name, capital, population, area, flag emoji) which adds specificity.

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

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

The description gives clear context for when to use this tool (when you need countries by region) but does not explicitly mention alternatives or exclusions. Since there are closely related sibling tools (e.g., countries_by_currency), a brief note about using those for currency-based lookups would elevate it to 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 readOnly, openWorld, and idempotent, but the description adds essential behavioral context: account requirements, paid tiers, parallel tool routing, gap recovery and contradictions, hop fields, citation resolvability, excerpting, and performance expectations. 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 dense and comprehensive, but it forms a single long paragraph that could be better structured with separators or bullet points. However, every sentence adds value and there's no fluff. It's front-loaded with the critical account requirement.

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 compensates by explaining the return format: findings packet with verbatim evidence, confidence, source, fetched_at, and pipeworx:// citations, plus gaps[] and contradictions[]. It also covers edge cases like large-record excerpting and performance timelines, making it complete for 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?

Schema coverage is 100%, but the description goes beyond by explaining depth semantics: 'quick=3 (single hop)' and 'standard' adds gap-recovery and contradictions, 'thorough' adds iterative lead-chasing. It also clarifies that questions can be broad/multi-part, adding meaningful context to the 'question' parameter.

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

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

The description clearly states the tool's function: 'Grounded multi-source research across Pipeworx's 1462 STRUCTURED data sources ... in ONE call'. It explicitly contrasts with open-web search and names sibling tools like ask_pipeworx, making its unique position unambiguous.

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

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

The description provides explicit guidance: 'Best for broad/multi-part questions over structured data', and contrasts with 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. It also notes the account requirement and alternative for non-signed-in users.

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 idempotentHint=true, covering the safety profile. The description adds valuable behavioral context: it returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples)' and notes 'each result is ready to call directly, no second schema lookup needed.' This discloses return format and behavior that annotations do not.

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

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

The description is three sentences and front-loaded with the core purpose. The middle sentence lists many domains, which is slightly lengthy but directly informative about scope. The final sentence gives important usage context. No wasted words, though the domain list could be condensed without losing value.

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

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

The description explains what the tool returns (top-N tools with names, descriptions, schemas, examples), when to use it (first when many tools available), and its non-destructive nature via annotations. There is no output schema, but the description covers the return format well enough for an agent to use the tool effectively. Missing only minor details like pagination or error handling, which are not critical for a discovery 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%, so all parameters are already documented with meaningful descriptions. The description does not add significant parameter-level detail beyond the schema; it only reinforces that the query is a natural language description. This meets the baseline for full schema coverage.

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

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

The description clearly states the tool's function: 'Find tools by describing the data or task.' It uses a specific verb ('find') and resource ('tools'), and the phrase 'browse, search, look up, or discover what tools exist' distinguishes it from sibling tools that perform actual data queries. The list of domains further clarifies scope 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?

Explicit guidance is provided: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set.' This tells the agent exactly when to invoke this tool versus alternatives, and the 'FIRST' directive implies it is a precursor to selecting other tools.

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

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

Beyond the read-only/idempotent annotations, the description discloses concrete behavior: parallel fan-out across SEC EDGAR, XBRL, USPTO, news, and GLEIF; a patents API sunset with soft-fail; a GDELT→GNews fallback; and specific returned fields. This gives the agent a clear model of what happens at runtime.

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 dense and front-loaded with usage examples, but the listing of multiple paraphrased triggers ("Tell me about X" / "research Acme" / "brief me on Tesla") is somewhat redundant. Still, every substantive sentence contributes details about sources, return structure, and limitations, so it earns a 4 rather than a 3 or 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?

With no output schema, the description thoroughly compensates by enumerating return components (cik, company_name, recent_filings with URIs, fundamentals fields, patents, news, LEI), plus failure modes and fallbacks. It also covers input constraints and the recommended path for name-only inputs, making the tool fully self-contained.

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

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

Schema description coverage is 100%: both type and value are fully described, including ticker/CIK examples and the name limitation. The description largely repeats this information (e.g., "Pass ticker 'AAPL' or zero-padded CIK..."), adding no new semantic value beyond what the schema already provides.

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

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

The description clearly defines the tool as generating a "full cross-source profile of a US public company" with a specific verb (profile/brief) and resource (entity). It differentiates from siblings by explicitly noting it should be preferred over chaining single-pack SEC/XBRL/news lookups and by directing name-only requests to resolve_entity.

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

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

The description gives explicit when-to-use guidance: "ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view." It also states a key exclusion (names not supported, use resolve_entity) and provides alternatives, making usage conditions unambiguous.

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

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

Annotations already indicate destructive and idempotent behavior, but the description adds context that the deletion targets previously stored memory and is appropriate for clearing sensitive data. It clarifies the scope of destruction beyond the raw annotation.

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 focused sentences: action, when to use, and related tools. No redundant phrasing; every sentence earns its place. Front-loaded with the core action.

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

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

For a simple one-parameter delete tool with strong annotations and full schema coverage, the description provides all necessary context: purpose, usage timing, data sensitivity, and sibling relationships. No gaps for an agent to misuse 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 has 100% coverage for the key parameter ('Memory key to delete'). The description reinforces this with 'by key' and adds meaningful connection to remember/recall, helping the agent understand the key refers to a memory previously stored. This slightly exceeds the schema baseline.

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

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

The description opens with 'Delete a previously stored memory by key' – a specific verb (delete), resource (memory), and method (by key). It clearly distinguishes itself from sibling tools remember and recall, leaving no ambiguity about its role.

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

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

Provides explicit 'Use when' conditions: stale context, task completion, clearing sensitive data. Also instructs to 'Pair with remember and recall', positioning it within a workflow. No alternative is confused with 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, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds operational context by stating it 'Fetches the page, extracts title/description/key links' and produces a 'single text blob ready to drop at site-root/llms.txt.' This goes beyond the annotations by describing the actual behavior and output format, 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 concise and front-loaded: the main purpose is stated immediately, followed by process, output, and use cases in a tight 3-sentence structure. Every sentence earns its place with 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 tool with only two parameters and no output schema, the description is complete: it covers purpose, process, output format, and use cases. Annotations handle safety and idempotence, and the schema documents parameters thoroughly. No additional context is necessary for correct selection and invocation.

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

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

Schema coverage is 100% with two parameters already well described (url example, max_links default and max). The tool description does not add extra parameter semantics beyond what the schema provides, so it meets the baseline for high coverage but doesn't 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 ("Generate") and names the resource ("llms.txt file for any URL"), then details the process (fetches, extracts, emits). It clearly distinguishes this tool from sibling tools like ai_visibility_check or scan_competitor_ai_presence, which focus on visibility checks rather than file generation.

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 three concrete use cases (client indexing, personal project drafting, competitor auditing) that make it clear when to invoke the tool. However, it does not explicitly contrast with any sibling tool or state when not to use it, so it falls short of the full 'when/when-not/alternatives' standard.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the list of returned fields (capital, population, etc.), which is useful behavioral context but not particularly novel beyond what the output schema likely provides. It doesn't disclose additional traits such as rate limits or error behavior, but given the read-only nature, 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 two sentences long, front-loaded with the action verb 'Get' and the resource 'country details', followed by illustrative examples and a concise list of returned fields. Every sentence earns its place with no redundancy or unnecessary fluff.

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

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

For a simple single-parameter read-only tool with full schema coverage, annotations, and an output schema, the description is complete. It states the purpose, gives examples, and lists return fields, covering all necessary contextual information without needing further elaboration.

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%, meaning the parameter 'code' is fully documented as 'ISO 3166-1 alpha-2 or alpha-3 country code'. The description only adds examples, which reinforce but do not add new meaning. Therefore, 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 gets country details by ISO code, with examples. It distinguishes itself from sibling tools like countries_by_currency or search_countries by specifying the lookup key (ISO code) and the specific data fields returned, making its purpose unambiguous.

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

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

The description clearly indicates that this tool is appropriate when you have an ISO country code, providing examples. It does not explicitly mention alternatives or when not to use it, but the context is clear enough for an agent to infer it should be used over name-based search when a code is available. Lacks explicit exclusions or alternative tool references.

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, idempotent, and non-destructive behavior, so the bar is lower. The description adds valuable context beyond this by listing the exact return fields (id, type, params, created_at, last_fired_at, fire_count) and clarifying that it lists active subscriptions by default, which aligns with the include_inactive parameter. 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 two sentences, front-loaded with the action and resource, then returns fields, then usage guidance. Each sentence serves a distinct purpose with no filler or redundancy.

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

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

For a simple list tool with one optional parameter and strong annotations, the description is complete: it states what it lists, the fields returned, and the intended use cases. The lack of an output schema is mitigated by listing return fields in the description.

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 include_inactive, so the schema already fully explains its meaning and default. The description's mention of 'active subscriptions' indirectly reinforces the parameter's purpose but adds no new 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 starts with a specific verb and resource: 'List the caller's active subscriptions.' It clearly distinguishes this from sibling tools like subscribe and unsubscribe, and specifies the scope (caller's active subscriptions) and the returned fields, making the purpose unambiguous.

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

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

The description explicitly states when to use the tool: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This provides clear context for usage relative to subscribe/unsubscribe alternatives, even though it doesn't name them directly.

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

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

No annotations provide behavioral hints (all false), so the description carries full burden. It discloses rate limiting ("Rate-limited to 5 per identifier per day"), that it is free and doesn't count against tool-call quota, and explains the claim_token flow (filing returns a token; passing it later reads status and changes). It also notes the team reads digests daily, adding context on how feedback is processed.

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 lengthy but every sentence earns its place: purpose, usage scope, boundaries, claim_token workflow, rate limits, and content guidance. It is front-loaded with the main action and uses clear, structured sentences that progressively add essential details without redundancy.

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

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

For a tool with no output schema and no required parameters, the description is complete: it explains what the tool does, when to use it, what to include, rate limits, and the claim_token lifecycle (both filing and reading results). It also covers scope limitations, so an agent knows exactly how to invoke it correctly.

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

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

Schema coverage is 100% with detailed descriptions, so the schema already explains parameters. The description adds meaningful usage context beyond the schema, especially for claim_token (how to use it to read replies) and message (what to include/exclude, e.g., "don't paste the end-user's prompt"). This supplemental guidance justifies a score above baseline, though not a 5 since the schema already covers basics.

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

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

The description states a specific verb+resource: "Tell the Pipeworx team something is broken, missing, or needs to exist," and clarifies the feedback categories (bug, feature, data_gap, praise). It also distinguishes the tool from other servers' feedback tools by explicitly limiting scope to Pipeworx connection 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 provides explicit when-to-use guidance: use for wrong/stale data, missing tools, or praise, and when-not-to-use: "if the tool came from a different MCP server... file it with that server instead." It also instructs users to describe issues in terms of Pipeworx tools and not paste end-user prompts, offering clear alternatives.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds valuable context about caching (5min-1h), data provenance (CF analytics-engine), and privacy (no PII), going beyond the structured 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 compact yet information-dense, using a clear list for use cases and concise statements about caching and data. No redundant 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?

Despite no output schema, the description explains the return contents (top tools, top packs, total call volume) and caching behavior. It fully contextualizes the tool for an agent, covering what, why, and how data is sourced.

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

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

The input schema already provides 100% coverage of the single 'window' parameter with detailed descriptions. The overall description restates the window options but doesn't add semantic nuance beyond the schema, so 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 the tool returns top tools, packs, and call volume for recent windows, with specific use cases. It distinguishes itself from siblings like discover_tools by focusing on aggregate trend data rather than individual tool discovery.

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 'Useful for' section explicitly lists three scenarios for when to use the tool, including discovering hot data sources and validating tool choice. It doesn't mention alternatives or exclusions, but the context is clear.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive, so the bar is lower. The description still adds substantial behavioral disclosure: the >3pp threshold for signals, the semantic anchor Jaccard similarity, the placeholder fraction filtering, and the fill check condition 'realizable_edge_pp ≤ 0 means ... do not trade it.' These are not present in 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 long but well-organized with labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loaded with the main usage. Every sentence contributes meaningful information, though some redundancy exists between the intro and the response-field listing. It is dense but earned.

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 fully documents the return shape: opportunities[], partition_check, fill_check fields, and the condition for trading. It covers edge cases (low similarity, placeholder filters, thin legs) and mentions limitations (realizable edge at book). The complexity of the tool is high, and the description addresses all major behavioral aspects.

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

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

Schema coverage is 100% and schema descriptions are already rich. The description adds further meaning beyond the schema: event slugs accept full URLs, topic uses a seed question for cross-event scan, and it explains how each parameter changes the algorithmic behavior (walks child markets vs searches related events). This goes beyond input format into decision-relevant semantics.

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

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

The description opens with a specific verb and resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes the three invocation modes (no args, event, topic), each with distinct semantics. This sets it apart from siblings like polymarket_edges and polymarket_fill_risk.

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

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

Provides explicit when-to-use guidance: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', and explains cross-event mode 'catches ... patterns that single-event misses.' It also directs users to polymarket_fill_risk for custom sizing, giving an alternative for a related use case.

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

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

The description extensively discloses internal behavior beyond annotations: the three model families, edge calculation details (slippage, Kelly capping), the 24h-move warning, partition-specific filters, response structure with diagnostics, and caching keyed on knobs. This far exceeds the read-only/idempotent annotations, giving agents a rich understanding of what happens when they call the 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 long but every sentence carries operational detail. It is front-loaded with purpose and then compresses a large amount of useful behavioral information. While not exceptionally concise, it is appropriately sized for the tool's complexity and has no redundant 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?

With no output schema, the description fully covers response structure (by_segment, fed_candidates, _diagnostics), explains why segments might be empty (funnel counters, filter_skips), describes caching behavior, and documents edge interpretation caveats. This makes the tool self-contained for an agent to understand inputs, outputs, and pitfalls.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful context on top of the schema, particularly for min_partition_leg_kelly (explaining why min_kelly doesn't apply to partitions and that per-leg Kelly is inside top_legs) and the tradeable-edge knobs (min_liquidity/max_spread_pp). This elevates it above the baseline.

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

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

The description opens with a specific verb+resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' This clearly distinguishes the tool from siblings like polymarket_arbitrage or polymarket_edge_tracker by focusing on opportunity discovery via Pipeworx data vs market price.

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

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

It provides clear usage context: 'Built for "what should I bet on today"' and notes agents can 'discover opportunities without paging hundreds of markets.' This implies a discovery use case and contrasts with manual paging, but it doesn't explicitly name alternative tools or state when not to use this tool, 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?

The description extensively discloses behavior beyond the readOnlyHint annotations: response structure (tracked/expired/snapshot_dates), trend categories, decay computation on absolute value, signed edge_pp_net, snapshot gaps, TTL limits, and daily-close frequency. This far exceeds annotation baselines.

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 long but well-structured with Args, RESPONSE, and LIMITS sections. Every sentence carries operational detail; given no output schema, this level of detail is necessary and earns its place.

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

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

The tool has no output schema, so the description must compensate by fully documenting return values and edge cases. It does so: tracked[], expired[], snapshot_dates[], trend values, decay semantics, TTL boundaries, and data-gap behavior. The description is complete for an AI agent to select and invoke the tool correctly.

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

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

Both parameters are already fully documented in the schema (100% coverage). The description adds helpful context by explaining days as lookback and window as snapshot family, with defaults and max, but it omits the lower clamp (present in schema). This adds some meaning beyond the schema, so a 4 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 as 'edge persistence and decay telemetry' and frames the question it answers ('how long has this edge existed and is it shrinking?'). It distinguishes itself from the sibling polymarket_edges by being snapshot-based and tracking history rather than current edges.

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 when to use it: when edge age and decay matter, contrasting fresh vs old wide edges. However, it does not explicitly name alternatives or state when not to use it, 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?

The annotations already indicate readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds substantial behavioral context: it walks the order-book ladder, returns verdicts (clean|degraded|cannot_fill), identifies thin_legs and forced_directional_risk, and explains how partial fills can create unhedged directional exposure. This goes well beyond the annotations' safety profile.

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 long but every sentence provides necessary detail for a complex tool. It front-loads the core purpose and uses uppercase keywords (REQUIRES, SINGLE-MARKET, BASKET) to structure the content. It could be slightly more concise or use bullet points, but it avoids redundancy and remains efficient for the level of complexity.

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

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

Given the tool has 4 parameters, no output schema, and two distinct usage modes, the description is remarkably complete. It enumerates the return fields for both single-market and basket modes, covers edge cases (thin_legs, cannot_fill), and provides practical context about when the tool is necessary. The agent has enough information to invoke it correctly without additional lookup.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful semantics on top of the schema: it explains that size_usd means 'max spend' on buys but 'target proceeds' on sells in single-market mode, and 'settlement notional' (shares per leg) in basket mode. It also clarifies the default side behavior in basket mode (auto from partition sum), which is not in the schema descriptions.

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

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

The description opens with a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth,' which clearly defines the tool's function. It explicitly distinguishes its two modes (single-market vs basket) and differentiates from siblings like polymarket_arbitrage and polymarket_edges by focusing on fill risk rather than edge detection.

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

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

The description provides explicit usage guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains when NOT to rely on theoretical edge ('theoretical overround on thin books is not capturable') and warns about partial basket fills converting arb into unhedged positions, giving clear alternatives and 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 description goes far beyond the annotations, which are minimal (readOnly, openWorld, idempotent, not destructive). It exposes detailed behavioral nuances: compatibility_warning reasons (e.g., non-equivalent bet shapes, semantically unrelated events), temporal_alignment field meaning, and skipped_cross_type/subtype counters. It even warns that results can be misleading if temporal alignment is false. This is exemplary transparency.

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

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

The description is long but information-dense. Every sentence earns its place, from the core purpose to the safety fields and the final caveat. It is front-loaded with the main idea and then systematically explains modes, response, and warnings. The use of caps for mode names and field names aids scanning, though it could benefit from bullet points or section breaks. Slightly dense but appropriately sized for the tool's complexity.

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

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

Given the tool has no output schema and relatively few parameters, the description fully compensates by detailing the response structure (leg-by-leg prices, spread in pp), the meaning of safety fields, and the conditions under which spreads are meaningful. It addresses edge cases like incompatible bet shapes and temporal misalignment. For a tool with this complexity, the description is remarkably 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?

Although the schema already documents all three parameters with descriptions (100% coverage), the tool description adds semantic depth by explaining how the 'topic' shortcut relates to the explicit 'kalshi_event_ticker' and 'polymarket_event_slug', including the override behavior. It also enumerates the valid topic values in the narrative, reinforcing the schema. This adds value beyond the schema, justifying a score above the baseline 3.

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

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

The description opens with a clear, specific statement: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' This concisely captures the tool's function and distinguishes it from sibling tools like polymarket_arbitrage or polymarket_edges, which focus on a single venue or different aspects. The statement about venue pricing discrepancies further clarifies the tool's intent.

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 explains when to use the tool by outlining two modes ('topic' for pre-mapped shortcuts, explicit tickers for custom pairings) and provides strong caveats: 'Real cross-venue spreads are rarer than the macro-shortcut list suggests... pre-mapped ≠ tradeable.' It warns about scenarios where the tool returns a compatibility warning, acting as an implicit 'when-not-to-trust' guidance. However, it does not explicitly name alternative tools or contrast with siblings, so it stops short of a perfect 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 read-only, idempotent, and non-destructive behavior. The description adds meaningful context beyond that by explaining the scoping to an identifier (anonymous IP, BYO key hash, or account ID) and the behavior of listing all keys when the key argument is omitted.

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

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

The description is three sentences, front-loaded with the core action. It includes targeted examples, scoping, and pairing with related tools, with no superfluous information. It is slightly longer than minimal but every sentence earns its place.

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

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

For a simple one-parameter tool with no output schema, the description adequately covers how to use it, what it returns (a value or list of keys), and important contextual details like scoping and the remember/forget pairing. It is complete for the tool's complexity.

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

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

Input schema already provides 100% coverage, describing the key parameter and noting 'omit to list all keys.' The description adds examples of key values (e.g., user's target ticker) but does not provide any additional parameter syntax or format details, so the baseline of 3 is appropriate.

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

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

The description opens with a specific verb+resource: 'Retrieve a value previously saved via remember, or list all saved keys.' It clearly distinguishes itself from siblings like 'remember' (save) and 'forget' (delete), and includes concrete examples of use cases.

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 usage context: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It implicitly covers when not to use (i.e., for new information) and mentions the related tools remember and forget, though it does not explicitly name alternatives 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?

The description states that setting mark_read:true flags returned events as read and makes 'the next call only shows newer ones,' which is a state-changing side effect. This directly contradicts the readOnlyHint:true annotation, which claims the tool is read-only. This is an annotation contradiction, so the score is 1 per rubric.

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 four sentences and front-loads the main action before details. It packs useful extras like the external endpoint and mark_read behavior without filler, though it could be slightly tighter.

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 compensates well by specifying return fields (source, citation_uri, raw event payload), filter options, and the mark_read workflow. It also mentions the external URL for scripts/dashboards, making the tool self-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?

All five parameters have schema descriptions (100% coverage), so the baseline is 3. The description adds concrete value by providing a type example ('sec_8k'), explaining the consequence of mark_read:true, and reinforcing the ISO timestamp format for since, which goes 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 and resource: 'Pull fired events from your subscription feed.' It clearly identifies the tool as alert retrieval and differentiates it from siblings like list_subscriptions and recent_changes by emphasizing the persisted evaluator feed and event payloads.

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 clear usage context: filtering by type and/or since, using mark_read to advance the feed, and explicitly notes that polling works fine. It doesn't explicitly name alternatives or exclusion cases, but the context is strong enough for an agent to know when to use it.

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

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

Annotations declare readOnly/idempotent/non-destructive, and the description adds substantial behavioral context: it fans out to SEC EDGAR, GDELT/GNews with fallback logic, USPTO with a soft-fail note due to PatentsView sunset, and date format handling. This goes beyond the annotations to help the agent anticipate real-world behavior.

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

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

The description is dense but every sentence is purposeful: natural language triggers, sources and fallbacks, date formats, return structure, and sibling distinction. No filler. The structure front-loads the most important usage semantics and then covers edge cases and alternatives.

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 (multiple upstream sources, fallback behavior, date parsing, output shape) and lack of an output schema, the description is remarkably complete. It covers sources, failure modes, parameter formats, return summary, and differentiation from sibling tools, leaving little ambiguity for the agent.

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

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

The schema already covers all parameters (100% coverage). The description adds value by explaining the `since` parameter's dual format (ISO or relative), recommending '30d' or '1m' for typical monitoring, and giving examples for `value`. This is more than the schema alone provides, though the schema still carries most of the weight.

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

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

The description clearly states the tool provides a change feed for a company over a time window, with explicit examples of natural language queries that map to the tool. It distinguishes from the sibling entity_profile by explicitly referencing when to use that alternative 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?

The description gives concrete usage examples and context ('What's new with X' / 'latest on Y'), and explicitly says to use entity_profile for static profiles. It also explains the fallback behavior between GDELT and GNews, providing clear guidance on behavior under different conditions.

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

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

The description discloses storage mechanics beyond the annotations: key-value pair scoped by agent identifier, persistence differences between authenticated and anonymous sessions (24 hours), and relationship to related tools. Annotations only indicate idempotent, non-destructive, and non-read-only, so the description adds significant 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?

Three sentences, front-loaded with the core purpose. The middle sentence provides concrete use cases, and the final sentence covers storage mechanics and persistence. Every sentence contributes critical guidance with no fluff.

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

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

For a simple tool with two parameters, no output schema, and clear annotations, this description is complete. It covers what, when, why, and how, plus integration with recall and forget. No missing information or ambiguity remains.

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

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

The schema already fully describes both parameters (key, value) with examples. The description adds the semantic nuance that the pair is 'scoped by your identifier,' clarifying that keys are not global and are tied to the caller, which is not present 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 states a specific action ('Save data the agent will need to reuse later') with a clear resource (data keyed by identifier). It distinguishes from sibling tools by explicitly telling the user to 'Pair with recall to retrieve later, forget to delete.'

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: 'Use when you discover something worth carrying forward' with concrete examples (ticker, address, preference). It also names the companion tools (recall, forget), providing context on the lifecycle and alternatives.

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

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

The description discloses significant behavioral traits beyond the annotations. Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds: cascading through multiple lookup endpoints, graceful degradation when GLEIF/OpenFIGI are unavailable (EDGAR still returns), and that unresolved identifiers are explicitly listed under an 'unresolved' field. It also explains cross-source identity spine behavior and how ISINs resolve via GLEIF. 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 front-loaded with example queries and a clear purpose. It uses a structured format with bullet-like sections for supported types. However, it is verbose and could be slightly more concise by moving some details (e.g., the full explanation of ISIN resolution) into the parameter descriptions. Every sentence adds value, but the density may be overwhelming. Still, it earns its length for the complexity of the 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?

Despite having no output schema, the description provides thorough information about return values: for 'company' it lists CIK, ticker, LEI, FIGI with source labels, and mentions an 'unresolved' field; for 'drug' it lists RxCUI, ingredient, brand, and citation. It covers edge cases like graceful degradation and explicit unresolved identifiers. Given the tool's complexity (cascading lookups, multiple identifier types), the description is complete enough for an agent to understand what to expect without needing an output schema.

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

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

Schema coverage is 100% (both parameters described), but the description adds substantial meaning beyond the schema's brief descriptions. For the 'value' parameter, it provides concrete examples (AAPL, 0000320193, 'ozempic') and explains how different input formats (ticker, CIK, ISIN, name) are resolved. For the 'type' parameter, it details what each type returns and the data sources. This makes the parameters much more meaningful for the agent.

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: resolving user-spoken names to canonical/official identifiers. It lists specific example queries ('What's the ticker for...', 'find the CIK for...'), describes supported types ('company', 'drug'), and specifies what each returns (CIK, ticker, LEI, FIGI for company; RxCUI for drug). This distinguishes it from sibling tools like compare_entities or entity_profile which have different purposes. The verb 'resolve' plus 'name to identifiers' is specific and unambiguous.

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

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

The description provides explicit usage guidance: 'Use FIRST whenever you have a name but need an ID.' This is a clear directive for the agent to prioritize this tool before using other tools that require identifiers. It also explains that each call replaces 2-3 manual lookups, justifying its use. While it does not explicitly mention when not to use it, the narrow scope and the 'first' directive make the usage context very clear.

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

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

The description discloses the tool's behavior: it probes each entity, ranks by score, and surfaces most/least recognized. It also describes the return format (ranked list with score, confidence, signal density). Annotations already cover safety (readOnly, idempotent, non-destructive), so the description adds value by explaining the comparison process and output, going beyond the annotations.

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

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

The description is three sentences, with the primary purpose front-loaded ('Compare AI visibility across multiple entities side-by-side'). Each sentence earns its place: purpose, mechanism+output, and a concrete use case. No wasted words or redundancy.

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

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

For a tool with no output schema, the description adequately describes the return value (ranked list with score, confidence, signal density), the process (probing each entity with ai_visibility_check), and common usage. It covers the main context needed. Minor gaps include handling of edge cases (e.g., invalid entity counts, missing API key), but these are not essential for selection.

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

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

The input schema has 100% coverage for all four parameters, including descriptions for entities (first entry as subject), models, _apiKey, and context. The description adds minimal parameter-level detail beyond the schema, such as 'your brand + N competitors' and 'Claude' as an example, but the schema already does the heavy lifting. 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 identifies the tool's function: comparing AI visibility across multiple entities side-by-side, with a specific verb ('compare'), resource (AI visibility across entities), and scope (multiple entities). It distinguishes itself from the sibling ai_visibility_check by explicitly mentioning side-by-side comparison and from generic compare_entities by focusing on AI visibility and the ai_visibility_check probing mechanism.

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: competitive AI-marketing audits and an example query. It implies when to use this over ai_visibility_check (for multi-entity comparison) and mentions it probes each entity with ai_visibility_check, but does not explicitly name alternatives or state 'use ai_visibility_check for a single entity.' This is strong implied guidance, but not 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?

Adds substantial behavioral context beyond annotations: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed will list timeouts. This complements the readOnly/idempotent annotations without contradiction.

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

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

The description is dense but front-loaded: purpose first, then usage, return fields, limitations, and failure behavior. Every sentence earns its place, making the length justified for a composite 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?

Since there is no output schema, the description enumerates the summary block fields, per-advisory details, links, and alternative versions. It also covers limitations (NPM only) and partial failure behavior, making it self-sufficient for an agent author.

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

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

The input schema already documents both parameters ('package' and 'version') at 100% coverage, so the description's examples ('lodash') add minimal new semantic value. Baseline 3 is appropriate when schema handles parameter documentation.

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

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

The description opens with a specific composite check ('should I add this npm package to my project') and names both data sources (deps.dev and bundlephobia), making it highly specific and self-explanatory. It clearly distinguishes from sibling tools like scan_competitor_ai_presence.

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

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

Explicitly states when to use ('Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"') and provides exclusions/alternatives ('NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly').

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 destructiveHint=false, so the safety profile is covered. The description adds behavioral context by listing the exact return fields and the key capability of returning land borders by name, which is useful beyond the schema.

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

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

The description is two sentences with front-loaded purpose and a clear list of returned data. Every clause adds value, and there is no redundancy or padding.

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

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

Given the low complexity (one parameter), existing output schema, and annotations, the description fully covers what the tool does, what it returns, and a concrete use case. No critical gaps remain.

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

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

The schema already provides 100% coverage for the single 'query' parameter, including partial-match support. The description does not add new parameter-level meaning beyond restating 'by name,' so a baseline score of 3 is appropriate.

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

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

The description opens with a specific verb+resource: 'Search for countries by name,' and enumerates the exact fields returned, including official name, capital, population, and borders. This clearly distinguishes it from sibling tools like get_country_by_code or countries_by_region, and the border detail adds a unique differentiator.

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 through the explicit example of answering 'which countries border Bolivia,' which signals a search-by-name scenario. However, it does not explicitly name alternative tools or state when not to use it, 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 declare readOnly/OpenWorld/idempotent, but the description goes further by disclosing technical details: embeddings model (BGE-base-en), cosine similarity, 500-char overlapping windows, and the 200K char cap with truncation flagging. It also describes output format (passages with offsets and similarity scores), adding significant context beyond the annotations.

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

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

Despite being information-dense, every sentence earns its place. The structure front-loads the core purpose, then gives usage guidance, a pairing alternative, and finally technical details—all in under 100 words. No redundancy exists, and it remains highly scannable.

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

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

For a tool without an output schema, the description covers return values (passages, offsets, scores), operational constraints (cap, truncation), and integration with a sibling tool. It gives enough context for an agent to select and invoke it appropriately, including examples of queries.

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

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

Schema covers all params descriptively, so baseline is 3. The description adds nuance by framing 'text' as 'what you already pulled' and clarifying the natural-language query purpose. It also reveals that inputs longer than 200K are truncated and flagged, which is not in the schema and enriches understanding of the text parameter's behavior.

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 'Semantic search INSIDE a fetched record', clearly stating the tool's function as searching within a provided text. It distinctively differentiates from siblings by explaining it consumes already-retrieved text (e.g., SEC filings) and returns relevant passages, unlike ask_pipeworx_grounded which operates over the whole document.

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

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

Explicitly states when to use: 'Use when the record is too big to cram into the prompt'. It also names the sibling tool ask_pipeworx_grounded as an alternative, suggesting a workflow of fetching with the gateway and then grounding over passages, providing clear comparative 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 annotations (readOnly=false, openWorld=true, idempotent=true, destructive=false), the description discloses significant behavioral details: OAuth requirement prevents anonymous/BYO, authentication is needed to persist subscriptions, SMS delivery requires verified phone and has a daily cap, and the feed is always active. It also mentions the return value (subscription ID), which is beneficial given no output schema.

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

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

The description is a single dense paragraph that front-loads the core purpose and then details types and delivery channels. It is efficient but somewhat long and could be restructured into bullet points for readability. Every sentence adds value, though the type list is redundant with the schema's enum.

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?

While the schema is rich, the description is not fully complete. It lists only three of the five supported types, omitting patent_grant and clinical_trial, which could mislead the agent into thinking those types are unsupported. It also fails to mention the webhook delivery channel, which is only in the schema. However, the schema covers these gaps, and the description does cover auth, return value, and delivery feed constraints.

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 input schema's params property is very detailed with examples for all types). The description adds extra semantics beyond the schema, such as explaining that items:['5.02'] means an officer change, implying the item codes map to event types. It also adds the OAuth requirement and the 'return subscription ID' information, which are not in the schema.

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

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

The description clearly identifies the tool's purpose: 'Create a proactive monitoring subscription to a live-data event stream.' It uses a specific verb and resource, lists supported event types, and distinguishes itself from sibling tools like list_subscriptions and unsubscribe by specifying it creates a subscription and returns its ID.

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

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

The description provides concrete usage context: requires a Pipeworx OAuth account, explains the always-on feed channel and how to pull alerts via recent_alerts or a GET endpoint, and notes constraints (SMS verification, 10/day cap). It doesn't explicitly say when not to use this tool or name alternatives, but the context is clear.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds meaning beyond annotations by disclosing the output structure (category-bucketed example questions with tool+argument shapes drawn from the live catalog) and the no-argument vs. topic-focused behavioral difference. That goes beyond what annotations provide, though it could mention response size or pagination.

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

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

The description is a single dense paragraph, but every sentence carries useful content: intent mapping, output description, usage guidance, and parameter behavior. It is front-loaded with the user intents and purpose, but the initial run-on list of example queries makes it slightly verbose. Overall, it is well-structured and economical for the amount of information it conveys.

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 explain what the tool returns, and it does: 'Returns category-bucketed example questions... each with the exact tool + argument shape that answers it.' It also covers when to use, how to use (with/without topic), and the connection to meta-tools. For a simple one-parameter read-only tool, this description is thorough and complete.

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

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

Schema coverage is 100%, so the schema already documents the 'topic' parameter. The description adds value by explaining the behavior when omitted ('full spread') and providing concrete examples ('finance', 'pharma', 'betting'), reinforcing the schema's description. Given the baseline of 3 for full coverage, the extra usage context justifies a 4.

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

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

The description clearly identifies the tool as the onboarding entry point for learning what Pipeworx can do, with a specific verb ('returns category-bucketed example questions') and resource (Pipeworx capabilities). It distinguishes itself from siblings by positioning as 'FIRST' when you don't know what to ask, and by referencing the exact tool+argument shape for each example, which is unique among the sibling tools.

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

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

The description provides explicit when-to-use guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also explains parameter usage (omit for full spread, pass topic to focus) and names meta-tools it helps you learn. However, it does not explicitly state when NOT to use this tool in favor of alternatives like discover_tools, so it stops short of a full 5.

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

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

The description adds meaningful behavioral context beyond the annotations: ownership enforcement, row deactivation rather than deletion, and that historical events remain available via recent_alerts. This provides important side-effect information that the annotations (readOnlyHint, destructiveHint, idempotentHint) do not fully convey.

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

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

Two concise sentences that front-load the action ('Cancel a subscription by id') and then add relevant constraints and consequences. No fluff, every sentence earns its place.

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

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

For a simple one-parameter tool with no output schema, the description covers the action, ownership constraint, behavioral effect, and relationship to recent_alerts. It could mention what happens on invalid id or already-canceled subscription, but the idempotentHint annotation partially covers that. Overall, quite 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 id is fully described in the schema (uuid returned by subscribe). The description merely says 'by id,' adding no format or source detail beyond the schema. Since schema coverage is 100%, 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 opens with 'Cancel a subscription by id,' a specific verb+resource that clearly distinguishes this from sibling tools like subscribe and list_subscriptions. The additional detail about deactivating rather than deleting further clarifies the operation.

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

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

The description gives useful context: ownership is enforced and the effect is deactivation, not deletion. It implies this is the tool to stop receiving alerts for a subscription, but does not explicitly state alternative tools or when not to use it. Still, the context is clear enough for an 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, openWorldHint, idempotentHint, and destructiveHint=false, but the description adds significant behavioral detail: it explains the meaning of 'could_not_verify' as a verification failure (with verification_error{stage,detail}) that must not be treated as evidence, and distinguishes 'unsupported' as a coverage gap. It also clarifies the return structure (verdict, actual value, citation, reasoning). This goes well beyond the annotations.

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

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

The description is longer than average but every section earns its place: usage triggers, routing rules, return types, and semantic clarifications. The opening examples ('Is it true that…' / 'fact check') front-load the tool's trigger phrases. It could be tightened slightly, but it is well-organized and not wasteful.

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

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

Given there is no output schema, the description thoroughly covers return values (verdict categories, actual value with citation, reasoning) and edge-case semantics (could_not_verify vs. unsupported). It also explains the internal pipeline enough for the agent to understand behavior without needing additional context. 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?

Schema coverage is 100% and the schema already describes both parameters. The description adds value by giving a concrete example of a claim, explaining how tolerance_pct overrides wording-derived tolerance (with a specific use case: 1–2 for hallucination detection), and clarifying the default ('implied by wording, capped at 5'). This enriches the schema without redundancy.

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: natural-language claim verification against authoritative sources, with a specific verb ('validate', 'verify') and resource ('claims'). It distinguishes itself from siblings by explicitly describing its scope (factual claim checking) and noting it replaces 4–6 sequential calls, which sets it apart from general research or search 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 provides clear when-to-use guidance: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also delineates two distinct routing paths (SEC EDGAR/XBRL for company-financial claims vs. grounded pipeline for all others), giving the agent nuanced context. It doesn't explicitly name alternative tools or state when NOT to use it, but the guidance is strong enough to warrant a 4.

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