Data Europa

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

Annotations already declare the tool as read-only, open-world, idempotent, and non-destructive. The description adds valuable behavioral context beyond these: billing implications of providing an API key (BYO key, pay Anthropic directly), the default model used, and the exact return structure ({score, confidence, signals, raw_response} + combined view).

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

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

The description is four concise, front-loaded sentences with no redundancy. Each sentence earns its place: function, model defaults/cost, return structure, and use cases. The format is scannable and 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?

Despite lacking an output schema, the description fully specifies the response structure, parameter behavior, and use cases. For a 4-parameter read-only tool with robust annotations, the description covers all essential context an agent needs to select and invoke it correctly.

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

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

With 100% schema coverage, each parameter is already well-described. The description goes further by clarifying the relationship between models and _apiKey (pass _apiKey to also probe Anthropic) and specifying the free default model, adding practical semantics not present in the schema alone.

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

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

The description uses the specific verb 'Probe' and identifies the resource (LLMs), clearly stating the output (visibility score 0-100 per model). It distinguishes itself from siblings like ask_pipeworx or scan_competitor_ai_presence by focusing on LLM knowledge scoring rather than answer generation or competitor 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 description provides explicit use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains model selection (default Workers AI vs BYO Anthropic with cost implications). It does not explicitly name alternative tools or state when not to use this tool, so it falls short of a 5.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds valuable context: it returns structured answers with citation URIs, routes across a large tool ecosystem, fills arguments automatically, and is a 'one fast call' entry point. 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 long but well-structured: it front-loads the most important direction ('PREFER OVER WEB SEARCH'), then covers domains, behavior, examples, and alternatives in a logical flow. Every sentence earns its place, though a slightly tighter structure could improve scannability.

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 its complexity (routing across thousands of sources, multiple domains, alternative tools), the description is remarkably complete. It addresses purpose, when to use, examples, output format (structured answer with citations), and escalation paths. The absence of an output schema is compensated by describing what the response contains.

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

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

The input schema provides 100% coverage for all 6 parameters (all aliases of 'question') with clear descriptions. The description adds usage examples and trigger phrases, but no deeper parameter semantics beyond what the schema already provides, so the baseline 3 applies.

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

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

The description uses a specific verb+resource: 'Routes the question to the right one of 5,529 tools across 1455 verified sources' and 'returns the structured answer with stable pipeworx:// citation URIs.' It clearly distinguishes itself from siblings by naming ask_pipeworx_grounded and deep_research as alternatives, making its purpose unambiguous.

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

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

The description gives explicit when-to-use guidance: 'PREFER OVER WEB SEARCH' for a broad list of domains, 'START HERE for most questions', and 'Step up only when needed' with specific escalation paths to ask_pipeworx_grounded and deep_research. It also includes trigger phrases and examples, which is exemplary usage guidance.

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

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

Beyond the read-only, idempotent annotations, the description adds key behavioral context: it is a full working router with no fallback stub, no candidate is currently active, and it matches ask_pipeworx exactly. Also notes the experimental nature and comparison against the stable version.

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 bit longer than minimal, but each sentence carries distinct value: definition, current state, usage, and clarification. It is front-loaded with the core purpose and avoids repetition. Slightly wordy but efficient overall.

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 complexity of a universal router with thousands of tools, the description is remarkably complete. It addresses identity, current behavior (identical to stable), candidate testing, comparison logic, and the fact that it is fully functional. The lack of output schema is mitigated by referencing the same response shape as ask_pipeworx.

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 100% of parameters, listing question and its aliases. The description does not add parameter-specific details beyond saying 'same arguments' as ask_pipeworx, which is already captured in 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 this is the beta version of ask_pipeworx, an identical universal router with the same 5,529 tools, arguments, and response shape. It distinguishes itself from siblings by being the experimental edge and noting it currently matches ask_pipeworx exactly.

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 it exactly like ask_pipeworx when you want the newest routing' and clarifies results are compared against the stable router to decide merges. This gives clear when-to-use guidance and implies when not to use (when needing stable behavior).

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

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

Annotations already indicate read-only, idempotent, open-world, and non-destructive behavior. The description goes well beyond by disclosing the exact return payload (answer, evidence, confidence, etc.), refusal reasons, the extra LLM call cost, and the 'using ONLY what the tool result contains' constraint. No contradictions.

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

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

The description is dense but every sentence carries unique value: what it does, how it works, return schema, refusal conditions, use cases, and cost trade-off. It front-loads the core purpose and remains efficient without redundancy.

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

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

There is no output schema, so the description must explain return values; it does so exhaustively, including the refusal_reason enum. It also covers routing complexity (5,529 tools, 1455 sources) and the trade-off vs the sibling tool, making it complete for an agent to decide 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% (all six parameters are aliases for 'question' and documented). The description adds no parameter-specific meaning beyond saying it 'fills arguments' during routing, which is already implied. Baseline 3 applies because the schema fully covers parameters.

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 concrete purpose: 'Hallucination-resistant answer mode for high-stakes reads.' It clearly distinguishes itself from the sibling 'ask_pipeworx' by explaining that it extracts answers using only tool results and returns evidence. This is a specific verb+resource with explicit differentiation.

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

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

Provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on...' and explicitly names the alternative for casual lookups: 'prefer ask_pipeworx for casual lookups.' This is textbook usage guidance with a direct sibling comparison.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description goes well beyond them by disclosing classification behavior, fan-out specifics, response shapes, resolver confidence mechanics, low-confidence short-circuiting, closed-market handling, wide-spread flags, and cancellation-rule risk. This is rich, non-redundant transparency.

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

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

The description is well-structured with labeled sections and front-loaded purpose/usage. It is quite lengthy (~400 words) but each sentence contributes operational detail, such as resolver contracts and safety mechanisms. It earns high marks for organization but loses a point for verbosity that could be trimmed.

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

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

With no output schema, the description fully carries the burden of explaining return values, and it does so comprehensively: result.market, result.analysis, result.evidence, resolver contract with match_confidence and alternatives, parent_event extractor, news backfill fields, and resolution-rule risk. It also covers blocking statuses and safety behavior, making it complete for agent 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?

The input schema has 100% description coverage with detailed parameter docs (e.g., depth enum, market format, include_raw size implications). The tool description restates the market input formats but does not add significant new parameter-level semantics beyond what the schema already provides; fan-out examples reference the 'thorough' behavior without explicitly mapping to the depth 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 opens with a specific verb and resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly scopes the tool to Polymarket bet research and enumerates accepted input forms (slug, URL, question text). It also distinguishes itself from sibling tools by naming concrete use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z').

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 'Use for' with three common phrasings, giving clear context for when to invoke this tool. It does not provide explicit 'when not to use' or name alternative sibling tools, but the use cases and detailed fan-out logic imply a strong fit for Polymarket-specific research tasks.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds substantial behavior details beyond these: pulls latest 10-K data from SEC EDGAR/XBRL, handles off-calendar fiscal years, sorts by primary metric, returns paired data with pipeworx:// citation URIs, and notes the parallel call optimization. This is rich, non-redundant context.

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

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

The description is longer than typical but every sentence contributes value—trigger examples, core function, type details, and output behavior are all relevant. It is front-loaded with user-intent phrases and structured logically. While somewhat dense, it earns its length given 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?

For a tool with no output schema and moderate complexity, the description covers key contextual aspects: data sources, edge cases (off-calendar fiscal years), result sorting, output format (paired data + citation URIs), and the performance benefit. It could elaborate on potential error scenarios or exact return structure, but for a comparison tool this is sufficiently complete.

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

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

Schema coverage is 100% for both parameters, so the baseline is 3. The description adds meaning beyond the schema by clarifying what each type ('company' vs 'drug') retrieves, the expected format of values (tickers/CIKs vs drug names), and the sorting behavior. This enhances the agent's understanding of parameter usage beyond the schema's simple descriptions.

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

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

The description clearly defines the tool's purpose: 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' It provides specific trigger phrases ('X vs Y', 'rank these companies') and distinguishes itself from sequential lookups by stating it replaces 8–15 sequential calls, differentiating it from sibling tools like entity_profile.

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

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

The description explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' providing clear when-to-use guidance. It also explains the two type-specific behaviors (company vs drug). However, it does not name a specific alternative tool or explicitly state when not to use it beyond the comparison context, so a small gap remains.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, but the description adds substantial context beyond these: account/auth requirements, paid plan for thorough depth, parallel routing to 5,529 tools, return packet structure, gaps[] behavior (never invented), contradictions[] for certain depths, semantic excerpting, citation_uri fetchability, and time expectations. There is no contradiction with the annotations.

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

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

The description is long but information-dense, with each sentence contributing unique value (account requirements, alternatives, behavior, return format, timing). It is reasonably front-loaded with the account prerequisite and closely follows a logical flow from prerequisites to usage to details. A small deduction for verbosity, but the complexity of the tool justifies most of the 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?

With no output schema, the description fully explains return values: findings packet with verbatim evidence, confidence, source, fetched_at, citation, gaps[], contradictions[], hop field, and semantics of citation_uri. It also covers timing, account tiers, and clear usage exclusions, making the description complete for an agent to invoke and interpret results.

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

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

Although schema coverage is 100%, the description enriches parameter meaning significantly. For 'question', it states 'Broad/multi-part is fine — decomposition is the point.' For 'depth', it details the behavioral differences between quick, standard, and thorough (e.g., gap recovery vs. lead chasing, paid tier), plus the default, making the enum values more actionable than the schema alone.

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

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

The description clearly states the tool's function: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' in one call, and explicitly distinguishes it from open-web search and sibling tools like ask_pipeworx. It provides a specific verb+resource+scope and differentiates usage from alternatives, making the purpose unambiguous.

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

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

The description offers explicit guidance on when to use the tool ('Best for broad/multi-part questions over structured data') and when not to ('For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'). It also identifies alternatives by name, including the fallback for users without an account, giving the agent clear decision rules.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds valuable behavioral context beyond these: it returns top-N most relevant tools with names, descriptions, and full input schemas (with curated examples), and each result is ready to call directly without a second schema lookup. It also notes that the tool is meta (returns tool schemas), which is not captured in annotations. The only gap is no mention of behavior when no matches are found or rate limits, but given annotation coverage, a 4 is appropriate.

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

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

The description is front-loaded with the core purpose in the first sentence, followed by usage guidance and output details. The domain list is long but purposeful—it tells the agent what kinds of data/tasks are discoverable. Every sentence contributes: purpose, when to use, what it returns, and a strong directive to call it first. The length is justified for a meta-tool that needs to communicate breadth, though it could be slightly tightened.

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 discovery tool, the description is complete: it explains input (natural language query), output (top-N tools with schemas), and usage context (call first, no second lookup). The rich annotations (readOnly, idempotent) and full parameter schema cover the rest. No output schema exists, but the description explicitly describes the return format. Minor omissions like relevance criteria or error behavior are not critical for this tool's 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 100%, with each parameter (query, q, task, search, description, limit) having a description and examples. The description adds general context about 'describing the data or task' and mentions 'top-N' (which maps to limit), but it doesn't provide details beyond the schema. Since the schema already documents aliases and default/max for limit, the description adds marginal value. 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 the tool's function with a specific verb and resource: 'Find tools by describing the data or task.' It goes further to enumerate the domains it covers (SEC filings, financials, FDA drugs, etc.), which distinguishes it from sibling tools like 'search' or 'search_within' by positioning it as a meta-tool for discovering other tools. The phrase 'Call this FIRST' also strongly differentiates it from direct-answer tools.

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

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

The description provides explicit when-to-use guidance: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It implies a clear exclusion—when you already know the specific tool or just need one answer, this is not the tool. It also contrasts with 'not just one answer,' guiding the agent toward direct tools for single-answer queries.

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

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

Annotations cover readOnly, idempotent, and non-destructive. The description adds substantial context: parallel fan-out across multiple sources, patents API sunset with soft-fail, GDELT→GNews fallback, and the specific data fields returned. This goes well beyond what annotations provide, and there is no contradiction.

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

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

The description is long but information-dense. It opens with natural-language examples to quickly convey purpose, then details return data, and closes with input constraints. While not as lean as two-sentence descriptions, every clause adds actionable information; minor redundancy exists in the examples, but overall it is 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 no output schema, the description explains the full shape of the return: list of fields (cik, filings, fundamentals, patents, news, LEI) with formats and URIs. It also covers edge cases (patents sunset, fallback, name unsupported) and points to resolve_entity for names. This is comprehensive 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?

The schema already documents both parameters (type and value) with descriptions. The description adds meaningful examples for ticker and CIK, the requirement for zero-padded CIK, and explicitly states names are not supported, which supplements the schema's generic 'Ticker or CIK' 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 explicitly states the tool's function: 'full cross-source profile of a US public company in ONE parallel call' with a specific verb ('profile', 'research', 'brief') and resource (US public company). It also distinguishes itself from sibling tools by directly saying 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' and by referencing resolve_entity for handle names.

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?

Clear when-to-use guidance: use when the user asks for a holistic view or a rundown. Explicitly excludes names as input and directs users to 'use resolve_entity first if you only have a name'. The alternative of chaining lookups is explicitly discouraged.

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 destructiveHint=true and idempotentHint=true, covering the destructive and idempotent nature. The description adds context about 'previously stored' and 'sensitive data', but does not go beyond annotations to describe side effects or error behavior. No contradiction found.

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

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

The description is two sentences, front-loaded with the action, includes usage guidance, and mentions sibling tools. Every sentence serves a purpose with no filler or redundancy.

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

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

For a simple single-parameter destructive tool with annotations covering idempotency and destructiveness, this description is complete. It tells the agent what the tool does, when to use it, and how it relates to remember and recall, without needing to explain return values (no output schema).

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

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

The schema fully describes the single 'key' parameter with 'Memory key to delete' (100% coverage). The description reinforces that deletion happens 'by key' but adds little new meaning beyond the schema, so 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 'Delete a previously stored memory by key', using a specific verb and resource. It effectively distinguishes itself from sibling tools like remember and recall by naming them as complements.

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 scenarios: 'context is stale, the task is done, or you want to clear sensitive data'. It also names remember and recall as associated tools, but lacks explicit when-not-to-use guidance or direct comparison to alternatives.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints. The description adds process context—fetches the page, extracts title/description/links, emits markdown—and frames the output as a text blob. This goes beyond the annotations without contradicting them, though it omits details like rate limits or potential fetch failures.

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

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

The description is compact and front-loaded, with the core purpose in the first sentence. It efficiently delivers the workflow, output format, and use cases in just a few sentences, with no redundant or filler content.

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

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

Given the tool's simplicity (2 params, full schema coverage, rich annotations, no output schema), the description covers the essential aspects: what it does, how it works, what it returns, and when to use it. It is sufficiently 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 input schema already provides 100% coverage for both parameters (url and max_links), so the description need not repeat them. The description does not add extra semantic detail beyond what the schema states, 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: generating a production-ready llms.txt file for any URL. It names the specific resource (llms.txt), the verb (generate), and the overall goal (helping AI crawlers index the site), making it distinct from sibling tools like ai_visibility_check or scan_competitor_ai_presence.

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

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

The description provides three explicit use cases (client sites, own projects, auditing competitors), giving clear context for when this tool is appropriate. However, it does not name alternative tools or explicitly state when not to use it, stopping 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 that it returns names and IDs for filtering, but does not explain pagination or the limit parameter. No contradiction.

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

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

Single sentence, front-loaded with the main action, and no unnecessary words. Every part earns its place.

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

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

For a simple list endpoint with one optional parameter and good annotations, the description gives sufficient context on purpose and output, though the limit parameter is left unexplained.

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 description does not mention the 'limit' parameter, and the schema has no descriptions. With 0% schema coverage, the description should explain the parameter but doesn't, so the agent only has the parameter name and example to infer meaning.

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

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

The description clearly states the tool lists thematic dataset categories on the EU open-data portal, with examples (environment, transport, economy) and the output (names and IDs). This distinguishes it from sibling tools like organizations and tags.

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 indicates the returned data is for use as filters in search, implying the tool is used to get category options for search filtering. It does not explicitly mention alternatives or when-not to use, but the context is clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the burden on the description is lower. The description adds valuable context about scoping ('caller's active subscriptions') and the exact data returned, though it doesn't mention the include_inactive parameter behavior beyond the schema default.

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

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

Two sentences, zero wasted words. The first sentence states what it does and what it returns; the second gives usage context. It is well-structured and front-loaded with the core action.

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

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

The tool is simple (one optional parameter), has rich annotations, and the description lists all return fields (compensating for lack of output schema). It fully covers what an agent needs to know to invoke 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?

Schema coverage is 100% with include_inactive having a clear description. The tool description adds minimal parameter-specific meaning beyond implying the default is active-only ('active subscriptions'), which aligns with the schema's 'default false'. 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 a specific action ('List') and resource ('the caller's active subscriptions'), and enumerates the return fields (id, type, params, created_at, last_fired_at, fire_count). This distinguishes it from sibling tools like subscribe/unsubscribe and makes its function unambiguous.

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

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

The second sentence provides explicit guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This tells the agent when to call this tool and gives context for alternatives (subscribing/unsubscribing), fulfilling the usage guideline 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?

Annotations already declare the tool read-only, idempotent, and non-destructive. The description adds useful behavioral context about pagination (default 100, max 1000) and the return fields (names, dataset counts), which 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?

The description is a single sentence that front-loads the main purpose and follows with parameter semantics. No wasted words, every part 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?

Given the tool's simplicity (one optional parameter), the rich annotations, and the presence of an output schema, the description provides all necessary context for an agent to select and invoke the tool correctly. It covers purpose, parameter behavior, and expected output content.

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

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

The schema provides only the type 'number' for 'limit', so schema coverage is 0%. The description fully compensates by explaining that limit controls page size with default 100 and max 1000, adding critical meaning 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 states the tool lists EU open-data portal publishing organizations with names and dataset counts, which is specific and distinguishes from sibling tools like 'groups' or 'search'. The verb 'List' plus resource scope makes the purpose unambiguous.

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

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

The description gives clear context for when to use (listing EU organizations) and details on the limit parameter, but does not explicitly mention alternatives or exclusions. The usage is implied but not fully contrasted with similar tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds scope (EU open-data) and return fields but no additional behavioral traits like rate limits or error behavior. This is useful but not rich behavioral context.

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

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

Single sentence, front-loaded with the action and resource, then details the return content. No redundant words; every phrase 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 parameter, comprehensive annotations, and an output schema. The description covers the essential purpose, target, and return fields, making it 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?

The schema has only 'id' with no description (0% coverage). The description defines it as 'portal ID' and provides the context 'EU open-data dataset record', giving semantic meaning beyond the schema. The schema example further clarifies the expected format, so the parameter is well explained.

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

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

The description clearly states a specific verb ('Fetch'), a specific resource ('single EU open-data dataset record'), and the identifier ('portal ID'). It also lists the returned metadata fields, making it distinct from sibling tools like 'search' or 'groups'.

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

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

The description implies usage: use when you have a known portal ID and need a single record's full metadata. It doesn't explicitly name alternatives or exclusions, but the 'single' and 'by its portal ID' phrasing contrasts clearly with discovery-oriented sibling tools.

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

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

Description discloses rate-limiting ('Rate-limited to 5 per identifier per day'), the claim_token mechanism for follow-up, that it's free and doesn't count against quota. These go beyond the annotations (all false), enriching the behavioral profile.

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

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

Description is front-loaded with core purpose, then systematically covers when, exclusions, and operational details. Each sentence serves a distinct function with no redundancy. Length is justified by 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?

Covers what the tool does, when to use, exclusions, content guidelines, return token behavior, team reading schedule, and rate limits. Even without an output schema, it adequately explains the key return value (claim_token).

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 schema covers all four parameters (100%), the description adds usage nuance: guidance not to paste end-user prompts in the message, and instructions for claim_token usage ('pass the pwfb_… token that filing returned, with no other arguments'). It doesn't enumerate context fields, but those are well-specified 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?

Description opens with 'Tell the Pipeworx team something is broken, missing, or needs to exist,' clearly stating the tool's purpose. It enumerates feedback categories (bug, feature/data_gap, praise) and explicitly distinguishes from sibling tools by noting it's only for Pipeworx-served tools.

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

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

Explicitly states 'Use when...' with concrete triggers (wrong/stale data, missing tool, praise). Provides a clear exclusion: 'ONLY for tools served by this Pipeworx connection... file it with that server instead.' Also gives formatting guidance and rate limit.

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. The description adds valuable context: it is a 'self-aggregating signal — derived from CF analytics-engine, no PII, just (pack, tool, count)' and is 'cached 5min-1h depending on window.' This goes beyond annotations by disclosing data provenance, privacy, and caching behavior.

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

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

The description is well-structured and concise. It front-loads the core purpose, then lists three specific use cases, followed by a brief note on data source and caching. Every sentence adds value and the bullet-point format improves readability.

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

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

For a tool with a single optional parameter and no output schema, the description covers the key aspects: what it returns, the available windows, the source of the data, privacy implications, and caching. It does not describe the exact response format, but the absence of an output schema makes this a minor gap. Overall, it is sufficiently complete for an agent to decide whether and when to use it.

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

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

The schema already fully describes the window parameter with enum values and a detailed note comparing shorter vs longer windows. The description only restates the window options without adding new semantic information. With 100% schema coverage, the baseline of 3 is appropriate.

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

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

The description clearly states the tool's function: 'Returns the top tools, top packs, and total call volume over a recent window.' It uses the specific verb 'Returns' and names the concrete resources. It also distinguishes itself from sibling tools like discover_tools by emphasizing it is an aggregated signal of other AI agents' calls, not a general discovery tool.

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

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

The description provides explicit 'Useful for' scenarios: discovering hot data sources, confirming canonical tools, and aligning use cases with agent demand. However, it does not mention when NOT to use this tool or explicitly name alternative tools, so it falls short of a 5.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. Description adds rich context: partition checks, placeholder filtering, Jaccard similarity threshold, fill check against live CLOB depth, and explicit 'do not trade it' guidance for unrealizable edges. No contradictions with annotations.

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

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

Long but highly structured: uses labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loads the primary purpose and mode selection. Every sentence adds operational detail for a complex tool, with no filler or redundancy.

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

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

Despite no output schema, the description fully documents response shape (opportunities[] with fields, partition_check fields, fill check results) and covers edge cases, filtering logic, and actionable trade guidance. It is effectively self-contained for an agent to invoke correctly.

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

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

Schema coverage is 100%, but description substantially enhances each parameter: explains event slug format with examples, accepts full URLs, defines topic as a seed question, and clarifies what each mode does. This goes well beyond the schema descriptions.

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

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

Description starts with specific verb+resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly scopes behavior (trending scan, event-level, topic-level) and distinguishes from siblings like polymarket_edges or polymarket_fill_risk by focusing on arbitrage 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?

Description gives explicit mode selection: no args for trending_scan, `event` for specific markets, `topic` for cross-event scans. It even recommends `event` for a specific market and mentions when to use polymarket_fill_risk for custom sizing, providing clear alternatives and 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 is exceptionally transparent about behavior beyond the annotations. It details model families, response segmentation, diagnostics, a 24h-move warning, cache behavior, placeholder-slug filters, and edge/filtering logic. Since annotations already indicate a safe read-only operation, the description adds substantial context 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 thorough but quite lengthy, with dense run-on sentences and extensive parenthetical details. It is front-loaded with the purpose, but the sheer volume of model-specific detail makes it less concise. It earns a 3 because while every sentence adds information, the overall structure is unwieldy for quick scanning.

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 (9 parameters, three response segments, diagnostics, no output schema), the description is remarkably complete. It explains the top-level response structure, segment contents, diagnostics for empty results, filtering knobs, and even notes unreliable signals. This makes the tool's behavior clear without an output schema.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaningful parameter context, such as how min_partition_leg_kelly applies to per-leg Kelly instead of parent-level kelly_fraction_half, and how slippage_pp subtracts from raw edge. These details go beyond the schema, meriting a 4.

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

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

The description clearly states the tool's purpose: "Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price." It uses a specific verb and resource, and the use case is clear. However, it does not explicitly distinguish itself from sibling tools like polymarket_arbitrage or polymarket_edge_tracker, so it earns a 4 rather than 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 provides strong usage context: "Built for 'what should I bet on today' — agents discover opportunities without paging hundreds of markets." It also explains knobs like min_liquidity and max_spread_pp for filtering. However, it does not explicitly state when to prefer this tool over alternatives or provide exclusions, 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?

Annotations already declare readOnly/openWorld/idempotent/destructive safety, so the description goes beyond by explaining data quirks: snapshots written only on cache-miss (gaps mean no scan), 60-day TTL bound, and decay computed from daily closes net of slippage, not intraday. This is rich behavioral context that annotations do not 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 long but extremely well-structured with clear sections (Args, RESPONSE, LIMITS) and front-loaded purpose. Every sentence contributes functional information—response fields, trend meanings, and limitations—so the length is justified and concise in 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?

Given no output schema, the description thoroughly explains the return structure (tracked, expired, snapshot_dates) and their semantic nuance. It also covers historical depth limits and data-gap behavior, making it complete for a telemetry tool with moderate 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% for both parameters, so the baseline is 3. The description adds minor clarifications like days as lookback and window as snapshot family, but largely repeats schema details (defaults, bounds). It does not add significant semantic insight beyond the schema.

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

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

The description clearly identifies the tool as edge persistence and decay telemetry built from daily polymarket_edges snapshots, with a concrete question it answers: 'how long has this edge existed and is it shrinking?' This distinguishes it from sibling tools like polymarket_edges by focusing on historical persistence rather than current edge listing.

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 a clear use case: distinguishing a fresh wide edge from a 3-week-old wide edge, implying this tool is for assessing edge aging. It does not explicitly name alternatives or state when not to use it, but the context strongly implies its role relative to current-edge tools, earning 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 readOnly, openWorld, idempotent, and non-destructive hints. The description adds valuable behavioral detail beyond this: it walks the order-book ladder, returns a verdict (clean|degraded|cannot_fill), and discloses the risk of partial basket fills creating unhedged directional positions. No contradictions with annotations.

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

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

The description is dense and information-rich, but it is a single long paragraph with heavy use of capitalization for emphasis. Every sentence adds value, but readability would improve with bullet points or section breaks. It's appropriately sized for the tool's complexity but could be better 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 tool is complex (two modes, no output schema), yet the description lists return fields for both modes (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict, theoretical_sum, realizable_sum, capture_ratio, thin_legs[], etc.), plus edge cases and risk warnings. This is complete enough for an agent to invoke correctly.

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

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

Although input schema covers all four parameters (100% coverage), the description adds critical semantics: market vs event mode mutual exclusivity, side interpretation differences between single and basket modes, size_usd meaning (spend vs target proceeds vs settlement notional), and default/clamp ranges. This significantly enriches the schema.

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

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

The description opens with a specific verb+resource ('Realizable-vs-theoretical edge check against live CLOB order-book depth') and clearly differentiates from sibling tools by explicitly referencing polymarket_arbitrage and polymarket_edges. It fully explains both single-market and basket modes, making the tool's purpose 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 explicitly states when to use this tool: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It also explains why (theoretical overround on thin books is not capturable, partial fills convert arb into directional risk), providing clear context and exclusion logic.

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

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

Annotations already convey read-only, idempotent, non-destructive behavior. The description adds substantial context: it explains the output structure (leg-by-leg prices, spread, top_spreads_pp), the meaning of compatibility_warning cases (matched_pairs:0 with skipped_cross_type>0 vs. both >5 legs), temporal_alignment implications, and how skipped_cross_type/subtype counters reflect dropped comparisons. This far exceeds the bar for behavioral disclosure.

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 information-rich, with clear section markers (TWO MODES, RESPONSE, SAFETY FIELDS) that aid parsing. It is longer than a simple two-liner, but every sentence adds meaningful detail about behavior, edge cases, or limitations—no filler. A slight trim of restating 'pre-mapped ≠ tradeable' at the end could improve conciseness, but it is well-structured for the complexity involved.

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 it does so thoroughly: leg-by-leg prices, spread arrays, top_spreads_pp, compatibility_warning triggers, temporal_alignment, and skip counters. All three parameters are documented with examples. For a read-only comparison tool with no required parameters, this provides complete actionable context for invocation.

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

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

Schema coverage is 100%, but the description enriches the raw schema by explaining the two functional modes (topic shortcuts vs. explicit tickers/slug) and how the explicit fields override the topic-mapped side. It also lists the exact valid topic values, giving the agent a clear grammar for parameter selection beyond the schema's terse 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 and resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly explains the tool's function and differentiates it from siblings like polymarket_arbitrage by emphasizing compatibility checks and the fact that pre-mapped topics are not automatically tradeable.

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

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

The description gives explicit when-to-use guidance via TWO MODES and explains when the tool reports a compatibility warning (e.g., when bet shapes are non-equivalent). It also warns that 'pre-mapped ≠ tradeable,' but does not explicitly name alternative tools, leaving some ambiguity about when to prefer a 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so safety is covered. The description adds meaningful behavioral context beyond that: the tool is scoped to an identifier ('anonymous IP, BYO key hash, or account ID'), and the ability to list all keys by omitting the argument is described. It does not detail return formats or error behavior, but the added scoping info 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 three sentences, each earning its place: the first states the action and modes, the second provides usage context with examples, and the third covers scoping and companion tools. It is front-loaded with the core function and contains no filler or redundancy.

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

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

Considering the tool's simplicity (one optional parameter, no output schema), the description covers both invocation modes, scoping, and usage intent. However, it does not describe the return value format or behavior when a key is not found, which would be useful given the absence of an output schema. Overall, it is nearly complete but has a small gap.

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

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

The schema already provides 100% coverage for the single 'key' parameter with the description 'Memory key to retrieve (omit to list all keys)'. The tool description repeats this information ('omit the key argument') but adds no new semantic detail beyond what the schema already conveys. Thus the description does not significantly elevate understanding of the 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 opens with a specific verb and resource: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' It clearly distinguishes this tool from siblings by directly naming remember (save) and forget (delete), and explains the dual modes of operation. This is unambiguous and fully differentiates the tool.

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

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

It provides clear context for when to use the tool: 'Use to look up context the agent stored earlier' with concrete examples (target ticker, address, research notes). It also names companion tools for alternatives (remember to save, forget to delete). However, it does not explicitly state when NOT to use it (e.g., when to prefer search), though this is implied by the focus on previously stored memory.

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, but the description adds key behavioral context: the mark_read side effect (flagging events read), the return payload structure, and the fact that polling works fine. 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 three sentences: front-loaded purpose, then details on output and parameters, and a closing note on polling/alternative access. Every sentence contributes value with no redundancy or filler.

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

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

For a read-oriented tool with no output schema, the description fully covers return value contents, filter syntax, the mark_read behavior, and an alternative access method. It is sufficiently 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?

Schema coverage is 100%, but the description adds meaningful context for type (e.g. 'sec_8k'), since (ISO timestamp), and especially mark_read (effect on subsequent calls). It does not describe limit or unread_only, but those are already clear 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 starts with a specific verb+resource ('Pull fired events from your subscription feed') and clearly states what the tool returns (recent alerts with source, citation_uri, and raw payload). This distinguishes it from siblings like list_subscriptions or recent_changes.

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 explains filtering by type and since, notes that polling is supported, and provides an alternative endpoint for scripts/dashboards. This gives explicit context on when to use the tool versus other access methods.

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

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

Beyond annotations, the description discloses the multi-source fan-out, the GDELT→GNews fallback under rate limits/5xx, and the USPTO soft-fail due to PatentsView API sunset. It also explains the return structure including citation URIs, which is not in annotations.

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

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

The description is dense but every sentence carries meaning. It starts with relatable examples, moves to fan-out behavior, then return format, and ends with an alternative. 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?

Despite having no output schema, the description explains the return payload (changes[] grouped by source, total_changes count, citation URIs) and the source-specific behaviors (fallbacks, soft-fail). This makes the tool's behavior fully transparent for a complex operation.

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 description adds practical semantics to the schema, such as `since` accepting ISO dates or relative shorthand with examples and suggesting typical monitoring values. It also clarifies `value` accepts ticker or CIK formats, enriching the schema's coverage.

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

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

The description clearly defines the tool as a change feed for a company over a time window, with explicit example queries and a named resource. It also distinguishes itself from the sibling entity_profile by specifying static profile use cases.

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

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

It provides concrete usage scenarios ('What's new with X', 'latest on Y') and explicitly states when NOT to use it ('Use entity_profile instead when you want the static profile'). This gives clear guidance on tool selection.

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

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

Goes beyond the annotations by describing persistence semantics ('Authenticated users get persistent memory; anonymous sessions retain memory for 24 hours') and scoping ('scoped by your identifier'). The description is consistent with idempotentHint=true and readOnlyHint=false, and adds useful details about data lifetime.

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

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

The description is compact and front-loaded with the core purpose, followed by usage context, technical details, and companion tool references. Every sentence adds value without excessive verbosity.

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 schema (2 required string params) and no output schema, the description fully covers what the tool does, when to use it, storage semantics, and how it relates to recall/forget. No critical missing behavioral information.

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 self-explanatory descriptions for 'key' and 'value'. The tool description does not add parametric meaning beyond giving examples of keys in the usage context, so it meets the baseline but does not exceed it.

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

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

The description uses a specific verb 'Save' with a clear resource ('data the agent will need to reuse later'). It distinguishes from siblings by explicitly naming 'recall' and 'forget' as companions, and gives concrete use examples like 'a resolved ticker, a target address, a user preference'.

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') and contrasts with alternatives ('Pair with recall to retrieve later, forget to delete'). This gives clear context for choosing this tool over the related memory tools.

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

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

Beyond the readOnly/idempotent/openWorld annotations, the description discloses internal cascading lookups, graceful degradation of LEI/FIGI enrichment, source labeling of identifiers, and explicit handling of unresolved identifiers under 'unresolved'. These details go well beyond the annotations and describe important runtime behavior.

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

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

The description is long but front-loaded with examples and purpose, and the detailed sections on supported types and degradation are necessary. It could be slightly more concise by trimming redundant phrases, but the structure is logical and no sentence is wasted.

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

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

For a tool with no output schema and two entity types, the description is remarkably complete: it covers input formats, output identifiers, fallback behavior, and unresolved handling. The agent has enough information to invoke it correctly and interpret results in most scenarios.

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

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

Although the schema covers 100% of parameters, the description adds rich semantics: company accepts ticker, CIK, or name; drug accepts brand or generic. It enumerates the output identifiers for each type and clarifies which inputs are valid. This adds meaning 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 states the tool resolves user-spoken names to canonical/official identifiers, with concrete examples and supported types. It distinguishes itself from siblings like search or entity_profile by explicitly mentioning 'other tools require as input' and 'Use FIRST when you have a name but need an ID.'

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

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

The description gives explicit when-to-use guidance: 'Use FIRST whenever you have a name but need an ID.' It also explains the tool replaces 2-3 manual lookups, implying it consolidates several lookups and should be preferred in such scenarios. This is clear context for selection among sibling tools.

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

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

Annotations cover the read-only/idempotent nature, so the bar is lower. The description adds meaningful behavioral context by explaining the internal action ('Probes each entity ... with ai_visibility_check'), the ranking behavior, and the exact output fields ('score, confidence, signal density per entity'). This goes beyond the structured 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 tight three sentences: purpose, mechanics, and use case. Every sentence contributes new information, with no repetition of the tool name or obvious fluff. It's front-loaded with the primary verb and resource.

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 4 parameters but no output schema, the description compensates by explicitly stating the return format: 'ranked list with score, confidence, signal density per entity'. Combined with annotations that confirm safety, and the schema that documents parameters, the description provides complete operational context for an AI agent to select 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?

The schema already documents all 4 parameters with 100% coverage, giving the baseline 3. The description adds a crucial semantic detail: the first entity is the 'subject' and the rest are competitors, which informs how the entity array should be constructed. It also clarifies that the 'context' parameter is applied to every probe, adding interpretive value.

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 'Compare AI visibility across multiple entities side-by-side', which clearly states the verb, resource, and scope. It further distinguishes from the sibling ai_visibility_check by noting it probes each entity with that tool and ranks them, making its multi-entity purpose unambiguous. This is a specific, non-tautological description.

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 a clear use case: 'competitive AI-marketing audits' with the example question 'does Claude know about us as well as our competitors?'. It also implies that for a single entity, ai_visibility_check is the appropriate tool, but it doesn't explicitly state when not to use this tool or name alternatives beyond the mechanism. That gap prevents 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?

Beyond the readOnlyHint/idempotentHint annotations, the description adds operational details: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed will list timeouts. It also enumerates the return structure, providing context annotations don't cover.

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

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

The description is long but every sentence earns its place: purpose first, then usage triggers, then return fields, then ecosystem limitations, then failure/latency behavior. It is front-loaded and dense with useful information, with no fluff.

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

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

There is no output schema, but the description lists exact return fields (summary block fields, per-advisory detail, links, recent alternative versions), explains latency and failure modes, and defines its ecosystem scope. This makes the tool self-contained and fully actionable for an agent.

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

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

Schema description coverage is 100%; both parameters are already well-documented in the schema (package accepts scoped names, version defaults to latest). The description adds no additional 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 performs a composite 'should I add this npm package to my project' check, combining deps.dev and bundlephobia data sources. It enumerates specific dimensions (license, advisories, version history, bundle size, dependency count, ESM/tree-shake support), making it distinct from sibling tools.

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

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

Explicitly says 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. Also provides a clear exclusion: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.' This tells when to use and when not to use, with a routing alternative.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds useful behavioral detail: supports Solr filter expressions, pagination via rows/start, sorting, and returns dataset titles, descriptions, and publisher info. 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 two sentences, front-loads the main purpose, and includes a concrete Solr filter example. Every word earns its place, no fluff.

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

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

For a search tool with 5 parameters, an output schema, and comprehensive annotations, the description covers all essential invocation aspects: the target portal, query semantics, optional filters, pagination, sorting, and return content. It is sufficient for correct selection and invocation.

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

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

Schema description coverage is only 40% (fq and rows have descriptions). The description compensates by explaining the query is free-text, fq is for Solr filters, rows/start enable pagination, and sort is for sorting. This adds meaning 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 states the tool: 'Search the EU open-data portal (data.europa.eu) for datasets by free-text query'. It specifies the verb (search), the resource (EU open-data portal), and the scope (datasets), distinguishing it from siblings like search_within by naming a specific external portal.

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 (searching EU open-data datasets) and mentions supported capabilities (Solr filters, pagination, sorting). It does not explicitly name alternatives or exclusions, but the specific resource and scope imply the appropriate use case.

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

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

Beyond the annotations (read-only, idempotent), the description discloses the embedding model (BGE-base-en), chunking strategy (500-char overlapping windows), truncation behavior (200K char cap flagged), and that results include character offsets for verifiable quotes. This adds substantial behavioral detail.

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

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

Four sentences each add unique value: purpose/inputs, use case, sibling pairing, and technical details. The description is front-loaded with the core action and remains efficient without redundancy.

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

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

Even without an output schema, the description explains the return format (passages with offsets and similarity scores), input size limits, and how to integrate with ask_pipeworx_grounded. It fully prepares an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100% but the description adds meaningful examples (SEC 10-K body, natural-language query examples) and clarifies the 'top-N' behavior corresponding to limit. The truncation note also enriches the 'text' parameter beyond its 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 core action: 'Semantic search INSIDE a fetched record,' and differentiates from siblings by emphasizing that the text must already be pulled (e.g., a SEC 10-K body). It also contrasts with ask_pipeworx_grounded by explaining the intended workflow. This is a specific verb+resource with clear 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?

Explicitly says 'Use when the record is too big to cram into the prompt' and describes how it pairs with ask_pipeworx_grounded: 'fetch with the gateway, ground over the relevant passages instead of the whole document.' This gives clear when-to-use and alternative 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 annotations already indicate a mutating operation (readOnlyHint: false), but the description adds meaningful behavioral disclosure beyond that: account prerequisites, feed always-on behavior, SMS verification and rate cap, webhook HMAC signing, one-time secret return, and auto-disable after 10 consecutive failures. This fully informs the caller of side effects and constraints, with no contradiction.

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

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

The description is dense and front-loaded with the core purpose, then organized by subscription types and delivery channels. While it is longer than average, every clause adds specific information. The webhook signing details are somewhat intricate, making it slightly less concise than a 5, but still 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?

Given the tool's complexity (nested params, enum, no output schema), the description is remarkably complete: it covers authentication requirements, all subscription types, every delivery channel, return value, and operational caveats. An agent can invoke it correctly without needing external 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 coverage is 100%, but the description adds significant semantic detail: concrete examples for each type (e.g., 'sec_8k' items:["5.02"]), the requirement for 'sponsor or condition' in clinical_trial, delivery channel specifics like verified phone numbers and the 10/day SMS cap, and webhook signing details. It goes well beyond the schema.

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

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

The description uses specific verb 'Create' and clearly identifies the resource as 'a proactive monitoring subscription to a live-data event stream'. It distinguishes itself from sibling tools like list_subscriptions and unsubscribe by focusing on the act of subscribing, and it additionally notes the return value (new subscription id).

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

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

The description provides extensive context about when to use the tool: it requires a Pipeworx OAuth account, lists supported subscription types with example parameters, and explains delivery channel options. However, it does not explicitly mention 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, and destructiveHint=false, so the agent knows this is a safe, idempotent read operation. The description adds valuable behavior beyond annotations by explaining that it returns category-bucketed example questions with exact tool + argument shapes, and that it draws from the live catalog of thousands of tools.

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

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

The description is longer than ideal but every sentence contributes: the leading user-phrased queries signal natural language triggers, the category list explains output scope, and the usage guidance is actionable. It is not bloated or repetitive, and the key usage instruction ('Use this FIRST') is placed near the end but remains prominent.

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 parameter, no output schema), but the description fully covers what the tool returns, how to use it with and without the topic parameter, and when to prefer it. It also explains the connection to meta-tools, which is sufficient for an agent to invoke it correctly in an onboarding context.

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

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

The input schema already describes the single 'topic' parameter with a full list of allowed values and the note to omit for a cross-category spread, giving 100% schema description coverage. The description adds example topics ('finance', 'pharma', 'betting') and confirms the 'omit for full spread' behavior, but it does not materially go beyond what the schema already conveys.

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

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

The description clearly states the tool's purpose as the onboarding entry point for an agent that just connected and wants to know what Pipeworx can do. It uses a specific verb+resource ('suggest questions', 'what can I ask Pipeworx') and distinguishes itself from siblings by emphasizing it is the 'use this FIRST' tool and by describing its role relative to meta-tools like ask_pipeworx and compare_entities.

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

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

The description explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools', which provides clear context for when to use it. It does not mention explicit exclusions or alternatives like discover_tools, but it does name related meta-tools, giving partial 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 read-only, idempotent, non-destructive nature. The description adds behavioral context: query filters by prefix, limit controls page size with a default of 100, which goes beyond 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?

A single sentence efficiently conveys the tool's purpose and both parameters, with no redundancy.

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

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

For a simple two-parameter tool with comprehensive annotations and an output schema, the description covers the essential usage details. Nothing critical is missing, though more niche details like sorting order are not discussed.

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

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

The schema provides only types and examples, with 0% description coverage. The description fully compensates by explaining that query filters by prefix and limit sets page size with a default value.

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

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

The description uses the specific verb 'List or search' with the resource 'keyword tags' and clearly scopes it to the EU open-data portal, distinguishing it from sibling tools like groups or search.

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 explains how to use query for prefix filtering and limit for page size, giving clear context. However, it does not explicitly mention when not to use it or point to alternatives, so it stops short of full guidance.

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

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

The description adds meaningful behavioral context beyond the annotations: ownership enforcement and deactivation (not deletion) of the row. This aligns with destructiveHint=false and idempotentHint=true, reinforcing the tool's safety profile 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?

Two sentences, front-loaded with the primary action, then ownership, then consequences. No wasted words 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?

For a simple one-parameter tool with no output schema, the description is fully adequate. It explains the operation, ownership constraint, and post-cancellation behavior, leaving no obvious gaps.

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

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

Schema coverage is 100% with a clear description of the id parameter. The description itself adds little beyond 'by id', so the schema already carries the semantic weight. 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 the action ('Cancel a subscription by id') with a specific verb and resource. It distinguishes itself from sibling tools like subscribe and list_subscriptions by focusing on the cancellation operation.

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

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

Clear context is provided: the tool is for cancelling subscriptions, and ownership is enforced. The mention of recent_alerts for historical events gives a hint about post-cancellation behavior, though it doesn't explicitly contrast with alternatives or state when not to use.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description explains key behavioral nuances: the could_not_verify result means the check didn't happen and carries a verification_error, not evidence for/against the claim; unsupported means no source covers it. It also discloses the routing logic (SEC EDGAR/XBRL fast path vs. grounded pipeline) and the fact that it replaces multiple sequential calls, giving the agent a clear model of what the tool does and how to interpret its outputs.

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

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

The description is dense but every sentence carries weight: trigger examples, routing logic, return values, and an 'IMPORTANT for callers' note. It opens with natural-language triggers, then explains the core behavior, return structure, and exceptions, all without repetition. The structure is logical and easy to scan.

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

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

With no output schema, the description fully covers what the tool returns (verdict types, actual value with citation, reasoning) and how to interpret edge cases (could_not_verify, unsupported). It also explains the processing pipeline and the performance benefit (replacing 4–6 calls), making the tool's behavior and limitations clear for an agent.

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

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

While the schema already covers both parameters at 100%, the description adds valuable semantics by explaining tolerance_pct's behavior: it 'Overrides the tolerance implied by the claim wording' and recommends setting 1–2 for hallucination detection, plus notes the default cap of 5. This is meaningful guidance beyond the schema's basic definition.

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: 'natural-language claim verification against authoritative sources' and explicitly maps to user intents like 'fact check' and 'verify the claim that…' with concrete examples. It distinguishes itself from sibling tools by emphasizing verdict-based verification, returning a structured verdict, and replacing 4–6 sequential calls.

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 guidance: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also provides trigger phrases and explains the routing behavior for company-financial vs. other claims. However, it does not name specific sibling alternatives to rule out (e.g., search or ask_pipeworx_grounded), so slightly less than a 5.

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