Opendatasoft

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

The description adds meaningful behavior beyond the annotations (readOnly, idempotent, non-destructive): it discloses the default model (Workers AI Llama-3.3-70b, free), that passing `_apiKey` routes calls to Anthropic with direct payment, and the exact return structure. This cost and model-selection context is not present in annotations and is valuable.

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

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

The description is a single paragraph that front-loads the core purpose, then covers model selection, cost behavior, return format, and use cases in just three efficient sentences. There is no filler or redundant repetition of schema details.

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?

Even without an output schema, the description explains what the tool returns ('per-model {score, confidence, signals, raw_response} + a combined view'). It covers model options, API key requirements, cost implications, and use cases, making it complete for an agent to decide 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%, so the baseline is 3. The description adds extra meaning by linking `_apiKey` to Anthropic and mentioning that `context` helps disambiguate common names, slightly enriching what the schema already provides. It doesn't elaborate on parameter formats, but that's already 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 what the tool does: 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' It names the resource (LLMs), the action (probe), and the specific output (score, confidence, signals, raw_response). It distinguishes itself from siblings like ask_pipeworx or deep_research by focusing on LLM knowledge visibility scoring.

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 use cases: 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' This gives clear context for when the tool is appropriate. However, it does not name alternative tools or state when not to use it, so it stops short of full exclusion guidance.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds valuable behavioral context: routing across thousands of sources, stable citation URIs, works on every tier, and one fast call. No contradiction, though it doesn't discuss rate limits or auth, which is acceptable for a read-only query tool.

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

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

The description is long but well-structured, front-loaded with the key 'PREFER OVER WEB SEARCH' callout and then organized into scope, examples, alternatives, and caveats. Each sentence contributes meaningful guidance, 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?

Despite no output schema, the description specifies the return format (structured answer with pipeworx:// citation URIs). It also covers performance, tier compatibility, and alternative tools, making it self-sufficient 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?

Input schema has 100% coverage with all aliases documented. The description supplements this by providing concrete example questions and clarifying that the input is a natural-language question. This goes beyond the schema's minimal alias 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 a specific verb ('routes') and identifies the resource (questions to 5,529 tools across 1,455 verified sources). It clearly distinguishes from siblings by naming ask_pipeworx_grounded and deep_research as alternatives. The 'START HERE' directive reinforces its primary role.

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

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

Explicitly states 'PREFER OVER WEB SEARCH' and provides a detailed list of query types and examples. It gives clear 'when not to use' guidance by directing users to ask_pipeworx_grounded for hallucination-resistant answers and deep_research for broad/multi-part questions, establishing strong differentiation.

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 explains that candidate routing improvements may be enabled live and that results are compared against the stable router for merging decisions. It also confirms that despite being beta, it is a complete router. This adds meaningful context beyond the annotations' readOnly/idempotent hints, though it doesn't describe all edge-case behaviors.

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

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

The description is front-loaded with the beta status and proceeds logically through the current equivalence, usage instruction, and reassurance of full functionality. Each sentence conveys necessary information, but the phrasing is slightly verbose and could be tightened without losing meaning.

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 role as a beta variant of a known router, the description fully covers its purpose, current state, usage, and relationship to the stable version. It explicitly mentions the shared response shape, so the absence of an output schema is handled. No critical information is missing for an agent selecting and invoking the tool.

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

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

Schema coverage is 100%, with every alias (q, text, input, query, prompt) documented and clearly linked to the required 'question' parameter. The description adds no additional parameter semantics, but the schema already provides full meaning, so the baseline score of 3 is appropriate.

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

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

The description clearly states it is a 'Beta version of ask_pipeworx' and an 'identical universal router' with the same tools, arguments, and response shape. It immediately distinguishes itself from the stable ask_pipeworx by its experimental routing improvements, making the purpose and differentiation 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?

Explicitly tells the agent when to use it: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also clarifies the current state (no active candidate, so identical to ask_pipeworx) and that it is a fully working router with no fallback, which prevents misuse in production contexts.

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 declare readOnly/openWorld/idempotent, the description adds significant behavioral detail: it returns a structured object with evidence as a verbatim quote, provides a specific refusal_reason enum, and notes the extra LLM call cost. It also explains the internal pipeline ('picks the right tool... fills arguments, fetches the data'). No contradiction with annotations.

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

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

The description is dense but every sentence earns its place: purpose, process, return shape, refusal reasons, usage guidance, and cost trade-off. It is front-loaded with a decisive first sentence and uses clear punctuation to separate concerns. 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 goes beyond expectations by fully specifying the success return object and all refusal reasons. It also covers the key context of cost and alternatives. Given the tool's complexity (routing across 5,529 tools, extraction logic), this description is remarkably complete.

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

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

Schema description coverage is 100% (the 'question' parameter and its aliases are fully described in the schema). The description adds no additional parameter-level semantics beyond stating the question is natural language, which the schema already covers. Baseline 3 is appropriate because the schema carries the 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 opens with a specific verb and resource: 'Hallucination-resistant answer mode for high-stakes reads.' It clearly distinguishes itself from the sibling ask_pipeworx by emphasizing 'EXTRACTS the answer using ONLY what the tool result contains' and returning an explicit refusal when the data doesn't answer. This makes the tool's unique purpose immediately 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 provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' It also names the alternative tool and gives a cost-based exclusion: 'Costs one extra LLM call vs ask_pipeworx — prefer ask_pipeworx for casual lookups.' This fully satisfies the dimension.

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 readOnly+idempotent, but the description goes far beyond by disclosing edge-case behaviors: low-confidence matches short-circuit with status:'low_confidence_match', closed markets return 'market_closed_or_inactive', wide spreads carry tradeability:'illiquid_wide_spread', cancellation rules are parsed, and news fallback mechanics include _fallback_attempted and retry_after_sec. These are valuable behavioral traits not inferable from annotations alone.

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 (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.) and front-loaded core purpose. While every sentence adds substantive detail, it is dense and lengthy; a 4 reflects that the structure helps navigation but could be tightened without losing essential info.

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 explains return shapes: result.market, result.analysis, result.evidence, parent_event fields, and market_match_confidence. It also covers safety mechanisms and resolution-rule risk. This is complete enough for an agent to confidently invoke the tool and interpret results without additional documentation.

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, so baseline is 3. The tool description adds meaningful context beyond the schema: it explains how 'market' input is resolved (slug/URL/question) and gives fan-out examples for 'depth: thorough' (e.g., BTC bet → coingecko + fred + gdelt+gnews). This supplements the schema without redundancy.

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

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

The description opens with a clear verb+resource statement: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies inputs (slug, URL, question text) and outputs (evidence packet + market-vs-model comparison), and distinguishes itself from siblings by focusing on Polymarket bet research with data fan-out and edge calculation.

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 use cases are given: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' This gives clear context for when to invoke the tool. Sibling differentiation is not explicitly named, but the described behavior (market resolution, classifiers, fan-out) is unique among the siblings. No exclusions are stated, so it merits a 4 rather than 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/idempotentHint/destructiveHint, but the description goes far beyond by revealing data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorting by primary metric, and the return of citation URIs. This provides crucial behavioral context that annotations do not convey.

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

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

The description is a single dense paragraph but every sentence adds a distinct, valuable piece of information: trigger phrases, preference guidance, data sources, sorting behavior, and output format. It is front-loaded with the most important usage cues and avoids redundant 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?

Given the tool's complexity (two entity types, 2–5 items, no output schema), the description fully covers return values (paired data + citation URIs), sorting logic, data sources, and edge cases like off-calendar fiscal years. It leaves no major questions for an agent choosing or invoking the tool.

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

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

Though schema coverage is 100%, the description adds significant meaning to the 'type' parameter by explaining exactly what each type pulls (10-K financials for companies, FAERS/trial counts for drugs) and what the 'values' parameter should contain for each type. This goes well beyond the schema's basic descriptions.

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

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

The description opens with a clear verb phrase ('side-by-side comparison of 2–5 companies or drugs in ONE parallel call') and provides explicit trigger examples ('Compare X and Y'), making the tool's purpose unmistakable. It also distinguishes this from single-entity lookups by emphasizing the parallel comparison capability.

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

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

The description explicitly states when to use this tool ('ALWAYS PREFER over sequential single-pack lookups when comparing entities') and lists specific user-language cues ('X vs Y', 'which is bigger', 'rank these companies'). This gives clear, actionable guidance for an AI agent deciding between this and alternative tools.

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

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

Annotations already declare readOnly, idempotent, and non-destructive hints. The description adds behavioral detail by specifying return contents (field definitions, record count, dataset description) and the role of the portal instance, enriching understanding 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 a single sentence, front-loaded with the action and resource, then lists return values. Every word contributes, with no redundancy or fluff.

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

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

For a low-complexity metadata fetch with an output schema present, the description covers the core purpose, inputs, and return values well. Minor gap: it does not explain instance default behavior, but this is not critical given the simplicity.

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 0%, so the description must compensate. It references dataset_id explicitly and implies instance via 'specified portal instance', but it does not explain whether instance is optional or what happens if omitted, leaving a semantic gap for the 2-parameter tool.

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

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

The description uses a specific verb 'Fetch' and clearly identifies the resource: 'schema and metadata for a single Opendatasoft dataset by dataset_id'. It distinguishes from sibling 'datasets' (plural) by emphasizing 'single', making the scope explicit.

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

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

The description implies when to use this tool (when needing schema/metadata for one dataset) and contrasts with plural 'datasets' sibling, but it does not explicitly name alternatives or state when not to use it. This provides clear context without formal 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, so safety is well covered. The description adds valuable context about the default instance (public.opendatasoft.com) and the returned fields, which goes beyond the schema. It doesn't mention rate limits or pagination behavior, but given the strong annotations, this is adequate.

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

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

The description is a single sentence that is front-loaded with the verb and resource, and it packs essential information (scope, filters, return values) without any 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?

The tool has 6 params, no required params, a good annotation set, and an output schema. The description covers the main use case and return summary, but it doesn't explain sort/facet syntax or pagination (start/rows). Schema examples partially fill this gap, making it adequate for a search 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 only 33% (2 of 6 params have descriptions). The description clarifies 'q' as keyword and mentions optional sort and facet filters, and confirms the default instance, but it does not explain 'rows' or 'start' parameters. This partially compensates for the low schema coverage but leaves gaps.

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 'Search datasets on any Opendatasoft portal' with a specific verb, resource, and scope, and lists return values (dataset IDs, titles, field summaries). It does not explicitly contrast with the sibling 'dataset' tool, so it stops short of fully distinguishing from alternatives.

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

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

The description clearly implies when to use the tool: for keyword-based dataset search across Opendatasoft portals, with optional sort and facet filters. It doesn't mention exclusions or name alternative tools like 'dataset' or 'records', but the context is sufficient for most selection 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?

Beyond the read-only/idempotent/open-world annotations, the description adds rich behavioral context: account and payment tiers, parallel decomposition across 5,529 tools, explicit gaps[] for unanswered facets, resolvable citation_uri only when fetchable, contradictions[] for standard/thorough, semantic excerpting of large records, and latency expectations. Nothing contradicts the annotations, and the description materially expands on them.

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

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

The description is dense and every sentence adds value; it front-loads the account requirement and core distinction. However, it is a single long block with many interconnected clauses, making it slightly harder to scan; breaking it into short paragraphs or bullets would improve structural clarity.

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 specifies the return format (findings packet, verbatim evidence, confidence, source, fetched_at, pipeworx:// citation, gaps[], contradictions[], hop field), explains latency ranges, and covers limitations like empty gaps for current-news topics. An agent has enough context to invoke and interpret results 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?

Even though schema coverage is 100%, the description adds substantial meaning beyond the schema. It explains what kind of question is appropriate with concrete examples, and for depth it details the behavior differences among quick/standard/thorough (hop counts, gap recovery, contradiction scan, paid tier), which the schema enum alone does not convey.

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: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' and explicitly contrasts with 'NOT open-web search.' It distinguishes itself from siblings by noting it is 'Best for broad/multi-part questions' versus single lookup or current-news use cases, making its purpose and differentiation unmistakable.

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/when-not guidance: use for broad/multi-part structured-data questions, use ask_pipeworx for single lookups, and prefer ask_pipeworx for breaking/current-news topics. It also states account requirements and the fallback to ask_pipeworx when not signed in, 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 already declare the operation as read-only, idempotent, and non-destructive, so no contradiction arises. The description adds valuable behavioral context beyond the annotations: it returns top-N results complete with schemas and curated examples, eliminating the need for a second lookup. This is a notable behavioral detail that helps the agent predict the tool's output and efficiency.

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 information-dense but well-structured: purpose, usage condition, domains, return details, and placement advice. Every sentence contributes—no filler. While slightly longer, it is justified by the breadth of the tool's function and the need to communicate its meta-role clearly.

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 is complete for a tool with no output schema. It specifies what is returned ('top-N most relevant tools with names, descriptions, and full input schemas with curated examples'), how results are ready to call, and the recommended usage context. The input schema covers parameters, so no additional param requirements are needed.

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

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

Schema description coverage is 100%, with the schema fully documenting the 'query' parameter and its aliases (q, task, search, description) plus 'limit'. The description reinforces that the query is a natural language description and mentions 'top-N' (aligning with the limit parameter) but does not add new parameter-level semantics beyond what the schema provides, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It enumerates the coverage areas (SEC filings, FDA drugs, economic data, etc.) and explicitly distinguishes itself from sibling tools by being the meta-discovery tool ('Call this FIRST...'). It also describes the output format, solidifying its unique role.

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

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

The description provides explicit usage guidance: 'Use when you need to browse, search, look up, or discover what tools exist for [list].' It also tells the agent to 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This clearly separates when to use discover_tools versus directly invoking a known sibling 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 annotations (readOnly, openWorld, idempotent), the description discloses notable behavioral details: patent data soft-fails due to USPTO API sunset, news uses a GDELT→GNews fallback, and names are not supported. These add context about reliability and constraints without contradicting annotations.

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

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

The description is long but every sentence packs meaningful detail: examples, use-case priority, fan-out sources, return fields, and fallback behavior. It is front-loaded with natural-language triggers and structured with semicolons, though slightly dense as a single block.

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

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

With no output schema, the description fully carries the burden of explaining returns. It enumerates all returned data groups (cik, filings, fundamentals, patents, news, LEI) and includes constraints (max 5 filings, patent sunset, fallback chain). It is complete for the tool's complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by giving concrete examples ('AAPL', '0000320193'), re-emphasizing the zero-padded CIK format, and clarifying that names are unsupported—reinforcing the schema's description but not making it 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 opens with concrete user intents ('Tell me about X', 'research Acme') and states a specific verb+resource: 'full cross-source profile of a US public company in ONE parallel call.' It distinguishes itself from sibling tools like resolve_entity and compare_entities by emphasizing the all-in-one 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?

Explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' and instructs to 'use resolve_entity first if you only have a name.' This provides clear when-to-use and alternative tool 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 the tool as read-only, idempotent, and non-destructive, covering safety. The description adds the core output behavior (distinct values and counts) but does not disclose potential limitations like pagination, ordering, or count accuracy.

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

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

The description is two sentences, front-loaded with the main verb and resource, and contains no wasted words. It is concise and well-structured.

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

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

The description is adequate for a read-only facets tool but has significant gaps in parameter semantics, especially for 'instance'. Given no schema descriptions, the tool is not fully self-contained for autonomous use.

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

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

The schema has zero property descriptions, so the description must compensate. It implicitly covers 'facet' and 'dataset_id' but leaves 'instance' unexplained, which is ambiguous and critical for correct invocation.

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

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

The description clearly states the action (retrieve), resource (distinct values and counts for a facet field within an Opendatasoft dataset), and purpose (enumerating categories or filtering options). This distinguishes it from sibling tools like 'records' that query actual records.

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 on when to use this tool ('before querying records'), but does not explicitly name alternative tools or state when not to use it. This gives sufficient guidance without exclusions.

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

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

The description confirms the destructive nature ('Delete') which aligns with the destructiveHint=true annotation. It adds the context of clearing sensitive data but doesn't disclose additional behavioral traits beyond what annotations already convey, such as irreversibility or idempotency. No contradiction with annotations.

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

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

The description is concise and front-loaded with the primary purpose. The three sentences each provide value: purpose, use cases, and related tools. No wasted words.

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

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

For a simple one-parameter tool with annotations and no output schema, the description is complete enough. It covers purpose, usage, parameter, and related tools. The idempotentHint annotation addresses behavior for missing keys, so the description doesn't need to explain that. Some might expect a note on return value, but that's not critical here.

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 the key parameter described as 'Memory key to delete' in the schema. The description merely repeats 'by key' without adding extra meaning or format details. Baseline 3 is appropriate since the schema already handles parameter semantics.

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

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

The description clearly states the tool's function: 'Delete a previously stored memory by key.' This uses a specific verb and resource, and it distinguishes itself from sibling tools like remember and recall, which store and retrieve memories respectively.

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 context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also mentions pairing with remember and recall. However, it doesn't explicitly state when not to use this tool or name alternatives, so it falls slightly 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 establish read-only, non-destructive, idempotent, and open-world behavior. The description adds valuable context by explaining that it fetches the page, extracts title/description/key links, and emits a text blob. It also notes the output location (site-root/llms.txt), which goes beyond 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 three sentences, front-loaded with the main purpose, followed by the process and use cases. Every sentence contributes value and there is no redundancy or fluff.

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

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

Given the tool's moderate complexity (network fetch, output generation), the description covers the input (URL), the process (fetch/extract/emit), the output (single text blob), and placement guidance. Annotations cover safety and idempotency, making this 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 description coverage is 100% for both parameters (url and max_links), so the description doesn't need to compensate. The description does not add additional meaning beyond what the schema already provides, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool's action (generate a production-ready llms.txt file), the target resource (any URL), and the output format (standard llms.txt markdown). It distinguishes itself from sibling tools like ai_visibility_check or scan_competitor_ai_presence by focusing on file generation rather than analysis.

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

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

The 'Useful for' section provides clear context for when to use the tool (client indexing, own project, competitor audit), but it does not explicitly mention alternatives or when not to use it. This is clear context without exclusions, earning 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?

Annotations already declare read-only, open-world, idempotent, and non-destructive behavior. The description adds the default instance behavior and specifies the kind of metadata returned. This goes beyond annotations by clarifying scope and default, though it omits details like error handling 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?

The description is one sentence, front-loaded with the verb and resource, and includes a default. Every word earns its place with no fluff or repetition of schema or annotation details.

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 (one optional param, no nested objects, output schema present). The description covers the main inputs, default behavior, and key output elements. It lacks mention of error cases or potential limitations, but given the low complexity and annotations, this is nearly 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 0%, so the description must compensate. It clarifies that the 'instance' parameter identifies a portal and mentions the default, but does not specify accepted formats or value constraints beyond the schema's example. This is minimal but useful compensation for a single optional parameter.

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

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

The description uses a specific verb ('Fetch') and resource ('catalog-level metadata for an Opendatasoft portal instance') with concrete details (total dataset count, themes, languages). It clearly distinguishes itself from sibling tools like 'datasets' and 'records' which handle data-level 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 context is clear: this is for portal-level metadata, not dataset-level details. The default to public.opendatasoft.com provides practical guidance. However, it does not explicitly name alternative tools or state when not to use it, though the sibling list offers obvious contrasts.

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 readOnly, so the description adds value by specifying the return fields (id, type, params, created_at, etc.) and scoping to the caller's own subscriptions. It does not contradict annotations and adds useful behavioral context beyond what annotations provide.

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

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

The description is two sentences, front-loaded with the action, and includes return details and usage guidance without any filler. 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?

The tool is simple with one optional parameter and no output schema; the description fully covers what it returns and when to use it. Annotations cover safety, making this complete for an agent to select and invoke.

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

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

Schema description coverage is 100% for the single parameter include_inactive, which already explains the default false. The description adds no additional meaning to the parameter, relying on the schema. Baseline 3 is appropriate.

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

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

The description clearly states 'List the caller's active subscriptions' with a specific verb and resource. It distinguishes from sibling tools like subscribe and unsubscribe by focusing on listing existing subscriptions and their details.

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

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

It provides clear usage context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This explicitly tells when to use the tool, though it doesn't explicitly name alternatives like 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?

The description adds substantial behavioral context beyond the annotations: it discloses rate limiting (5 per identifier per day), cost (free, no quota), the return of a claim_token for later look-up, and that the team reads digests daily and uses signals for roadmap. It also explains how to check resolution status. No contradiction with annotations exists; readOnlyHint=false aligns with this being a write-like action.

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

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

The description is a single dense paragraph with no filler. Every sentence contributes, but there is slight redundancy between the opening purpose statement and the subsequent 'Use when' enumeration. Still, it is well-structured and front-loaded with the core purpose.

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

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

Given the tool's moderate complexity (4 optional params, no output schema), the description is remarkably complete. It covers all use cases, exclusions, parameter usage, return token behavior, rate limits, and quota. Since there is no output schema, the description's detailed explanation of the claim_token workflow is especially valuable.

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

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

Schema coverage is 100% (all four parameters have descriptions), so the baseline is 3. The description adds meaningful extra semantics: it clarifies that claim_token is used to read a previous report's status, and it instructs users to describe issues in terms of Pipeworx tools/packs rather than pasting end-user prompts, which enriches the message parameter guidance.

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

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

The opening sentence clearly states the tool's function: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It uses a specific verb (tell) and resource (Pipeworx team), and the scope is unambiguous. This distinguishes it sharply from sibling tools, which are research/data operations.

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 when to use the tool ('Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise)') and provides a clear exclusion: it is only for tools served by this Pipeworx connection, and feedback about other MCP servers' tools should be filed elsewhere. It even suggests checking tool names if unsure.

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 the tool as read-only, idempotent, and non-destructive. The description adds valuable context: derived from CF analytics-engine, no PII, cached 5min-1h depending on window, and the self-aggregating nature. This goes beyond what annotations convey.

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

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

The description is composed of four dense but purposeful sentences: returns, use cases, data source/privacy, and caching. Every sentence earns its place and the structure is easy to scan. Slightly verbose but not wasteful.

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

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

For a simple tool with one optional parameter and no output schema, the description covers the return values, use cases, data provenance, privacy, and caching. The only gap is a precise output format, but it hints at (pack, tool, count). Overall very complete.

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

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

The single 'window' parameter is fully documented in the schema with an enum and description explaining short vs. long window trade-offs. The description repeats the window options without adding new parameter-level details, so it adds little 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 it returns top tools, top packs, and total call volume over a recent window, with a specific focus on what other AI agents are calling. This distinguishes it from sibling tools like discover_tools by emphasizing real-time trend aggregation rather than static discovery.

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

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

The 'Useful for' list provides concrete scenarios: discovering hot data sources, confirming canonical tools, and checking alignment with agent needs. This gives clear when-to-use context, though it doesn't explicitly name alternative tools or exclusions.

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

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

Annotations already indicate read-only, open-world, idempotent, and non-destructive. The description adds substantial behavioral context: scanning top ~200 markets, partition-filter placeholder rules, >3pp deviation signal threshold, similarity anchoring (Jaccard ≥0.30), and fill-check behavior with live CLOB depth. It even warns 'do not trade it' under specific conditions.

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

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

Although lengthy, the description is structured with clearly labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loaded with the core purpose. Every sentence contributes technical or usage detail, and the organization makes it 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?

Despite having no output schema, the description explicitly outlines the return structure: opportunities[] with gap_pp, suggested_trade, reasoning, and monotonicity context; partition_check fields; and fill-check results. Given the tool's complexity, the description covers all necessary context for correct invocation and interpretation.

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 vastly enriches the semantics. It provides concrete examples for event ('fed-decision-may-2026'), states that full URLs are accepted, explains topic mode with seed questions, and elaborates on what each parameter does in terms of scanning scope and output. The parameter meanings are far beyond the schema's short descriptions.

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

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

The description opens with a specific verb+resource+method: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes itself from siblings by referencing polymarket_fill_risk for custom sizing and detailing unique modes (event, topic, trending scan).

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 for each calling convention: 'Call with NO args for a trending_scan... pass event for... or topic for...' It also recommends event for specific markets, explains cross-event use cases, and tells users when not to trade (realizable_edge_pp ≤ 0). The alternative polymarket_fill_risk is named for sizing.

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

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

The description extensively discloses internal model families, output fields, limitations (e.g., unreliable Fed signal), caching behavior, and diagnostics, going far beyond the readOnlyHint and idempotentHint annotations. It explains what data is returned and how to interpret empty segments.

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

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

The description is extremely dense and runs as a single paragraph, which makes parsing difficult, but every sentence contains meaningful details about models, response structure, and limitations. It lacks structured formatting (e.g., bullets) despite its length, making it less concise than ideal.

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 the response structure, per-opportunity fields, diagnostics, and edge cases. It covers why certain segments might be empty and explains caching, making it complete for an agent to understand and invoke the tool.

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

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

While the input schema already has 100% parameter descriptions, the description adds semantic context about how knobs interact (e.g., min_partition_leg_kelly applies to per-leg Kelly because parent-level Kelly is zero) and explains tradeable-edge filters. This adds value 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 scans top Polymarket markets to find opportunities where Pipeworx data disagrees with market price, with a specific use case ('what should I bet on today'). This is a specific verb+resource+outcome and distinguishes from siblings like polymarket_arbitrage and polymarket_edge_tracker by focusing on top-market discovery.

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

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

The description provides clear context for when to use the tool (opportunity discovery without paging hundreds of markets) and describes configuration knobs for tradeability filters, but does not explicitly name alternative sibling tools or state when not to use it. The fed_candidates note also gives context about unreliable signals.

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 substantial behavioral context beyond the annotations (readOnly, openWorld, idempotent). It explains data collection (snapshots written on cache-miss, leading to gaps), TTL limits (60-day snapshot TTL), computation basis (daily closes, not intraday), and domain semantics (negative edge_pp_net means SELL YES). This goes far beyond what annotations convey and directly addresses real-world 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 detailed but efficiently structured: purpose, arguments, response semantics, and limitations are logically ordered and front-loaded. Each sentence carries distinct information—no filler. The length is justified by the tool's complexity and the absence of an output schema.

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 no output schema, the description fully explains the response shape (tracked[], expired[], snapshot_dates[]) and field meanings, including trend, decay, lifespan, and snapshot gaps. It also covers historical limitations (TTL, snapshotting enablement date). The description is complete enough for an agent to use the tool correctly without external knowledge.

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

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

Schema coverage is 100% (both parameters fully described), so baseline is 3. The description repeats defaults and clamps (days default 14/max 30; window default '1wk') but does not add substantial new meaning beyond the schema. It clarifies 'window family' but the schema already says 'window family'. No new semantics are introduced.

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: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It explicitly answers a concrete question—'how long has this edge existed and is it shrinking?'—which clearly distinguishes it from sibling tools like polymarket_edges (current edges) or polymarket_arbitrage (arbitrage opportunities).

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

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

The description provides clear context for when to use this tool: when you need to know edge persistence/decay rather than just the current edge. The contrast between 'fresh wide edge' and '3-week-old wide edge' subtly implies when this tool is the right choice. However, it does not explicitly name alternative tools or state when not to use it, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral detail: 'walks the ladder', returns a verdict (clean|degraded|cannot_fill), and warns that 'theoretical overround on thin books is not capturable'. This goes well beyond annotations and does not contradict them.

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

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

The description is long but tightly packed. It uses ALL-CAPS labels for modes and parameters, front-loads the core purpose, and every sentence conveys new information: defaults, return fields, risk warnings, usage timing. No redundant filler, and structure makes the two modes easy to parse.

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

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

With no output schema, the description enumerates return metrics for both modes: top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict; and for basket: theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg fill detail, thin_legs[], max_clean_notional_usd, forced_directional_risk. It also covers defaults and clamps, making it complete for a complex tool.

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

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

Schema coverage is 100%, but the description adds crucial mode-dependent meaning: size_usd is max spend on buys vs target proceeds on sells; in basket mode it's settlement notional (shares per leg). It also explains side defaults, auto-detection from partition sum, and the clamp range. This is far more than the bare schema descriptions.

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

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

The description opens with 'Realizable-vs-theoretical edge check against live CLOB order-book depth,' clearly specifying the verb (check) and resource (fill risk). It distinguishes single-market and basket modes, and the usage note contrasts it with polymarket_arbitrage and polymarket_edges, so purpose is unambiguous and differentiated.

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

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

Explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500' and explains the failure mode (partial fills convert an arb into an unhedged directional position). It also describes when to use each mode, making usage timing and alternatives clear.

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

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

Annotations declare readOnlyHint and non-destructive, and the description adds substantial behavioral detail: it explains compatibility_warning triggers, temporal_alignment semantics, and skipped_cross_type/subtype counters. This goes far beyond the annotations and provides clear visibility into edge cases without any 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?

Despite its length, the description is highly structured with clear sections: purpose, modes, response fields, and safety fields. Every sentence provides essential information and there is no filler or redundant restatement of schema fields. It is appropriate 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 comprehensively: raw probabilities, top_spreads_pp, compatibility_warning cases, temporal_alignment, and skipped counters. It also addresses limitations and practical tradeability, making the description complete for an AI agent to select and call 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 already covers all three parameters with descriptions and examples (100% coverage). The description adds meaningful semantics beyond the schema by explaining mode interplay and that explicit ticker/slug overrides the topic-mapped side, which is not in the schema. This elevates it above the baseline, though additional param-level examples are already present.

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 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' clearly stating the verb (spread comparison) and resource (two venues). It distinguishes itself from sibling tools by emphasizing cross-venue comparison rather than single-venue arbitrage or edge detection.

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

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

The description explicitly explains two modes (topic shortcuts vs explicit ticker/slug overrides) and when each is appropriate, including precedence rules. It also warns that pre-mapped topics often return compatibility_warning and that 'pre-mapped ≠ tradeable,' setting usage expectations. It does not explicitly name alternative tools for when-not-to-use, so it stops short of a 5.

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

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

The annotations declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful context about scoping ('Scoped to your identifier (anonymous IP, BYO key hash, or account ID)') and the behavior when the key is omitted ('list all saved keys'). This goes 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?

Three sentences, beginning with the primary action. Sentence 2 explains usage context, sentence 3 covers scoping and relationships. No filler words; each clause 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?

The tool is simple (one optional param, no output schema), and the description covers purpose, how to invoke both modes, scoping, and complementary tools. It doesn't specify the return format or error handling, but these are not critical for a basic retrieval tool. Overall, it's 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 coverage is 100%, with the schema already describing the key parameter. The description restates the omit-to-list behavior but also provides context about what the keys represent (target ticker, address, notes). This adds some semantic flavor but not new parameter syntax or constraints, so it lands at 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 states 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument)' — a specific verb and resource. It distinguishes the tool by referencing sibling operations (remember, forget) and providing concrete use cases like 'user's target ticker, an address, prior 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?

The description explicitly tells when to use the tool: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also mentions pairing with remember and forget, giving a clear workflow. It lacks an explicit 'when not to use' or alternative tool names, so it's 4 not 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 and idempotentHint, but the description adds the important side-effect that mark_read:true mutates state. It also explains the return payload structure (source, citation_uri, raw event payload), which is essential because there is no output schema.

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

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

The description is three sentences, front-loaded with the main action, and every sentence adds functional value—return payload, filtering, polling, and alternative access. There is no wasted 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?

With no output schema, the description covers the key return fields, polling behavior, and mark_read side-effect. It doesn't repeat the schema's parameter descriptions for limit and unread_only, and the external URL adds useful integration context. It's complete enough for a read-only feed tool.

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

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

Schema coverage is 100%, but the description adds valuable meaning: it gives an example type ('sec_8k'), clarifies the effect of mark_read on subsequent calls, and reinforces the ISO timestamp format for 'since'. This goes beyond the schema's parameter 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 a specific verb 'Pull fired events' and clearly identifies the resource as the subscription feed. It distinguishes itself from siblings like list_subscriptions or recent_changes by explicitly mentioning 'fired events' and 'evaluator has written', making it clear this is about reading alert events.

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: 'Polls work fine' and gives an alternative access method via the GET URL for scripts and dashboards. It doesn't explicitly name sibling tools to avoid, but the context makes it clear this is the tool for reading subscription alerts.

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 detailed internal behavior: it fans out to SEC EDGAR, GDELT→GNews fallback, and USPTO (with a soft-fail note about the PatentsView API sunset). It specifies the fallback logic (GDELT preferred, GNews on rate-limit/5xx) and the return structure, which is far more than annotations alone provide.

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

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

The description is front-loaded with intuitive examples, then provides a concise definition, source details, return format, and alternative tool reference. Every sentence contributes new information without redundancy, making it efficient despite its length.

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

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

Since there is no output schema, the description fully explains the return value (structured changes[] grouped by source, total_changes count, citation URIs). It also covers edge cases like the USPTO soft-fail and fallback logic, ensuring the agent understands the tool's behavior in all circumstances.

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

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

The schema already covers all parameters with high coverage (100%), so the baseline is 3. The description adds value by clarifying accepted formats for `since` with examples ('7d', '30d', '3m', '1y') and recommending '30d' or '1m' for typical monitoring, which goes beyond the schema 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: a change feed for a company over a specified time window, with examples of natural language queries that map to it. It explicitly distinguishes itself from the sibling tool entity_profile, which provides static profiles.

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 context through example queries like 'What's new with X' and directly names an alternative tool ('Use entity_profile instead') for static profiles. It also explains the source fan-out and fallback behavior, making it clear when to invoke this tool.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints. The description adds meaningful context by specifying the return format (JSON), pagination support, and ODSQL capabilities. This goes beyond what annotations provide without contradicting them.

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

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

A single, well-structured sentence that front-loads the core purpose and uses every phrase to add value. No fluff or repetition of schema details.

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 key behavioral aspects (keywords, ODSQL, pagination, projection, return format) for a moderately complex tool with 9 parameters. An output schema exists, so return details are not needed. Minor gaps like default pagination limits are omitted, but the description is complete enough 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?

With 0% schema description coverage, the description compensates by mapping most parameters: q (keyword search), where/select/group_by/order_by (ODSQL clauses), limit/offset (pagination), and projection (select). It misses dataset_id and instance, but these are self-evident or niche; overall it gives significant semantic meaning to 7 of 9 params.

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

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

The description uses a specific verb ('Query') and resource ('records from an Opendatasoft dataset'), clearly distinguishing it from siblings like 'dataset' and 'datasets' which likely handle dataset metadata. It lists concrete capabilities (ODSQL clauses, pagination, projection) beyond a generic statement.

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

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

The description clearly indicates the tool is for querying records from datasets, with explicit references to ODSQL, pagination, and projection. It does not provide explicit exclusions or name alternatives, but the context makes it obvious when to use this tool versus sibling metadata/facet tools.

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

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

Annotations already indicate idempotency and non-destructiveness. The description adds valuable context by explaining memory scoping per user identifier and the persistence difference for authenticated vs anonymous sessions. It does not contradict any annotations, and the added details go beyond what the annotations alone convey.

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

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

The description is three sentences, front-loaded with the primary action, followed by usage context and storage details. Every sentence contributes new information without repetition, making it highly efficient.

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 simplicity of the tool and rich schema/annotations, the description covers purpose, usage timing, persistence behavior, and interaction with sibling tools. It omits the return format, but this is a minor gap for a simple storage operation, and overall it provides sufficient context to use 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 enriches parameter understanding by providing concrete examples of valid keys (e.g., 'resolved ticker', 'target address') and clarifying that values are arbitrary text. This goes beyond the schema's generic descriptions and helps the agent format parameters correctly.

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: 'Save data the agent will need to reuse later' with a specific resource and verb. It differentiates from siblings by explicitly mentioning 'recall' and 'forget' as complementary tools, making its role in the memory system distinct.

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 on when to use: 'Use when you discover something worth carrying forward... so you don't have to look it up again.' It also gives examples of appropriate content (ticker, address, preference) and names alternatives (recall, forget), fulfilling the when/when-not requirement.

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

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

Beyond the read-only/idempotent annotations, the description adds meaningful behavioral details: graceful degradation of LEI/FIGI enrichment if external sources are unavailable, explicit inclusion of unresolved identifiers under `unresolved`, and the internal cascade across multiple lookup endpoints. These details help the agent anticipate edge cases and interpret results correctly.

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 serves a purpose: opening examples, core mission, supported types with details, degradation behavior, and the note about replacing manual lookups. Information is front-loaded with the purpose statement, and no word is wasted. For a tool with this complexity, the length is justified.

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

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

Since there is no output schema, the description carries the full burden of explaining returns. It specifies what identifiers are resolved, which sources they come from, how unresolved items are reported, and degradation behavior. It also provides usage context (when to use) and input formats. This is complete 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 already provides 100% coverage for both parameters (type enumerations and value formats), including examples. The description repeats this information without adding new input semantics. It does add output context (e.g., what identifiers are returned) but that does not contribute to parameter understanding, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It provides specific example queries and distinguishes itself from sibling tools by emphasizing this is the first tool to use when a name needs an ID. Supported types and their specific identifier outputs (e.g., CIK, ticker, LEI, RxCUI) further clarify scope.

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 directs usage: 'Use FIRST whenever you have a name but need an ID.' It also illustrates with concrete example queries. However, it does not mention when not to use this tool or name alternative tools (e.g., entity_profile) for richer entity data, so it lacks the 'when-not' exclusion.

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, and non-destructive. The description adds valuable process detail: probes each entity with ai_visibility_check, ranks by score, and surfaces most/least recognized. It also discloses the return format (ranked list with score, confidence, signal density), going beyond annotations without contradicting them.

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

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

The description is three sentences, front-loaded with the core purpose, and every sentence adds value—use case, method, and output. No filler or repetition of schema 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?

Despite having no output schema, the description explicitly states the return structure (ranked list with score, confidence, signal density per entity). It covers the tool's functionality, use case, and relationship to ai_visibility_check, making it self-sufficient for a complex tool with multiple 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?

Schema coverage is 100%, so the schema already documents all parameters clearly. The description does not add significant parameter-level detail beyond what the schema provides, but it reinforces the concept of 'your brand + N competitors' in the context of entities.

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: 'Compare AI visibility across multiple entities side-by-side.' It clearly distinguishes from sibling tools like ai_visibility_check (single entity) 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?

Provides a clear use case: 'Useful for competitive AI-marketing audits' and an example query ('does Claude know about us as well as our competitors?'). It implies using this instead of ai_visibility_check when comparing multiple entities, but does not explicitly state 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?

Beyond the read-only/idempotent annotations, the description discloses fan-out behavior, latency (bundlephobia's first measurement can take 5-30s), graceful degradation with sources_failed, and the composite nature. No contradiction with annotations.

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

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

The description is front-loaded with purpose, then covers usage, return structure, ecosystem scope, and failure handling in a dense but organized way. Each sentence earns its place for a composite tool.

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

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

Despite lacking an output schema, the description thoroughly enumerates the return block fields (is_latest, license, etc.), advisory details, links, and recent versions. It also covers failure modes, latency, and ecosystem limitations, making it complete for a tool of this complexity.

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

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

Schema description coverage is 100% for both parameters (package and version), so the schema fully documents them. The description adds little parameter-specific semantics beyond mentioning version history and alternative versions, which are tangential. Baseline 3 is appropriate since the schema carries the 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 states the tool's purpose: a composite npm package evaluation checking safety, size, and details via deps.dev and bundlephobia. It uses a specific verb ('scan') and resource ('npm package'), and uniquely positions itself among siblings as the npm-specific package scanner.

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 usage guidance is provided: 'Use whenever an agent asks is X safe / popular / small...' It also gives exclusion criteria: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly,' naming an alternative for non-npm ecosystems.

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?

Despite annotations already covering read-only, open-world, and idempotent behaviors, the description adds concrete technical details: BGE-base-en embeddings, cosine similarity over 500-char overlapping windows, a 200K character cap with truncation and flagging, and that results include character offsets and similarity scores. This goes well beyond the annotation 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?

Three sentences, with the first sentence front-loading the purpose. The second gives usage context, and the third packs technical behavioral details. No filler or redundant phrases; 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?

Since there is no output schema, the description explains the return format (top-N passages with character offsets and similarity scores) and the truncation behavior under the 200K cap. It also covers the use case, relationship to a sibling tool, and implementation details, making it complete for a moderately complex search utility.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds example text types (SEC 10-K, article) and query examples ('supply-chain risk'), but does not materially change or extend the technical meaning of the parameters beyond the schema. The 'top-N' mention for limit is generic and not as precise as the schema's 1-20/default 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 'Semantic search INSIDE a fetched record,' which is a specific verb+resource statement. It clearly distinguishes this tool from siblings by explicitly pairing it with ask_pipeworx_grounded and explaining its role as a context-saving search over a specific text.

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

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

Provides explicit when-to-use guidance: 'Use when the record is too big to cram into the prompt.' It also describes an alternative workflow with ask_pipeworx_grounded, telling the agent to ground over relevant passages instead of the whole document, thus covering both when and how it fits relative to other tools.

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

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

The description adds substantial behavioral context beyond annotations: auth requirement, return value, delivery channel behavior (feed always on, SMS verification and 10/day cap), and inability for anonymous users to persist subscriptions. This complements the annotations (readOnlyHint=false, openWorldHint=true, etc.) without contradiction.

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

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

The description is dense but well-organized using colons and examples. However, it is somewhat long and includes details that partly duplicate schema descriptions. Every sentence earns its place, but it could be slightly tighter without losing clarity.

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 no output schema, the description does a good job explaining return values, auth, and main types. But it misses two enum types (patent_grant, clinical_trial) and the webhook delivery channel, leaving gaps that force the agent to rely solely on the schema. These omissions prevent full completeness.

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 has 100% coverage, the description is misleading by listing only three types (sec_8k, polymarket_edge, fred_series) after 'Supported types:' when the schema enum includes patent_grant and clinical_trial. Similarly, the delivery channels section omits webhook, which is part of the schema. This misrepresentation reduces value beyond schema.

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

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

The description clearly states the tool's purpose with a specific verb and resource: 'Create a proactive monitoring subscription to a live-data event stream.' It also mentions the return value (subscription id), distinguishing it from sibling tools like list_subscriptions and unsubscribe.

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

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

Provides clear context for when to use the tool: creating proactive monitoring vs. pulling data via recent_alerts. It also states prerequisites (Pipeworx OAuth account) and constraints (anonymous/BYO cannot persist). However, it does not explicitly name alternative tools or exclude scenarios, stopping 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 mark this as read-only, open-world, idempotent, and non-destructive. The description adds behavioral detail about returning category-bucketed examples with exact tool and argument shapes, and that results are drawn from the live catalog of thousands of tools. This goes beyond the annotations without contradicting them.

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

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

The description is a single paragraph that front-loads user intent examples before diving into return details and usage. It contains some redundancy in the opening question synonyms but remains compact and well-organized for an onboarding tool.

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

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

Given the simple one-parameter schema and no output schema, the description fully covers purpose, behavior, return contents, parameter usage, and when to invoke. It provides enough context for an agent to select and use the tool without confusion.

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

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

The schema already documents the optional `topic` parameter with allowed values. The description adds practical examples ('finance', 'pharma', 'betting') and clarifies behavior when omitted, reinforcing the schema's coverage. This is helpful beyond the raw 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 an 'onboarding entry point' that returns category-bucketed example questions with exact tool and argument shapes. It distinguishes itself from siblings by explicitly positioning itself as the first tool to use when the agent doesn't know what Pipeworx can do.

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 usage context: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also explains when to omit or pass the topic parameter. It does not mention alternatives or 'when not to use,' but the guidance is clear.

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

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

Beyond annotations (idempotent, non-destructive), the description discloses ownership enforcement, deactivation instead of deletion, and that historical events remain accessible via recent_alerts. This adds valuable behavioral context not present in the annotations.

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

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

Two front-loaded sentences, each providing essential information: the core action, ownership caveat, and post-cancellation behavior. No redundant or filler content.

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

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

For a simple one-parameter mutation tool with no output schema, the description covers the action, side effects, ownership rules, and downstream impact (recent_alerts). It is fully sufficient for an agent to understand 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 already fully documents the single parameter (id) with a clear description ('Subscription id (uuid) returned by subscribe'). The description does not add new parameter-specific details, so the baseline 3 applies given 100% 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 uses a specific verb ('Cancel') and resource ('subscription by id'), clearly stating its function. It also distinguishes itself by noting ownership enforcement and deactivation behavior, differentiating it from sibling tools like subscribe and list_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 context is clear: this is for canceling subscriptions, and ownership restrictions are explained. It does not explicitly mention alternatives or when-not-to-use, but the purpose is unambiguous and the deactivation detail ties into recent_alerts, providing useful context.

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 substantial behavioral context beyond the annotations: it explains the internal routing (SEC EDGAR + XBRL fast path vs. grounded pipeline), enumerates all possible verdicts, and crucially clarifies the differenve between 'could_not_verify' (check did not happen, no evidence) and 'unsupported' (no source exists). This is exactly the kind of nuance that helps an agent reason about results. It fully aligns with the read-only, idempotent annotations.

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

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

The description is front-loaded with natural-language triggers and usage intent, then covers routing, return values, and error semantics in a structured way. It is fairly long but each sentence adds information; the 'Replaces 4–6 sequential calls' line is useful but somewhat redundant with the overall efficiency angle. Could be lightly trimmed without losing value.

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

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

With no output schema, the description carries the full burden of explaining return values and does so completely: it lists the verdict enum, the actual value with citation, reasoning, and a detailed explanation of the error/edge-case verdicts. It also covers routing behavior and the types of claims supported, making it comprehensive enough for an agent to invoke the tool and interpret the result 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?

With 100% schema description coverage, the baseline is 3, and the description does not meaningfully add to the parameter semantics already in the schema. The mention of 'exact percent-delta math' and tolerance-related context is echoed in the schema's tolerance_pct description, so the description adds little beyond what the structured schema provides.

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

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

The description clearly states the tool's purpose: natural-language claim verification against authoritative sources, with explicit example phrasings like 'fact check' and 'verify the claim that…'. It distinguishes the tool from general Q&A and research tools by focusing on fact-checking, but it does not explicitly name sibling tools as alternatives, so it falls short of a 5.

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

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

The description gives clear guidance on when to use the tool ('Use whenever the agent needs to check whether something a user said is factually correct.') and explains different handling for company-financial claims vs. other factual claims. However, it does not explicitly mention when not to use it or name alternative sibling tools, so it stops short of a 5.

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