worlduank

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

Annotations already declare readOnly/openWorld/idempotent, and the description adds valuable context: the default free model, the BYO-key cost implication for Anthropic calls, and the exact return shape ({score, confidence, signals, raw_response} + combined view). It does not contradict the annotations and provides more behavioral detail than typical.

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 purpose, followed by operational details and use cases. Every sentence earns its place with no redundancy or filler.

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

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

With no output schema, the description compensates by specifying the return structure per model and the combined view. It covers use cases and key operational details. It lacks some edge-case behavior (e.g., error handling, rate limits), but for a well-scoped tool with 4 params, it is reasonably complete.

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

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

The input schema already provides 100% coverage with thorough parameter descriptions (entity, models, _apiKey, context). The description reiterates the _apiKey purpose and default model but does not add new meaning beyond the schema. Baseline 3 is appropriate since the schema carries the heavy lifting.

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

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

The description clearly states the tool's function: probing LLMs for knowledge about a business/brand/product/topic and scoring visibility on a 0-100 scale. This specific verb+resource+output combination distinguishes it from sibling tools like compare_entities or entity_profile, which have different focuses.

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 example use cases: AI-marketing audits, pre-launch brand checks, and competitive monitoring. It also explains the default model option and how to opt into Anthropic, but does not explicitly state when not to use the tool or name alternative 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, so the safety profile is covered. The description adds valuable behavioral context: it routes to 5,439 tools, fills arguments, returns pipeworx:// citation URIs, works on every tier, and is 'one fast call'. This goes beyond the annotations and helps set expectations about the tool's orchestration 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?

Although lengthy, the description is tightly organized and front-loaded: it opens with the most critical guidance ('PREFER OVER WEB SEARCH'), then explains mechanism, usage triggers, examples, and escalation paths. Every sentence adds actionable information; no filler or repetition.

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

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

The description covers purpose, usage, alternatives, examples, output format (citation URIs), and operating characteristics (every tier, fast). No output schema exists, but the description conveys enough about return behavior. It is exceptionally complete for a complex meta-tool like this.

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 documents the 'question' parameter with aliases (q, text, input, query, prompt). The tool description does not add parameter-level detail beyond the schema, but it does include rich examples of valid questions. This meets the baseline for high schema coverage.

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

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

The description clearly states the tool's function: routing factual questions to a large pool of tools and returning structured answers with citation URIs. It uses specific verbs like 'fills arguments' and 'returns the structured answer', and explicitly distinguishes itself from siblings like ask_pipeworx_grounded and deep_research.

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

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

The description provides explicit guidance: 'PREFER OVER WEB SEARCH', 'Use whenever the user asks...', 'START HERE for most questions', and 'Step up only when needed' with named alternatives (ask_pipeworx_grounded, deep_research). It also explains how it handles breaking-news, covering both when to use and when not to use.

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 behavioral traits beyond annotations: it is an experimental beta with live candidate routing improvements, currently identical to ask_pipeworx, with no fallback. It also notes that candidates are retired based on outcome evidence, providing useful contextual history without contradicting the readOnly/idempotent hints.

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

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

The description is dense but efficient, front-loading the core purpose (beta universal router) and then providing essential context (current state, usage, comparison process). Every sentence contributes value with no redundant phrasing.

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 beta tool with dynamic behavior, the description covers the experimental nature, current status, fallback behavior, and relationship to the stable router. It also references the same response shape and arguments, making it complete even without an output schema.

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

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

Schema description coverage is 100%, so the schema already fully documents the question parameter and its aliases. The description adds 'same arguments' but no new semantics beyond the schema, making the baseline 3 appropriate.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx, a universal router with 5,439 tools, and explicitly distinguishes it from the stable ask_pipeworx by highlighting its experimental edge. The verb+resource+scope is specific and unambiguous.

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

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

It provides explicit usage direction: 'Use it exactly like ask_pipeworx when you want the newest routing,' and contrasts it with the stable router. It also states the current state (no active candidate) and that results are compared to decide merges, giving clear when-to-use 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?

Discloses rich behavioral details beyond annotations: the extraction is limited to the tool's returned content, returns structured evidence with verbatim quotes and refusal reasons, and costs one extra LLM call. All disclosed behaviors align with the readOnlyHint, openWorldHint, and idempotentHint annotations, with 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 dense yet efficient: three sentences cover purpose, return/refusal behavior, and usage guidance. It is front-loaded with the core proposition ('Hallucination-resistant answer mode') and every sentence contributes distinct 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?

Despite having no output schema, the description fully defines the success and refusal payloads, including specific refusal reason enumerations. It also clarifies complexity (routing across thousands of tools) and tradeoffs versus sibling tools, making the tool self-contained for an 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?

All six parameters are aliases for the single 'question' field, and the schema provides 100% coverage with clear descriptions. The description adds no parameter-level information, but the schema fully carries the burden, so the baseline score of 3 is appropriate.

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

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

The description specifies a distinct mode ('Grounded', hallucination-resistant) for high-stakes reads, with a clear verb ('ask') and resource ('Pipeworx'). It explicitly distinguishes from the sibling ask_pipeworx by describing the extraction and refusal behavior, 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?

Provides explicit guidance: use when answers will be quoted/cited/acted on and when facts must not be invented, and prefer ask_pipeworx for casual lookups. This gives clear when-to-use and when-not-to-use instructions relative to 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?

Beyond the readOnly/idempotent annotations, the description reveals substantial behavioral details: parallel fan-out to category-specific data packs, response shape contracts (result.market, result.analysis, result.evidence), blocking behavior on low-confidence matches and closed markets, and safety guards like illiquid-wide-spread flags. It also warns about resolution-rule risk and fallback handling for news sources—none of which is captured by 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 highly structured with section headers (RESOLVER CONTRACT, PARENT_EVENT EXTRACTOR, SAFETY, etc.) and every sentence adds operational detail. The initial summary is front-loaded, followed by necessary caveats and examples, with no filler.

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

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

Given the absence of an output schema, the description thoroughly documents result shape, status codes, edge cases, and resolution-rule risk—even quantifying EV impact of flat-50¢ voids. It also explains fallback behaviors and when responses are summarized vs raw, making it complete for an agent to use correctly.

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

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

The input schema already covers all 3 parameters with descriptions (coverage 100%), so the baseline is 3. The description adds value by enumerating accepted market identifiers (slug, URL, question text) with concrete examples, and by explaining when `include_raw` should be true ('recompute deltas, cite specific observations, or post-process').

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

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

The description opens with a clear action—'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call'—and goes on to specify the input types and use cases ('should I bet on X', 'what does the data say about Y'). This distinguishes it from sibling tools like `polymarket_edges` or `polymarket_arbitrage`, which are more specialized.

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 lists trigger phrases ('Use for "should I bet on X"...') and gives multiple example mappings from bet type to data sources. While it does not name alternative tools for exclusion, the context is sufficient to know when to invoke 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 already convey safety (readOnly, idempotent, non-destructive, openWorld), so the description adds value by disclosing behavioral traits not obvious from annotations: results are 'returned ranked high→low', it 'Defaults to each country's most-recent available value', and a year can be passed for a specific year. It also points to an alternative tool for CO2 rankings, adding nuance. While it doesn't describe output format, it provides meaningful behavioral 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?

The description is compact yet information-dense, front-loading the purpose in the first sentence. Every subsequent sentence earns its place: examples, parameter guidance, indicator list, and sibling-tool disambiguation. No filler or redundancy, and the structure flows logically from purpose to usage to parameters.

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

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

For a moderately complex tool with no output schema, the description is quite complete: it covers purpose, usage scenarios, parameter constraints, default behavior, and common indicators. The only minor gap is the lack of explicit return format details, but given the simple, ranked-list nature of the output, the description is sufficient for correct invocation.

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

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

Schema coverage is 100% with descriptions for all three parameters, so the baseline is 3. The description enriches this by listing common indicator codes with labels (NY.GDP.PCAP.CD for GDP per capita, SP.POP.TOTL for population, etc.), helping the agent select valid inputs. It also clarifies the year parameter's optionality and default behavior, adding meaning beyond the schema's basic description.

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

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

The description clearly states the tool's purpose: 'Compare a World Bank indicator across MULTIPLE countries in one call, returned ranked high→low.' This specifies the verb (compare), resource (World Bank indicator), and unique behavior (ranking), distinguishing it from siblings like get_gdp or get_population. Examples further clarify typical 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?

The description explicitly says 'PREFER for' with concrete query examples, and provides an exclusion: 'For CO2 rankings prefer country_co2_emissions, which knows the right series.' It also instructs to 'Pass 2+ ISO country codes' and explains the year default behavior, giving clear when-to-use and when-not-to-use 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 read-only and idempotent annotations, the description adds substantial behavioral detail: it sources data from SEC EDGAR/XBRL for companies and FAERS for drugs, handles off-calendar fiscal years correctly, sorts results by primary metric, and returns paired data with citation URIs. This fully discloses the tool's 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 and front-loaded with trigger phrases and core purpose, followed by data-source details. It is slightly long (~120 words) but every sentence conveys essential information. No fluff, but it could be tightened by removing redundant query examples.

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 the burden of explaining returns; it does so clearly ('paired data + pipeworx:// citation URIs per entity'). It also covers data sources, sorting, and parallel execution, making it fully complete for an agent to use this tool effectively.

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?

While the schema already describes both parameters, the description adds critical semantics: type='company' pulls latest 10-K data, type='drug' pulls FAERS/FDA/trial counts; values are tickers/CIKs for companies and names for drugs, with concrete examples. This goes well beyond the schema's generic 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 uses specific verbs and resources, listing trigger phrases ('Compare X and Y', 'X vs Y', 'which is bigger') and clearly states the tool performs side-by-side comparison of 2–5 companies or drugs. It distinguishes itself from siblings like compare_countries and entity_profile by explicitly focusing on companies/drugs and preferring over sequential 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 gives an explicit preference: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It also implies when to use alternative tools (single-entity lookups) and enumerates the exact query types (compare, rank, head-to-head) that trigger this tool. This is strong usage guidance.

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

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

Annotations already declare readOnly, idempotent, openWorld, non-destructive. Description adds data source (World Bank, AR5 basis, excluding LULUCF) and annual frequency, which are helpful beyond annotations. No contradictions.

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?

Highly efficient: three sentences cover purpose, usage patterns, and sibling differentiation. Front-loaded with core function. 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?

Tool is simple with 3 params and no output schema. Description covers how to invoke and differentiate, but does not explain return format (e.g., columns, units). Still, minimal gaps given the tool's straightforward nature.

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 good descriptions. The description adds value beyond schema: clarifies ranking vs. time series, reinforces per_capita meaning, and provides usage examples. Not redundant.

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?

Specific verb and resource ('National CO2 emissions for ANY country worldwide') immediately identifies purpose. Distinguishes from sibling tools by noting other emissions tools are US-only or grid-intensity. No ambiguity.

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

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

Explicitly states when to prefer this tool with example queries. Provides clear usage patterns: pass one country for time series, several for ranking. Notes exclusion of other tools, giving full 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 extensively discloses behavior beyond annotations: account/paywall requirements, parallelism, gap[] handling ('never invented'), hop fields, contradictions[], semantic excerpting, and latency expectations. These details align with annotations (readOnly, openWorld, idempotent, non-destructive) 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 long but information-dense; each clause adds operational context (pricing, alternatives, depth behavior, output format, latency). It is front-loaded with the account requirement and the 'not open-web search' distinction. Slightly more verbose than necessary but justified by tool 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?

Despite no output schema, the description fully explains the return packet: verbatim evidence, confidence, source, fetched_at, citation_uri, gaps[], contradictions[], and hop. It also covers failure modes, latency, and when results will be empty, making the tool predictable in varied scenarios.

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

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

Schema coverage is 100%, so parameters are already documented. The description adds valuable semantics for the 'depth' parameter—'quick=3', 'standard=5', 'thorough=8' with gap-recovery and contradiction scans—and clarifies that 'question' accepts broad/multi-part natural language. This enriches the schema rather than merely repeating it.

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

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

The description clearly states this tool performs 'grounded multi-source research across Pipeworx's 1412 STRUCTURED data sources' in 'ONE call', explicitly clarifying it is 'NOT open-web search'. It contrasts with siblings like ask_pipeworx and compare_entities, making the tool's purpose and scope 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?

Provides explicit when-to-use guidance: best for 'broad/multi-part questions over structured data', while 'for a single lookup use ask_pipeworx' and for breaking/current news 'prefer ask_pipeworx'. It also accounts for sign-in status, directing unsigned users to ask_pipeworx, and describes depth-level trade-offs.

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 cover read-only, idempotent, non-destructive safety. The description adds substantial behavioral detail: return contents (names, descriptions, full schemas with examples), direct callability without a second lookup, and the top-N result format. This goes well 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 and front-loaded: purpose first, then usage context, then return detail. The domain list is long but serves as a concrete example set that helps the agent understand scope. Every sentence adds value.

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

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

Despite having no output schema, the description fully explains the return value (top-N tools with schemas, ready to call), when to invoke it (first, many tools available), and what queries look like. It is complete for a meta-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 coverage is 100% and the schema already documents the query parameter, aliases, and limit. The description's mention of 'describing the data or task' and 'top-N' adds modest context, but it does not meaningfully enhance parameter understanding 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 'Find tools by describing the data or task' and expands with verbs like browse, search, look up, and discover. This clearly identifies a meta-tool that locates other tools, distinguishing it from the many domain-specific 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 'Use when you need to browse, search, look up, or discover what tools exist' and instructs to 'Call this FIRST when you have many tools available and want to see the option set.' It gives clear when-to-use context, though it doesn't explicitly mention when not to use it or name 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 readOnlyHint, idempotentHint, openWorldHint, and non-destructive behavior. The description adds substantial behavioral context beyond those: it fans out across multiple sources, returns up to 5 filings with specific URIs, soft-fails for the USPTO PatentsView API sunset, uses GDELT→GNews fallback, and notes that only tickers or zero-padded CIKs are accepted. No contradictions found.

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

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

The description is long but densely informative, front-loaded with example queries and the core purpose. Every clause adds value—source list, fallback behavior, return fields, and input restrictions—so it is not bloated. Could be slightly restructured for easier scanning, but it remains efficiently packed.

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 thoroughly by itemizing the return structure (cik, recent_filings, fundamentals, patents, news, LEI), including field-level details like "LATEST 10-K Revenues + NetIncomeLoss + Cash, sorted period_end DESC". It also covers API sunset behavior, fallback chains, and input limitations, making the tool well-specified for 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%, so baseline is 3. The description repeats the schema's parameter meanings (ticker or zero-padded CIK, only "company" type, names not supported) but does not add semantically new information beyond the schema's own descriptions. It reinforces with examples but does not go further.

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 produces a full cross-source profile of a US public company in one parallel call, with a specific verb+resource pairing. It also distinguishes from siblings by explicitly preferring this tool over chaining single-pack SEC/XBRL/news lookups and by directing name-only inputs to resolve_entity.

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

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

Provides explicit when-to-use indicators (e.g., "Tell me about X", "research Acme", "brief me on Tesla") and an explicit preference rule: "ALWAYS PREFER over chaining single-pack ... lookups". It also gives a clear when-not-to-use: names are not supported, with a direct alternative to use resolve_entity first.

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 as destructive and idempotent. The description adds context about what is deleted (memory by key) and the privacy rationale (clearing sensitive data), which goes beyond the structured metadata.

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

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

Three concise sentences: the action, the use cases, and related tools. No wasted words, and the purpose is front-loaded.

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

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

For a simple single-param destructive tool with annotations covering safety and idempotency, the description fully covers what it does, when to use it, and how it relates to siblings. No output schema is present, so return-value details are not necessary.

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 description ('Memory key to delete') already explains the parameter. The tool description does not add further parameter-level detail, so the baseline of 3 applies.

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

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

The description states a specific action ('Delete a previously stored memory by key') with a clear resource and mechanism. It distinguishes itself from sibling tools like remember and recall by its destructive nature.

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 explicit use cases ('context is stale, the task is done, or you want to clear sensitive data') and mentions pairing with remember and recall. However, it does not explicitly 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 already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds valuable behavioral context beyond annotations by explaining the network fetch ('Fetches the page'), the extraction of title/description/key links, and the output format ('single text blob ready to drop at site-root/llms.txt'). This gives the agent a clear model of what happens during execution.

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 primary action, followed by process and use cases. Every sentence adds value, with no redundant phrasing or filler. It is concise yet informative.

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

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

For a simple tool with 2 parameters, no output schema, and supportive annotations, the description is complete. It explains what the tool does, how it works, what output to expect, and common use cases. The lack of an output schema is mitigated by the explicit mention of 'single text blob' and 'standard llms.txt markdown format', so the agent knows what to expect.

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

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

Schema description coverage is 100%, with both 'url' and 'max_links' fully described in the input schema. The description does not add parameter-specific details beyond what the schema already provides (e.g., max_links default and max are in the schema). Since the schema does the heavy lifting, a baseline score of 3 is appropriate.

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

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

The description clearly states 'Generate a production-ready llms.txt file for any URL' with a specific verb and resource, and details the process (fetches page, extracts title/description/key links, emits markdown format). Though it doesn't explicitly name sibling alternatives, the purpose is distinct from sibling tools like ai_visibility_check or scan_competitor_ai_presence, which focus on checking visibility rather than generating the llms.txt file itself.

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

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

The description provides clear use cases: 'getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor.' This gives strong context on when to use the tool. However, it does not explicitly state when not to use it or mention alternative tools for other 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, establishing a safe read operation. The description adds the specific data returned but no additional behavioral traits like rate limits or auth requirements.

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

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

Two sentences, no redundancy, immediately states the resource and allowed inputs. Every sentence 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?

The tool is simple (1 param) and has a rich output schema, so the description's detail on returned fields and code format suffices. No gaps for correct invocation.

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

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

The schema's country_code description already fully documents the ISO code format with examples, and the tool description repeats this info, adding no new meaning. With 100% schema coverage, baseline of 3 is appropriate.

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

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

The description uses the verb 'Get' and specifies 'basic information about a country' with explicit fields (full name, region, income level, capital city, coordinates). This clearly distinguishes it from sibling tools like get_gdp or compare_countries that target different metrics or behaviors.

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 says to 'Use ISO 3166-1 alpha-2 or alpha-3 country codes,' providing clear parameter usage. However, it doesn't explicitly contrast with sibling tools or state when not to use it, though the focused field list implies its use case.

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

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

Annotations already establish read-only, open-world, idempotent, non-destructive behavior. The description adds concrete behavioral context: data source (World Bank), units (current USD), default date range (2015–2024), return format (year-by-year array), and the indicator code. This enriches the tool's behavior beyond the safety annotations.

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

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

Two concise sentences, front-loaded with the action and resource. The secondary sentence covers default range, output format, and relationship to a sibling tool without extraneous wording.

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

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

For a single-parameter tool with an output schema, the description is remarkably complete: it specifies data source, units, default period, output structure, and the tool's relationship to get_indicator. No significant behavioral aspect is left unstated.

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

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

The schema provides 100% coverage for the single required parameter, country_code, with a clear ISO code description. The description does not add syntactical detail, but it reinforces that the tool operates per country. Since schema description coverage is high, a baseline of 3 is appropriate.

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

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

Description uses specific verb 'Fetch', names the exact indicator (GDP in current USD, NY.GDP.MKTP.CD), the data source (World Bank), and the default date range. It explicitly distinguishes from the broader get_indicator by labeling itself a shortcut.

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 it is a 'Shortcut for get_indicator', providing a clear alternative and implicit guidance on when to use this tool (for GDP data) versus the general indicator tool. However, it doesn't explicitly list exclusion criteria or contrast with other sibling tools like get_population.

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 annotations (readOnly, openWorld, idempotent), the description discloses behavioral traits: data is annual, old CO2 codes were DELETED by the World Bank, and a live series is provided. This adds valuable context about data freshness and source changes, complementing the annotation coverage.

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

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

The description is long but every sentence earns its place: purpose, usage examples, parameter guidance, CO2 warning, and data freshness are all included. It is front-loaded with the main definition and organized logically, with no wasted words.

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

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

Given the tool's complexity and the availability of an output schema, the description is highly complete. It covers purpose, when to use, parameter selection, known caveats, and data limitations. The mention of annual data granularity and the CO2 exception ensures agents have the full context needed to invoke the tool correctly.

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

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

Schema coverage is 100%, but the description adds significant meaning by listing common indicator codes and their meanings (e.g., GDP=NY.GDP.MKTP.CD, inflation=FP.CPI.TOTL.ZG). This goes beyond the schema's generic 'World Bank indicator code' and helps agents select the correct code.

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: 'Get World Bank time-series data — economic, social, and development statistics — for ANY country worldwide.' It uses a specific verb ('Get') and resource ('World Bank time-series data'), and differentiates from siblings by explicitly naming the country_co2_emissions tool for CO2 and listing example queries.

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: 'PREFER for "unemployment rate in <country>"...' and for CO2 'use the dedicated country_co2_emissions tool.' It also notes that annual data may be less fresh than national statistics office figures, giving clear context for alternative 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 the tool as read-only, open-world, idempotent, and non-destructive. The description adds useful behavioral context such as the default time range and the output array format, which go beyond the annotations. It doesn't mention rate limits or errors, but the annotations cover the main 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 three concise sentences, each with a distinct purpose: core action, return format, and relationship to get_indicator. It is front-loaded with the most important information and contains no unnecessary words.

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

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

For a simple 1-parameter tool, the description fully covers purpose, default behavior, output format, and its relationship to sibling tools. The output schema exists, so return values don't need further explanation, and the description is sufficient for an 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?

The schema covers 100% of parameters with a single 'country_code' parameter fully described. The description doesn't add additional parameter-level semantics beyond what's in the schema, so the baseline of 3 is appropriate given the high schema coverage.

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

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

The description clearly states the tool fetches annual total population (SP.POP.TOTL) from the World Bank, using a specific verb and resource. It also explicitly distinguishes itself from the generic get_indicator tool by noting it's a shortcut, 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 provides clear context by specifying the default date range (2015–2024) and the return format (year-by-year array). The 'Shortcut for get_indicator' line indicates when to use this tool instead of the generic alternative, though it doesn't explicitly state exclusions or alternatives beyond that.

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

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

The description adds return field details and clarifies scope ('caller's active subscriptions'). Annotations already cover readOnly, idempotent, and non-destructive behavior, so the bar is lower; the extra detail is useful but not exhaustive.

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

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

Three sentences, each earning its place: purpose, return fields, and usage guidance. No fluff, efficient and front-loaded.

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

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

For a simple list tool with one optional parameter and rich annotations, the description covers purpose, return values, and use cases. It is complete for an agent to select and 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% and the single parameter include_inactive is fully described in the schema. The description adds no new parameter semantics, but none are needed given the high schema coverage.

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

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

The description clearly states the tool lists the caller's active subscriptions, with a specific verb and resource. It distinguishes itself from siblings like subscribe/unsubscribe by focusing on listing existing subscriptions.

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 to use it: 'review what you're monitoring before adding more or to find an id to cancel.' This gives clear usage context and implies alternatives (subscribe, unsubscribe).

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?

All annotations are false, so the description carries the full burden of behavioral disclosure. It reveals that this is a feedback submission (write action), mentions rate limiting ('Rate-limited to 5 per identifier per day'), clarifies it is 'Free; doesn't count against your tool-call quota,' and explains operational nuances (team reads digests daily, describe in terms of tools). This goes well beyond what annotations provide.

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

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

The description is longer than minimal but every sentence is informative: purpose, usage, exclusions, content guidance, rate limits, and free-tier note. It is front-loaded and logically structured, though slightly dense. It earns a 4 rather than 5 due to its length.

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

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

Given the tool's moderate complexity (nested context object, enum, no output schema), the description covers all necessary aspects: what it does, when to use, what to include, operational constraints, and what happens after submission (digests read daily). It is complete for a feedback 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%, so the baseline is 3. The description reinforces parameter meaning by elaborating on the 'type' values (bug, feature/data_gap, praise) and adds guidance on message content ('Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt'). This adds nuance beyond the schema descriptions, warranting 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 opens with a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It then enumerates concrete use cases (bug, feature/data_gap, praise) and distinguishes from sibling tools by scoping to 'tools served by this Pipeworx connection.' This is specific and unambiguous.

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

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

The description gives explicit when-to-use guidance: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also states exclusions: 'if the tool came from a different MCP server ... file it with that server instead.' This is textbook usage guidance with alternatives.

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

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

The description adds significant behavioral context beyond the annotations: it states the data is 'derived from CF analytics-engine', 'no PII', and 'Cached 5min-1h depending on window'. This provides transparency about data sourcing, privacy, and freshness, which the annotations do not cover. The readOnlyHint and idempotentHint align with the read-only nature described.

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

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

The description is compact and front-loaded: the first sentence states the primary output, followed by a bulleted use-case list, then a concise technical note. Every clause adds value, with no filler or redundancy. The structure makes it easy for an agent to quickly grasp the tool's purpose and applications.

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

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

For a tool with a single optional parameter and no output schema, the description is complete. It specifies what is returned (top tools, top packs, total call volume), the data source ('CF analytics-engine'), the privacy guarantee ('no PII'), and the caching behavior. This is sufficient for an agent to decide when and how to use it without ambiguity.

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

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

The schema already fully describes the 'window' parameter with enum values and explanatory text about shorter vs longer windows. The description repeats this info (mentioning '24h, 7d, or 30d') but adds no new parameter-specific details. With 100% schema coverage, a baseline of 3 is appropriate; description does not meaningfully enhance parameter understanding 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 returns 'the top tools, top packs, and total call volume over a recent window', using a specific verb (Returns) and explicit resource (Pipeworx trending data). It distinguishes itself from siblings by focusing on aggregate call statistics rather than individual queries, and specifies the output components.

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 explicit use cases under 'Useful for', giving clear context for when to use this tool, such as discovering hot data sources or confirming canonical tool choices. It does not explicitly name alternatives or exclusions, but the use-case framing is sufficiently clear. Without explicit 'when not to use', it earns a 4 rather than 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 goes far beyond the annotations (readOnlyHint, openWorldHint, idempotentHint). It details internal thresholds (3pp deviation, Jaccard similarity ≥0.30, >20% placeholder fraction), explains the fill_check behavior (realizable_edge_pp ≤ 0 means do not trade), and discloses fallback behavior (returns null arb signal) — all valuable behavioral context not present in 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 with labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and a clear front-loaded purpose. Every sentence contributes substantive information; the density is appropriate for a tool with multiple modes and complex filtering logic, though it could be tightened slightly.

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 thoroughly by describing response fields (opportunities[], partition_check), failure modes (null arb signal), and edge-case behavior (thin_legs[], realizable_edge_pp ≤ 0). It also distinguishes single-event vs cross-event modes and their tradeoffs, making the tool self-contained 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%, so baseline is 3. The description adds meaningful semantic detail beyond the schema: it explains that event slugs like 'fed-decision-may-2026' are accepted, that full Polymarket URLs are also accepted, and that topic expects a seed question. This enriches parameter understanding without simply repeating schema text.

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 from sibling tools by its unique method (monotonicity/partition checks) and explicitly names alternative tools like polymarket_fill_risk for custom sizing.

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

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

Usage guidance is explicit and prescriptive: 'Call with NO args for a trending_scan', 'pass event for the strongest per-event partition_check', and 'topic for a themed cross-event scan'. It even recommends when to use each mode ('event (recommended for a specific market)') and references the alternative tool polymarket_fill_risk for custom sizing, clearly demarcating when not to rely solely on 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?

Beyond the readOnlyHint, it describes three response segments and five model families, giving details like 'GDELT 7d/21d article-volume ratio, soft signal w/ halved Kelly' and per-sport α values. It also discloses the 24h-move warning, caching behavior ('Cached 1h at the KV level keyed on all knobs'), and diagnostic fields (funnel counters, filter_skips), providing deep insight into the tool's operation.

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

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

The description is long but well-structured, starting with the core purpose, then segment details, output structure, and knobs. It is dense with useful facts (e.g., specific α values for tennis 1.02, soccer 1.10, MMA 1.15) and each sentence contributes substantive information, though it could be more 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?

With no output schema, the description fully explains return values: top-level structure (by_segment, fed_candidates/fed_note, _diagnostics) and fields carried by every opportunity (edge_pp_net, kelly_fraction, market.liquidity, etc.). It also covers edge cases like Fed bets and rare-by-design concentrated_longshot, making it complete for an 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?

Schema coverage is 100%, so a baseline of 3 applies. The description adds value by explaining parameter interactions, e.g., 'min_liquidity / max_spread_pp drop opportunities where edge isn't realizable' and the special handling of min_partition_leg_kelly because 'Partition arbs always return kelly_fraction_half=0 at the parent level'. This clarifies when to apply each knob.

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 ('Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price') and clearly states the use case ('what should I bet on today'). It also differentiates the tool from siblings by detailing model families (e.g., crypto_price, partition_overround) unique to this 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?

It provides a clear context for when to use the tool ('agents discover opportunities without paging hundreds of markets') and explains the tradeable-edge filters (min_liquidity, max_spread_pp) as ways to drop unrealizable edges. However, it does not explicitly mention alternative sibling tools or when not to use this tool, such as for arbitrage-only scanning.

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, idempotent, and non-destructive; the description goes far beyond by detailing response structures (tracked[], expired[], snapshot_dates[]), explaining snapshot gaps, TTL limits, and specifying that decay is computed from daily closes net of slippage. No contradiction with annotations; this is exemplary transparency.

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

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

The description is well-structured with clear Args/RESPONSE/LIMITS labels and dense operational details. It is somewhat verbose, including a metaphorical aside ('wide for a reason nobody is willing to take'), but every section contributes to understanding the tool's behavior and output. Not overly bloated given its 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?

Despite lacking an output schema, the description fully documents the response fields, edge cases (snapshot gaps, TTL expiration), and computation semantics. It covers all necessary aspects for an agent to use the tool correctly, making it contextually complete for a tool with two optional parameters.

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 JSON schema already provides full descriptions for both parameters (days and window), including defaults and ranges. The description restates these briefly ('days lookback default 14 max 30, window snapshot family default 1wk') without adding new semantic information. With 100% schema coverage, the baseline of 3 is appropriate.

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

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

The description clearly identifies the tool as providing edge persistence and decay telemetry built from daily polymarket_edges snapshots, answering a specific question ('how long has this edge existed and is it shrinking?'). This distinguishes it from sibling tools like polymarket_edges by focusing on historical time-series rather than current edge values.

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

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

The description implies usage for analyzing edge persistence/decay and references polymarket_edges as the source, creating an implicit alternative. It does not explicitly say 'use this instead of X' but provides enough context for an agent to infer appropriate use, especially given the sibling tool list.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description goes beyond by detailing the ladder-walking behavior, return fields like 'thin_legs[]' and 'forced_directional_risk', and explicitly warns that 'partial basket fills convert an arb into an unhedged directional position' — a critical behavioral risk not captured by 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 with the core purpose, but it is a single very long paragraph. While all sentences are informative, better structure (e.g., bullet points separating modes) would improve scannability. It is still appropriately sized for the tool's complexity.

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

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

With no output schema, the description must explain return values, and it does so thoroughly: top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict, capture_ratio, profit_usd, thin_legs, max_clean_notional_usd, and forced_directional_risk. It also explains mode prerequisites and risk scenarios, making it complete for an 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?

Schema coverage is 100%, but the description adds meaning by tying parameters to modes: 'SINGLE-MARKET: pass a market slug/URL + side...' and 'BASKET: pass an event slug/URL + side...'. It also clarifies size_usd interpretation ('max spend on buys, target proceeds on sells', 'settlement notional S'). Slight redundancy with schema keeps it from a 5.

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 precise purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes the two operating modes (single-market and basket) and explicitly connects the tool to sibling tools (polymarket_arbitrage, polymarket_edges), making its role unique.

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 THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains why (theoretical overround not capturable, partial fills cause unhedged positions), giving clear when-to-use and implicitly identifying 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 declare readOnlyHint/openWorldHint/idempotentHint, and the description adds substantial operational context: the compatibility_warning triggers, temporal_alignment flag, and skipped_cross_type/ sub type counters that expose comparison internals. This goes far beyond the annotation hints, disclosing exactly when output is meaningless.

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 organized into clear sections (TWO MODES, RESPONSE, SAFETY FIELDS) with front-loaded purpose. Some redundancy exists (e.g., re-explaining skipped cross types in the warning narrative), but every sentence contributes useful detail for a complex 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?

With no output schema, the description fully compensates by explaining the response shape (leg-by-leg prices, top_spreads_pp, compatibility fields) and edge cases. It anticipates likely user errors (non-equivalent bet shapes, temporal mismatch) and provides complete usage guidance for a niche comparative 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?

Although schema coverage is 100%, the description adds critical interpretive value: it lists all ten pre-mapped topic values, explains the override behavior for kalshi_event_ticker and polymarket_event_slug, and gives examples. It also clarifies the response fields (raw probability 0-1, spread in pp) that depend on parameter choices.

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 precise verb+resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly distinguishes from siblings like polymarket_arbitrage by focusing on the same-question cross-venue comparison and explicitly detailing two modes (topic shortcuts vs explicit event IDs).

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 explicit when-to-use context: compare the same resolving question across venues, and notes the delta is only a real signal when bet shapes are equivalent. It cautions that 'pre-mapped ≠ tradeable' and describes conditions where no arb exists, but it does not explicitly name alternative sibling tools for different scenarios.

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 context beyond annotations by explaining the scoping mechanism ('Scoped to your identifier (anonymous IP, BYO key hash, or account ID)') and the key-omission behavior for listing all keys. It does not detail the return format, but this is minor for a simple read operation.

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

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

The description is concise (three sentences) with the primary action front-loaded. Every sentence adds distinct value: what it does, when to use it, scoping, and related tools. No redundancy or fluff.

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

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

For a simple retrieval tool with one optional parameter and strong annotations, the description is fully adequate. It covers purpose, usage, scoping, and relationships to sibling tools. The lack of an output schema is not a problem because the behavior is straightforward and the description sufficiently explains what will happen.

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

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

Schema coverage is 100%, so the parameter `key` is already described as 'Memory key to retrieve (omit to list all keys)'. The description adds value by giving concrete examples of what keys represent (user's target ticker, address, research notes) and reinforces the omit-to-list behavior, going beyond the schema's 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 and resource: 'Retrieve a value previously saved via remember, or list all saved keys.' It clearly distinguishes this from siblings by explicitly pairing with remember and forget, and provides concrete use cases (target ticker, address, research notes).

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 states when to use: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also names the companion tools for save/delete operations ('Pair with remember to save, forget to delete'), giving clear alternatives for related actions.

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, idempotentHint, and openWorldHint, but the description contradicts these by stating mark_read:true flags events as read and affects future calls, implying a state-changing, non-idempotent operation. This is a serious discrepancy.

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?

Four sentences, front-loaded with purpose, each adding value—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?

Despite no output schema, the description explains return payload fields (source, citation_uri, raw event payload) and addresses filtering, mark_read, and alternate access, covering most operational context. However, the contradiction with annotations leaves ambiguity about side effects.

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

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

Schema covers 100% of parameters with descriptions, and the description adds examples like 'sec_8k' and clarifies the effect of mark_read and since, providing meaning beyond the schema.

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

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

The description uses the specific verb 'Pull' and clearly identifies the resource ('fired events from your subscription feed'). It distinguishes from sibling tools like recent_changes by emphasizing subscription feed alerts and the mark_read behavior.

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 guidance that polling works and points to an HTTP endpoint for scripts/dashboards as an alternative. Also explains mark_read behavior for subsequent calls, giving clear context on when and how to use.

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 readOnly/openWorld/idempotent annotations, the description details fan-out to SEC EDGAR, GDELT→GNews fallback behavior, USPTO soft-fail due to API sunset, and return structure. This discloses non-obvious behaviors and edge cases.

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 earns its place, starting with trigger examples, then the core function, source breakdown, parameter syntax, return format, and alternative tool. It is well-organized and front-loaded with the key concept.

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

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

With no output schema, the description compensates by explaining the return structure (changes grouped by source, total_changes, citation URIs). It also covers source fallbacks and known limitations (PatentsView sunset), making it complete for a complex tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds semantic context by linking `since` to source behavior (e.g., 'filings since `since`', 'news mentions in window') and giving typical monitoring suggestions ('30d' or '1m'), which enriches the parameter meaning beyond the schema.

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

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

The description clearly identifies the tool as a 'change feed for a company in the last N days/weeks/months' with explicit natural language triggers. It distinguishes from sibling entity_profile by stating 'Use entity_profile instead when you want the static profile...'.

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

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

The description provides explicit when-to-use with example queries ('What's new with X', 'latest on Y') and an explicit alternative (entity_profile) with a condition for switching. This goes beyond implication to clear 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 annotations, the description reveals that memory is 'scoped by your identifier', with 'authenticated users get persistent memory; anonymous sessions retain memory for 24 hours'. This adds critical behavioral context about persistence and expiration that annotations do not provide. It aligns with idempotentHint by describing key-value storage.

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?

Four sentences, each with a distinct purpose: purpose, usage trigger, storage/persistence, and sibling pairing. It is front-loaded with the core action first, but the sibling pairing could be merged with usage guidance to reduce length.

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

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

For a simple two-parameter tool with no output schema, the description covers the essential behavioral contract: what is saved, when to save, how long it persists, who it is scoped to, and how to retrieve/delete. This is sufficient for correct use.

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

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

The input schema covers both key and value with 100% description coverage, so the baseline is 3. The description only generically refers to 'key-value pair' without adding parameter-specific details; however, it does note scoped by identifier, which applies to the key's scope.

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 'Save data the agent will need to reuse later', a specific action and resource. It also distinguishes itself from sibling tools by pairing with recall (retrieve) and forget (delete), making its role in the memory workflow clear.

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

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

The description explicitly says 'Use when you discover something worth carrying forward' and provides concrete examples like 'a resolved ticker, a target address'. It also names alternatives: 'Pair with recall to retrieve later, forget to delete', which clarifies when to use this vs siblings.

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

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

Beyond the read-only/idempotent annotations, the description discloses the internal cascade of multiple lookup endpoints, exact data sources (SEC EDGAR, RxNorm), output fields (ticker, CIK, RxCUI, ingredient, brand), auto-disambiguation behavior, and citation URI formats. This provides rich behavioral context with no contradiction to 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 dense yet well-structured: it front-loads user-facing query examples, then states purpose, usage guidance, and supported types with field-level detail. Every sentence contributes useful information without redundancy or filler, making it appropriately sized for a two-type resolver.

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 carries the burden of explaining return values. It specifies exact fields for both entity types (ticker, 10-digit CIK, company_name, citation URI for company; RxCUI, ingredient, brand, citation for drug), including the internal cascade and disambiguation, making the tool's behavior completely predictable.

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

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

The schema already covers both parameters at 100% coverage, so the baseline is 3. The description enhances this by detailing accepted input formats (ticker, CIK, name for company; brand/generic for drug), what each type returns, and auto-disambiguation, adding meaningful semantic value beyond the schema's short 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 clearly defines the tool's purpose as resolving user-spoken names to canonical identifiers, with concrete examples (ticker, CIK, RxCUI) and explicit mention that other tools require these IDs. It distinguishes itself from siblings by emphasizing the 'name -> ID' role and stating 'Use FIRST whenever you have a name but need an 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 gives explicit when-to-use guidance ('Use FIRST whenever you have a name but need an ID') and includes sample user queries that trigger the tool. It also explains the benefit of replacing 2-3 manual lookups, but does not explicitly state when not to use it or name alternative tools, so it falls short of a 5.

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

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

Annotations already declare read-only/idempotent behavior. The description adds meaningful context: it probes each entity with ai_visibility_check, ranks by score, surfaces most/least recognized, and returns per-entity score/confidence/signal density. This goes beyond what annotations provide.

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

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

Three sentences, each earning its place: method, use case, and output format. Front-loaded purpose, no wasted words, and easy to scan.

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

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

With no output schema, the description explicitly lists the return fields (score, confidence, signal density) and covers the tool's core behavior and parameters. It could mention failure handling or rate limits, but given the annotations and schema richness, it is sufficiently complete.

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

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

Schema description coverage is 100% and each parameter has a clear description. The description adds crucial semantic detail by noting that the first entity in 'entities' is treated as the 'subject' for narrative and the rest are competitors, which is 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 states the tool's function with a specific verb ('Compare') and resource ('AI visibility across multiple entities side-by-side'). It distinguishes itself from the singleton sibling 'ai_visibility_check' by emphasizing multi-entity comparison and ranking.

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 a concrete use case ('competitive AI-marketing audits') and an example query, giving clear context for when to use the tool. It does not explicitly exclude alternatives, but the guidance is strong enough for an agent to infer appropriate usage.

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

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

Beyond the annotations (readOnlyHint, idempotentHint), the description discloses key behaviors: it fans out across two services, partial failures degrade gracefully, bundlephobia's first measurement can take 5–30s, and the output includes a sources_failed field if a source times out. This adds valuable context without contradicting annotations.

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

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

The description is dense but purposeful, front-loading the core purpose, then usage triggers, return values, ecosystem scope, and failure behavior. Every sentence earns its place, and no fluff is present.

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 enumerates the returned summary block fields (is_latest, license, published_at, advisory_count, bundle_kb_min, bundle_kb_gz, dependency_count, has_esm, tree_shakeable) plus per-advisory details, links, and alternatives. It also covers latency, ecosystem limitations, and partial failures, making it complete for a composite 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 the parameters are already fully documented. The description adds no additional semantics beyond what the schema provides (e.g., package is an npm name, version defaults to latest). This is a baseline 3 per the rubric.

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

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

The description clearly states a specific verb and resource: a composite check for whether to add an npm package, aggregating deps.dev (license, advisories, version history) and bundlephobia (bundle size, dependency count, ESM/tree-shake support). This distinguishes it from siblings like scan_competitor_ai_presence and clarifies the ecosystem scope (NPM only in v1).

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 explicit trigger phrases: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also gives a clear when-not and alternative: non-NPM ecosystems (PyPI/Maven/Cargo/Go) should use 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 indicate a safe, read-only, idempotent operation. The description adds substantial non-obvious behavior: returns passages with character offsets and similarity scores, uses BGE-base-en embeddings over 500-char overlapping windows, and enforces a 200K-char cap with truncation flagging. This goes well beyond the 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?

Four sentences, each earning its place: core functionality, use case, pairing guidance, and technical limitations. The description is front-loaded with the primary action and remains compact despite the density of information.

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

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

For a moderately complex search tool with no output schema, the description covers the return value (passages with offsets and scores), key parameters, the use case, a companion tool, and technical constraints (window size, character cap, truncation). This is fully sufficient for an 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?

Schema description coverage is 100%, so the baseline is 3. The description reinforces the purpose of the text and limit parameters (e.g., 'top-N passages', 'longer inputs are truncated') but does not add significant new semantics beyond what the schema already states.

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

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

The description starts with 'Semantic search INSIDE a fetched record', naming a specific verb, resource, and scope. It provides concrete examples (SEC 10-K body, article) and clearly differentiates from siblings like ask_pipeworx_grounded by framing this as a focused passage-retrieval 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?

Explicitly states when to use: 'Use when the record is too big to cram into the prompt'. It also names the companion tool (ask_pipeworx_grounded) and explains the intended workflow, giving clear context for choosing this tool over 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?

Beyond the annotations (readOnly=false, openWorld=true, idempotent=true, destructive=false), the description adds critical behaviors: OAuth requirement, always-on feed channel, optional email/SMS with verification and daily cap, webhook signing secret returned once, HMAC verification details, and auto-disable after 10 failures. No contradictions with annotations.

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

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

The description is dense but front-loaded with the primary purpose. It packs substantial necessary detail into a single paragraph, but the enumeration of types and delivery channels could be better structured with bullets or clearer separation. Every sentence earns its place, but readability suffers slightly.

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

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

The description covers the main purpose, auth requirements, three of five subscription types, and email/SMS delivery. However, it omits the webhook delivery channel entirely from the main description (only in schema), and it does not mention patent_grant or clinical_trial types despite them being in the enum. This creates an incomplete picture for an agent deciding which tool and options to use.

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

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

Schema coverage is 100% and already detailed. The description adds meaningful context beyond the schema, such as example items codes ('items:["5.02"] = officer change'), the meaning of polymarket_edge cross-venue mispricings, and the phone verification requirement. It omits patent_grant and clinical_trial from its type examples, but the schema covers those.

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: 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' This clearly distinguishes it from sibling tools like list_subscriptions, unsubscribe, and recent_alerts by focusing on subscription creation.

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 strong context on when to use: requires a Pipeworx OAuth account, explicitly notes anonymous/BYO cannot persist, and describes supported subscription types with example params. It does not explicitly name alternatives or state 'when not to use,' but the sibling names and this detail make the appropriate use 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?

Even though annotations already mark the tool read-only and non-destructive, the description adds valuable behavioral context: it returns categorized example questions, each with the exact tool and argument shape, drawn from the live catalog. It also discloses the optional topic focus and the fallback to a full spread, going 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 thorough but somewhat dense, packing many examples and instructions into one long paragraph. It is front-loaded with natural-language query examples, which helps agent recognition, but it could be more concise by separating the purpose, return format, and usage instructions.

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 is complete: it explains what the tool returns, the categories covered, the optional filtering, and the typical use case. The annotations further cover safety and idempotency, leaving no major gaps in context.

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

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

The schema already provides 100% coverage for the single optional `topic` parameter, so the baseline is 3. The description adds extra value by giving concrete examples ('finance', 'pharma', 'betting') and explaining that omitting the parameter yields a cross-category spread, enriching the schema's documented values.

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

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

The description clearly defines the tool as the 'onboarding entry point' that returns 'category-bucketed example questions' with exact tool and argument shapes. It is specific about the resource (the live catalog) and outcome, and it differentiates itself from sibling execution tools like ask_pipeworx by focusing on suggesting what to ask rather than answering.

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 it: '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 provides concrete usage examples ('Call with no arguments for the full spread, or pass topic') and names alternatives (ask_pipeworx, entity_profile, compare_entities) for further learning.

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 annotations (idempotentHint, destructiveHint), the description discloses that the row is deactivated not deleted, which explains the soft-delete behavior, and that historical events remain accessible via recent_alerts. This adds significant behavioral context beyond the structured hints.

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

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

Two tight sentences: the first states the action, the second explains the consequences. No fluff, information-dense and front-loaded.

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

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

For a simple one-parameter tool with no output schema, the description covers the action, ownership constraint, and post-effect (deactivation, historical availability). It is fully sufficient for an 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?

Schema coverage is 100% and the id parameter is well-documented as a subscription uuid returned by subscribe. The description reinforces parameter usage by stating 'by id' and adds the ownership constraint (only your own subscriptions), which is param-relevant context beyond the schema.

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

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

The description clearly states the tool cancels a subscription by id, with a specific verb (cancel) and resource (subscription). It distinguishes itself from siblings like subscribe and list_subscriptions, and adds the ownership nuance.

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 context on when to use: to cancel a subscription, with ownership enforced. It doesn't explicitly state when not to use it, but the behavioral constraints and reference to recent_alerts imply alternatives, so it is clear but lacks explicit exclusions.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive, so the description adds rich behavioral context beyond that: it discloses routing logic, the use of 'exact percent-delta math' for financial claims, the verdict enum, citation format (pipeworx://), and the judgment step. This gives the agent a precise mental model of what happens when the tool is invoked.

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-organized: trigger phrases first, then scope, pipeline details, output summary, and efficiency note. Every sentence earns its place, though the 'Replaces 4–6 sequential calls' line is slightly promotional. No fluff, but it could be tightened without losing information.

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

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

For a tool with no output schema, the description sufficiently covers inputs, internal routing, verdict values, citations, and reasoning. It addresses the main complexity (handling different claim types) and does not leave the agent guessing about return values. It's complete for decision-making 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%, so baseline is 3. The description adds meaningful semantics: it explains that tolerance_pct controls the 'approximately_correct' grading, warns that setting 1–2 is for hallucination detection, and clarifies the default behavior ('implied by wording, capped at 5'). Claim examples also illustrate the expected format. This goes beyond the schema's field names.

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 concrete natural-language triggers ('Is it true that…', 'fact check', 'verify the claim that…') and a crisp verb phrase: 'natural-language claim verification against authoritative sources.' It distinguishes itself from sibling research tools by focusing on validating a specific claim, not open-ended research, and outlines two distinct verification pipelines (structured SEC vs. grounded fallback).

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 whenever the agent needs to check whether something a user said is factually correct.' It also differentiates claim categories (company-financial vs. other) and notes it replaces multiple sequential calls, implying it's the canonical fact-check entry point. It does not explicitly name sibling tools to avoid, but the context is clear enough for selection.

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