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 declare readOnly/openWorld/idempotent, so the description does not need to re-cover safety. It adds valuable behavioral context: the tool fills arguments automatically, returns citations, routes across many sources, and has a latency tradeoff vs direct web search. This goes beyond the structured annotations and helps an agent anticipate behavior and outputs.

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 well front-loaded with the most critical routing instruction ('PREFER OVER WEB SEARCH') and uses examples plus sibling-tool guidance efficiently. Some redundancy exists between the authoritative-data list and the general factual-question guidance, but every major section 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 complex routing tool with no output schema, the description explains what happens internally, what the answer will look like, when to use it, when not to use it, and which alternatives fit which situations. The examples cover multiple domains and the aliasing is covered by the schema. Nothing essential for correct selection or invocation is missing.

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

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

Schema coverage is 100%: all six parameters are documented as the question or alias for the question. The description provides examples and says natural language is accepted, but it does not add parameter-specific meaning beyond the schema. With full schema coverage, 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 names a specific verb ('routes the question'), a concrete resource (5,798 tools across 1,517 verified sources), and the output (structured answer with stable pipeworx:// citation URIs). It clearly positions the tool as a router for factual/current/historical questions and distinguishes it from web search and 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 explicitly says 'PREFER OVER WEB SEARCH' for a long list of domains and gives concrete trigger phrases ('what is', 'look up', 'get the latest'). It also provides explicit alternative routing: ask_pipeworx_grounded for multi-hop grounded questions, deep_research for large jobs, ask_pipeworx_beta for beta features, and web-search packs for minimal latency or direct sources.

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, so the safety profile is covered. The description goes beyond that by disclosing live testing behavior, current candidate status, exact equivalence to the stable router right now, and the absence of a fallback while still being a full router. This is precisely the kind of behavioral context a beta tool needs.

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: the first sentence captures beta status, scope, and experimental nature. The remaining sentences add current-state, usage, and fallback context without repeating schema or annotation content. It is longer than a minimal description, but every clause earns its place for a beta-flagged 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?

Given a simple one-required-string parameter set, rich annotations, and no output schema, the description covers the essential invocation context: what the tool is, how to use it, and that responses match ask_pipeworx's shape. The only minor gap is that it points to ask_pipeworx for the concrete response shape rather than describing it directly, but the sibling reference makes this acceptable.

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

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

The input schema covers all six parameters and explicitly documents every alias for question, so schema coverage is 100%. The description says 'same arguments' as ask_pipeworx but does not add parameter-level detail. Under the baseline rule, 3 is appropriate because the schema already does the heavy lifting and the description does not need to compensate.

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 by identifying this as a beta version of ask_pipeworx and explicitly states it is an identical universal router with the same 5,798 tools, arguments, and response shape. This makes both the resource and the experimental variant clear, and it distinguishes the tool from the stable ask_pipeworx sibling. The router framing plus the sibling reference is unambiguous.

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

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

The description states 'Use it exactly like ask_pipeworx when you want the newest routing,' which is an explicit usage directive. It also explains that results are compared against the stable router to decide merges, and that with no active candidate it currently matches ask_pipeworx exactly. This is sufficient when-to-use guidance and implicitly identifies the stable sibling as the alternative.

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

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

Annotations already establish readOnly/openWorld/idempotent, so the description adds meaningful behavior: it routes through a large tool set, extracts only from tool results, returns refusal reasons such as not_in_source and tool_error, and costs an extra LLM call. 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 dense and front-loaded but slightly over-packs process detail ('picks the right tool from 5,798 across 1517 sources, fills arguments, fetches the data') that could be shortened without losing meaning. Every sentence otherwise 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?

With no output schema, the description appropriately documents the success return object and refusal reasons, plus cost and use guidance. It leaves the meaning of 'confidence' and 'source' fields unspecified, a minor gap for a high-stakes 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% and the schema documents the 'question' parameter and all aliases, so the description does not need to add much. The description only implicitly assumes a natural-language question, remaining at the baseline for high schema coverage without adding parameter-level details.

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

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

The description opens by naming the mode ('hallucination-resistant answer mode') and contrasts it with sibling ask_pipeworx ('Same routing as ask_pipeworx'), making the specific grounded behavior and return shape explicit. It clearly identifies the tool as answer extraction from fetched data rather than a general search tool.

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

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

Gives explicit use conditions ('whenever an answer will be quoted, cited, or acted on... must not invent facts') and an explicit alternative with a cost-based preference ('prefer ask_pipeworx for casual lookups'). This is routing guidance, not just a restatement.

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 mark it readOnly, open-world, idempotent, and non-destructive, and the description adds substantial context: account and paid-tier requirements, parallel routing to thousands of tools, transparent gap reporting with no invented answers, contradictions scan, citation resolvability, semantic excerpting, and expected latency. There is no contradiction with the annotations.

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

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

The description is long and dense, but the complexity of the tool justifies most of the detail. It is front-loaded with the account constraint and alternative routing, followed by the core purpose and then behavioral nuances. It is somewhat rambling and could be tightened, but no sentence is 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?

There is no output schema, so the description correctly carries the full burden of explaining return values: findings packet contents, gaps, contradictions, hop field, citation URIs, and fetchability. It also covers auth, tier behavior, latency, and alternative tools, so an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, and the description goes beyond the schema by explaining what each depth level actually does: quick is single-hop, standard adds gap recovery and contradictions, thorough adds an iterative chase and requires payment. It also provides example questions that clarify what the question parameter is for.

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

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

The description names a specific verb and resource: grounded multi-source research over Pipeworx structured data sources in one call, with decomposition and parallel routing. It explicitly distinguishes itself from open-web search and from ask_pipeworx for single lookups. This gives an agent a clear basis for selecting it over the many 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?

It gives concrete when-to-use guidance: best for broad or multi-part questions over structured data, with examples. It also states when-not-to-use: if not signed in, use ask_pipeworx instead, and for a single lookup use ask_pipeworx. This is explicit alternative routing.

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

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

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?

Annotations already mark the tool as read-only, open-world, and idempotent, and the description adds substantial behavioral context: it fans out across multiple sources, returns sources_used/sources_failed, treats an empty section as real 'no data', soft-fails the USPTO patent source, and explains the FDA products section can be empty for non-biologics companies. This gives an agent clear expectations about partial results and fallbacks.

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; it front-loads the most important usage instruction and then packs the return shape, fallback behavior, and accepted input shapes into a compact set of clauses. A cleaner list structure might improve scanability, but nearly every sentence carries unique decision-relevant 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?

With no output schema, the description carries full responsibility for explaining what the tool returns, and it does: it enumerates all main response sections (CIK, recent filings, fundamentals, patents, federal contracts, FDA products, H-1B, news, LEI), explains sources_used/sources_failed semantics, and covers empty-result expectations and the resolved:false private-company case. Nothing an agent needs to invoke or interpret this tool correctly is missing.

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

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

The schema already documents both parameters at 100% coverage, and the description adds extra meaning: it gives concrete examples for type and value, clarifies that 'company' and 'ticker' are interchangeable, and describes name resolution through SEC EDGAR plus the private-company resolved:false outcome. This goes well beyond the schema's raw enum and string 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 names a specific verb and resource: it says it produces a 'full cross-source profile of a US public company' in one parallel call, and gives concrete invocation phrasings. It also distinguishes this from single-pack SEC/XBRL/news lookups by explicitly saying to prefer it for holistic-view requests.

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 this tool: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also clarifies edge-case usage behavior for private companies (returns resolved:false with an explicit notes line) and how to pass names, tickers, and CIKs.

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?

Annotations already establish readOnly/idempotent, and the description goes well beyond them: it discloses that fees are not modeled and spreads are gross, that compatibility warnings can be non-empty even with matched_pairs>0, that 'unknown' legs are never paired, and that temporal_alignment:null means 'could not be computed,' not aligned. This kind of semantic clarification materially changes how an agent interprets results. 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 long and dense, but nearly every sentence carries distinct information that affects behavior or interpretation (fees, compatibility codes, skipped legs, temporal semantics). It is front-loaded with purpose and modes before the detailed safety fields. It loses a point for being a single wall of text with no list/heading structure.

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 the response shape and safety signals itself, and it does: response fields, top_spreads_pp flags, compatibility_codes, skipped_unclassified, low_confidence_pairs, fees_note, and temporal_alignment. It also gives operational caveats about pre-mapped topics not being tradeable. For a tool this complex, nothing essential seems missing.

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

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

Schema already documents all three params with 100% coverage, listing the topic enum and examples for fed/btc. Description adds the key relationship that explicit ticker/slug overrides the topic-mapped side, and that both modes run the same matching logic. With full schema coverage, baseline is 3, and the override semantics justify 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 opening sentence names the verb and resource: it computes the cross-venue spread between Kalshi and Polymarket for the same resolving question, and the body defines two operating modes. It is specific about what it measures (raw probability spreads, gross of fees) and why the spread exists. It does not explicitly differentiate from sibling tools like polymarket_arbitrage or polymarket_edges, so not a 5.

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

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

The description explicitly says when each mode is appropriate: use topic shortcuts for 10 pre-mapped macros, or explicit kalshi_event_ticker + polymarket_event_slug for custom pairings, and both run the same matcher. It also warns that most pre-mapped topics return compatibility_warning today and that pre-mapped ≠ tradeable, which is actionable when deciding whether to trust a call. It doesn't address when to choose this over sibling spread/edge tools, so a 4.

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?

Even though annotations already indicate readOnly, idempotent, and non-destructive behavior, the description adds substantial operational detail: internal cascading through multiple lookup endpoints, graceful degradation when GLEIF/OpenFIGI is unavailable, explicit `unresolved` reporting, `figi_candidates` on ambiguous matches, source labelling for identifiers, and non-equity coverage via FIGI. This gives the agent realistic expectations beyond any structured fields.

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: it opens with example user phrasings, then directly states the rule 'Use FIRST whenever you have a name but need an ID', and groups the remaining detail under SUPPORTED TYPES. The caveats are dense and relevant, though the length and interleaving of many identifier-source details keep it from being maximally concise.

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

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

Given the tool has no output schema, the description does an excellent job covering what an agent needs to know: what identifiers are returned, how ambiguity is handled, how unresolved identifiers are represented, the acceptable input patterns, and how degradation behaves. The company and drug branches are both fully described, and edge cases like ISIN-to-LEI map and non-ticker instruments are covered.

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

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

Schema description coverage is 100%, but the description significantly enriches parameter meaning. For `value`, it specifies 'entity name only', exact issuer formatting, and warns against trailing security-class words like 'revenue bonds'. For `type`, it expands the enum into concrete identifier behaviors per type (CIK/ticker/LEI/FIGI for company vs RxCUI/brand/ingredient for drug). This far exceeds the baseline schema-only understanding.

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

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

The description clearly states the tool's purpose: resolving a user-spoken NAME into canonical/official identifiers that other tools require. It names concrete verbs and use cases ('What's the ticker for...', 'resolve a user-spoken NAME') and differentiates itself from siblings by asserting 'Use FIRST whenever you have a name but need an ID.' Supported entity types and identifier systems are explicitly enumerated.

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 strong usage context: 'Use FIRST whenever you have a name but need an ID' and notes it replaces 2-3 manual lookups. It clearly explains what inputs are accepted and gives detailed formatting constraints for the value parameter. However, it does not name sibling tools as explicit alternatives or state when not to use this tool over them, so it falls just short of full exclusion guidance.

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

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

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.