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 cover read-only, open-world, idempotent, and non-destructive behavior. The description adds valuable behavioral context beyond that: it routes through 5,689 tools across 1,489 sources, fills arguments automatically, returns pipeworx:// citation URIs, and is described as a single fast call that also handles live news.

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

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

The description is front-loaded with the most important instruction ('PREFER OVER WEB SEARCH') and every section has a clear role: scope, mechanism, triggers, examples, alternatives, and special cases. It is longer than strictly necessary, with some redundancy between the domain list and the later examples, but the length is largely justified for a central routing tool.

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

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

For a tool with no output schema, the description fully explains what the agent gets back, when to call it, what inputs are expected, and which sibling tools to use instead in specific cases. The combination of domain coverage, example questions, and explicit alternative routing makes this complete for an agent deciding whether and how to invoke it.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds meaningful extra context by specifying what kinds of questions are valid and providing concrete examples such as 'current US unemployment rate' and 'Apple's latest 10-K'. This goes beyond the schema's simple 'natural language question' description without being 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?

The description clearly identifies a specific action: route a natural-language question to the appropriate Pipeworx tool and return a structured answer with citations. It also differentiates itself from siblings by naming ask_pipeworx_grounded and deep_research as alternatives, so an agent can tell them apart.

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 is explicit about when to use this tool: prefer it over web search for factual/current/historical questions, use it as the default entry point, and step up only for grounded single answers or broad multi-part research. It even names the sibling tools to use in those cases.

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, open-world, and non-destructive. The description adds substantial live behavior: candidate routing improvements are active only while under test, none is currently active because the last was retired on 2026-07-26, and there is no fallback because this is a fully working router. This goes well beyond the annotation signal.

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

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

The description is front-loaded with identity and scope, then provides current state, usage guidance, and a clarifying note about the lack of fallback. Every sentence contributes distinct information with no redundancy.

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

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

For a single-question router with thorough annotations and complete schema coverage, the description covers identity, current behavior, usage, and experimental status. The only minor gap is that the response shape is delegated to 'same response shape as ask_pipeworx' rather than described locally, since no output schema is present.

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

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

Schema description coverage is 100%: the question parameter and all five aliases are documented in the input schema. The tool description adds no new parameter-level semantics beyond 'same arguments as ask_pipeworx,' so the schema carries the full burden.

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

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

The description clearly defines ask_pipeworx_beta as a beta variant of ask_pipeworx: a universal router over 5,689 tools with the same arguments and response shape, plus optional live routing improvements. This distinctively separates it from the stable ask_pipeworx sibling and the grounded variant.

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

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

It explicitly says to 'Use it exactly like ask_pipeworx when you want the newest routing' and explains results are compared against the stable router to decide merges. This gives clear selection context, though it does not formalize a 'use stable when...' exclusion beyond the 'experimental edge' implication.

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 signal readOnly, openWorld, and idempotent behavior, but the description adds substantial behavioral detail: success and refusal return shapes, refusal_reason values, evidence quoting, and the extra LLM call cost. This meaningfully enriches the agent's understanding 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 dense but well-structured: mode, mechanism, return/refusal contract, usage guidance, and cost tradeoff. Every sentence serves a purpose and the most decision-relevant information is front-loaded.

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

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

Although there is no output schema, the description clearly specifies the success return shape and the refusal_reason enum, making the tool's behavior predictable. It also covers routing, evidence behavior, cost, and when to choose this tool, so the agent has enough context to invoke it correctly.

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

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

Schema coverage is 100%, with all six parameters documented as aliases for 'question'. The description adds no additional parameter-level semantics beyond the use context, so it meets the baseline for schema-documented parameters 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 identifies the tool as a hallucination-resistant answer mode that extracts answers using only tool-result content. It explicitly differentiates itself from ask_pipeworx by emphasizing grounded extraction and refusal behavior, so an agent can distinguish it from siblings without inspecting schemas.

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: anytime an answer will be quoted, cited, or acted on, with examples like financial verdicts, legal claims, and medical lookups. It also states when not to use it by recommending ask_pipeworx for casual lookups and noting the extra LLM call cost.

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?

Beyond the readOnly/idempotent annotations, the description discloses authentication requirements, paid depth tier, parallel decomposition, gaps[] for unanswered facets, contradictions[] for standard/thorough, citation fetchability caveats, semantic excerpting, and latency expectations. This is substantial, non-redundant behavioral context.

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

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

The description is long but dense, and the most decision-critical facts (account requirement, what it is, alternatives) are front-loaded. Each later detail — gap recovery, contradictions, citation_uri, excerpting, latency — serves a distinct purpose rather than padding.

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

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

With no output schema, the description fully explains the return shape: findings packet with evidence, confidence, source, fetched_at, citation_uri, gaps[], contradictions[], and hop field. It also covers auth, depth behavior, use-case boundaries, and expected latency, 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?

Although schema coverage is 100%, the description adds meaning beyond the schema: it explains that depth:'standard' re-angles unanswered facets, depth:'thorough' chases leads and requires a paid plan, and that the question can be broad/multi-part since decomposition is the point. This materially helps an agent choose parameter 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 identifies the tool as grounded multi-source research across Pipeworx's 1489 structured data sources in one call, explicitly noting it is NOT open-web search. It distinguishes itself from sibling ask_pipeworx by naming what it is not and what type of questions it serves.

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 routing guidance: use deep_research for broad/multi-part structured questions; use ask_pipeworx for single lookups, breaking/colloquial current news, or when not signed in. These alternatives are named directly, leaving no ambiguity about when to choose this tool.

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

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

Annotations 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?

Annotations are all false and therefore uninformative, so the description carries the full burden. It discloses rate limiting (5 per identifier per day), that the tool is free and doesn't count against quota, the claim_token workflow, the daily digest processing, and the instruction not to paste end-user prompts. This is rich, transparency-enhancing detail far beyond the 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 longer than ideal, but every sentence earns its place: exclusions, workflow, rate limits, and use cases are all meaningful. It is front-loaded with the core purpose, then the triggers, then scope restrictions, then operational details. 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?

Given 4 parameters (including a nested object), no output schema, and uninformative annotations, the description is exceptionally complete. It covers intended use, exclusions, payload specifics, the claim_token follow-up mechanism, rate limits, and feedback processing — leaving no practical ambiguity for the agent.

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

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

Schema coverage is 100% with detailed descriptions for type, context, message, and claim_token. The description adds non-redundant semantic value by explaining the claim_token round-trip ('pass it back later as pipeworx_feedback({claim_token:...})') and by relating the enum values to real-world scenarios. This exceeds the baseline for fully-covered schemas.

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

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

The description leads with 'Tell the Pipeworx team something is broken, missing, or needs to exist', which is a specific verb+resource statement. It enumerates concrete trigger cases (bug, feature, data_gap, praise) and explicitly scopes the tool to 'tools served by this Pipeworx connection', distinguishing it from sibling query tools like ask_pipeworx.

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

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

The description provides explicit when-to-use guidance ('Use when a tool returns wrong/stale data... works surprisingly well') and clear when-not-to-use guidance ('if the tool came from a different MCP server... file it with that server instead'). It also tells users how to verify the correct server ('Pipeworx tool names are the ones this connection lists').

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?

Annotations already declare safe read-only/idempotent/non-destructive behavior. The description adds substantial context: the tool cascades through multiple internal lookups, degrades gracefully (if GLEIF/OpenFIGI unavailable, EDGAR still returns), and specifies that unresolved identifiers are explicitly stated under an 'unresolved' field. 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 long but well-structured: front-loaded with user query examples and usage directive, then systematic sections for each type. While slightly verbose, every sentence adds necessary context for a complex entity resolution tool that replaces multiple lookups. The length is justified by the tool's breadth.

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 thoroughly explains what the tool returns (identifiers labeled with source, unresolved list, graceful degradation). It covers both entity types, special mappings (ISIN to LEI), and multiple identifier sources (SEC EDGAR, GLEIF, OpenFIGI, RxNorm). The description is self-contained and provides all necessary context 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%, so baseline is 3. However, the description greatly enriches both parameters: for 'type', it explains what identifiers each type returns (e.g., company yields CIK, ticker, LEI, FIGI; drug yields RxCUI). For 'value', it provides explicit examples (ticker, CIK, ISIN, brand/generic names) and special behavior (ISIN maps to legal entity via GLEIF). This adds significant 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 specific verbs ('resolve', 'look up') and resources ('name to canonical identifiers'). It provides multiple user query examples and explicitly states 'Use FIRST whenever you have a name but need an ID.' This clearly distinguishes it from sibling tools like ask_pipeworx or 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 explicitly says 'Use FIRST whenever you have a name but need an ID' – a clear when-to-use directive. It also explains that the tool replaces 2-3 manual lookups, reinforcing its primary role. However, it does not explicitly state when NOT to use it or provide alternatives for cases where the user already has an ID.

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 readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds critical behavioral context: the two distinct pipelines, the meaning of each verdict (especially the crucial caveat that could_not_verify means the check did not happen and must not be treated as evidence), and the tolerance semantics. This goes well beyond the 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 information-dense with no fluff. It front-loads the purpose and examples, then explains routing, return values, error semantics, and efficiency. Every sentence contributes practical guidance for correct invocation and interpretation.

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 (two routing paths, multiple verdict types, error handling, tolerance logic) and no output schema, the description covers all key aspects: return values (verdict, actual value, citation, reasoning), the difference between could_not_verify and unsupported, and how tolerance affects grading. It is fully adequate for an agent to use correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful extra semantics: tolerance_pct overrides the tolerance implied by claim wording, and it explains how the two pipelines use the claim parameter. This elevates it above the baseline.

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

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

The description gives specific verbs ('validate', 'fact check', 'verify the claim') and clearly states the tool's resource: natural-language claim verification against authoritative sources. It differentiates from siblings by describing its two routing paths (SEC EDGAR for company financials, grounded pipeline for all else), which is unique among the sibling list.

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

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

It explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct' and provides routing rules for claim types. However, it does not name alternative tools or explicitly state when NOT to use it, so it stops short of the highest bar.

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