France Boamp

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds behavioral context like scoring range 0-100, per-model returns, and cost implications for Anthropic (BYO key). 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?

Description is a single tight paragraph, no wasted words. Purpose is front-loaded, and each sentence adds value (models, scoring, parameters, use cases).

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 what is returned (per-model score, confidence, signals, raw_response + combined view). Covers all parameters and use cases, leaving no 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% (all parameters described). The description adds meaningful context: default model type and cost, optional Anthropic with BYO key, and context purpose (disambiguation).

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 probes LLMs for visibility scores on a business/brand/product/topic, with specific verb 'probe' and resource 'LLMs'. It distinguishes from siblings like 'deep_research' or 'compare_entities' by focusing on AI visibility auditing.

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 outlines when to use (AI-marketing audits, pre-launch checks, competitive monitoring) and how to extend with _apiKey for Anthropic. It lacks explicit exclusions but provides clear use cases.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses useful behavior: it routes to thousands of source tools, fills arguments, and returns structured answers with stable pipeworx:// citation URIs. It does not cover failure modes or speed, but the annotations already cover the mutation and world-access profile.

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

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

The key guidance is front-loaded, but the description repeats the same 'Use whenever... Examples... START HERE' passage multiple times and ends with an unrelated instruction to 'Reset all context...'. This padding makes the description significantly less concise and 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?

For a broad routing tool, the description covers what it does, when to use it, example queries, and the form of the response (structured answer with citation URIs). The repetitive tail and lack of explicit unsupported-question types are gaps, but the essential selection and invocation information is present.

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

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

The schema already documents all six parameters with 100% coverage, and most are aliases for the same natural-language question. The description adds no parameter-level guidance beyond what the schema provides, 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 clearly states the tool's action: it routes factual questions to relevant tools and returns structured answers with citations. It is specific about scope ('current or historical data', SEC, FDA, FRED/BLS, etc.). However, it does not explicitly distinguish itself from sibling tools like ask_pipeworx_beta or ask_pipeworx_grounded.

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 strong when-to-use guidance, including trigger phrases, examples, and explicit guidance to prefer this over web search ('even if web search could also answer it'). It lacks clear when-not-to-use guidance and does not mention alternatives among sibling ask_pipeworx variants, so it is not quite a 5.

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

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

Annotations already mark the tool read-only, open-world, idempotent, and non-destructive. The description adds valuable context beyond that: it is an experimental live edge, may have routing candidates under test, currently has none, and is a full working router with no fallback. 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 a bit longer than necessary but each sentence carries distinct information: beta identity, current candidate state, usage instruction, and experimental nature. The key statements are front-loaded, though the date and repeated 'same ... same ... same' could be 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 complex universal router with no output schema, the description explains the tool's role, current behavior, and relationship to ask_pipeworx. It relies on the agent already knowing ask_pipeworx's response shape, since it says 'same response shape' without defining it, which is a minor 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?

Schema coverage is 100% and the schema already documents the `question` parameter and its aliases. The description adds only that arguments are identical to ask_pipeworx, which confirms compatibility but does not add new semantics beyond the schema.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx, a universal router over the same 5,908 tools with identical arguments and response shape. It distinguishes itself from ask_pipeworx by its experimental routing improvements, so an agent can tell what it does and how it differs.

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

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

It explicitly says to use it exactly like ask_pipeworx when the newest routing is wanted, and notes that results are compared against the stable router. This names the alternative and the selection condition; the current state (no candidate active) is also stated.

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, non-destructive behavior. The description adds valuable context beyond that: explicit success response shape, refusal reasons, evidence as verbatim quote, and the extra LLM call cost. No contradiction with annotations.

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

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

The description is dense but front-loaded with the core purpose, and every major behavioral point earns its place. Some repetition exists in spelling out routing steps after saying 'Same routing as ask_pipeworx', but overall it remains well-structured and focused.

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 the return contract and refusal cases, identifies the sibling tool and usage trade-off, and documents the aliases through the schema. An agent has enough context to invoke and interpret this tool correctly.

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

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

Schema description coverage is 100% and all parameters are aliases for the single question field. The description reinforces the natural-language question expectation but does not add meaning beyond the schema's own parameter documentation. 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 mode ('hallucination-resistant answer mode for high-stakes reads') and differentiates itself from ask_pipeworx by emphasizing extraction using only tool results. The verb 'answer' plus resource and behavioral scope make the 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?

Explicitly says when to use: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts', lists high-stakes examples, and names the alternative: 'prefer ask_pipeworx for casual lookups.' This gives clear routing 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 goes far beyond the annotations (readOnlyHint, idempotentHint, etc.) by detailing behavioral nuances: low-confidence resolution handling, closed market detection, wide-spread warnings, cancellation rule parsing, and fallback mechanisms for news. It is exceptionally transparent about edge cases and limitations.

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

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

The description is lengthy but well-structured with labeled sections (RESPONSE SHAPES, RESOLVER CONTRACT, etc.). It front-loads the core purpose and examples. While not extremely concise, every section adds necessary detail for a complex tool.

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

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

Given the tool's complexity, no output schema, and rich annotations, the description covers all essential aspects: input handling, classification, fan-out behavior, response structure, edge cases (low confidence, closed markets, wide spreads, cancellation rules), and safety mechanisms. It is thoroughly complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds significant extra context beyond the schema, such as the meaning of 'depth' (quick vs thorough with source count) and 'include_raw' (response size implications). This enriches parameter understanding.

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

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

The description clearly defines the tool's purpose: research a Polymarket bet by pulling Pipeworx data in one call. It specifies input types (slug, URL, question text), the resolution and classification process, and the output (evidence packet + market-vs-model comparison). This is highly specific and distinguishes it from sibling tools like polymarket_edges.

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

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

The description provides explicit use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') and lists classifiers for bet types. However, it does not explicitly contrast with sibling tools or state when not to use it, which would elevate it to a 5.

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

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

Despite comprehensive annotations, the description adds critical behavioral details: it explains that for companies it pulls latest 10-K financials from SEC EDGAR/XBRL with correct off-calendar fiscal year handling (citing AAPL Sep, NVDA Jan), and for drugs it pulls FAERS adverse-event counts, FDA approval counts, and active trial counts. It also notes results are sorted by primary metric and that citation URIs are returned. 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 a single dense paragraph but every sentence serves a purpose (examples, usage preference, data sources, sorting, output format). It is slightly lengthy but front-loaded with examples, making it effective. Minor improvement would be breaking into bullet points.

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

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

Given the tool's complexity (two entity types with different data sources, constraints on count), the description covers all necessary aspects: what it compares, how many, data sources per type, sorting behavior, output format, and citation handling. No output schema exists, but the description adequately explains return values.

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 enhances understanding by specifying that values should be tickers/CIKs for companies and drug names for drugs, and it explains the return payload context (e.g., revenue, net income for companies; adverse events for drugs). This goes beyond the schema's enum 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 concrete query examples like 'Compare X and Y' and 'X vs Y', immediately establishing the tool's purpose of side-by-side comparison of 2–5 companies or drugs in a single parallel call. It clearly contrasts with sequential single-pack lookups, making the function 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?

Explicit guidance to 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and the claim that it 'replaces 8–15 sequential lookups' provides strong usage direction. The description gives clear when-to-use and avoid scenarios, fully addressing the decision heuristic.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior, and the description adds a large amount of behavioral context beyond them: account requirement, paid plan, latency expectations, the findings-packet contract, gaps[] semantics, contradictions[], hop fields, citation resolvability, and semantic excerpting. The 'NOT open-web search' note does not contradict openWorldHint because the tool still reads external structured data sources.

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 and effectively front-loaded: the account requirement and primary routing alternative come first, then core purpose and behavior. Minor redundancy—'in ONE call' appears twice and depth semantics repeat some of the schema—keeps it from a perfect score, but no sentence is gratuitous.

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

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

There is no output schema, so the description correctly carries the full burden of explaining return values: verbatim evidence, confidence, source, fetched_at, stable citations, gaps[], contradictions[], hop fields, and the rule that citation URIs are only present when resolvable. It also covers latency, tier restrictions, and alternative tool routing, making it complete enough for correct invocation and result 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 already documents both parameters at 100% coverage, so the baseline is 3. The description adds practical semantic value beyond the schema: it clarifies that broad/multi-part questions are expected, ties depth levels to hop behavior and gap recovery, and emphasizes that 'thorough' requires a paid plan.

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

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

The description names a specific resource and action: grounded multi-source research across Pipeworx's 1540 structured data sources in one call, with decomposition and parallel routing. It explicitly distinguishes itself from ask_pipeworx and from open-web search, so an agent can tell it apart from 30 siblings without opening schemas.

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

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

The description gives explicit when-to-use and when-not-to-use guidance: use for broad/multi-part structured-data questions; use ask_pipeworx instead for single lookups, current/breaking news, and when not signed in. It also states the paid-tier constraint for 'thorough' depth, leaving little to inference.

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, destructiveHint=false. The description adds valuable behavior: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' This explains the output structure and readiness for invocation, going 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?

The description is somewhat long but well-structured. It front-loads the purpose, then lists domains, explains return value, and gives usage advice. Every sentence serves a purpose, though it could be slightly more concise. It is not verbose or redundant.

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 as a discovery tool with 6 parameters (including aliases) and no output schema, the description fully covers what the tool does, how to use it (examples, aliases), and what to expect (returns top-N tools with schemas). It is complete for the agent to understand and invoke correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining that the 'query' parameter accepts aliases (task, q, description, search) and provides examples like 'analyze housing market trends.' It also documents the 'limit' parameter with default and max. This semantic enrichment justifies a score above baseline.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists specific domains (SEC filings, financials, etc.) and explicitly differentiates from siblings by instructing 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This distinguishes it as a meta-discovery tool versus the many domain-specific siblings.

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

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

The description gives explicit usage guidance: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST.' It provides numerous examples of tasks (e.g., 'analyze housing market trends'). While it implies when to use, it lacks explicit 'when not to use' or alternatives, but the context and sibling names make usage 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?

Adds substantial behavior beyond the annotations: fans out across many named sources in parallel, returns sources_used/sources_failed, empty sections are real 'no data' not bugs, PatentsView API sunset soft-fails until reactivated, a company with only small-molecule/generic drugs will show no fda_products, and private companies return resolved:false with a notes line. All of this is consistent with the read-only, idempotent, open-world 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 rich, with trigger examples front-loaded and every sentence serving a purpose—no filler. However, it is one long unbroken paragraph, which makes scanning harder for an agent; structuring it into shorter segments (trigger, sources, return fields, input rules) would 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?

With no output schema, the description carries the full burden of explaining return values, and it does: cik/company_name, recent_filings with URIs, fundamentals fields, patents, federal_contracts, fda_products, hiring, news, LEI, and the source_failed handling. It also covers input variants and graceful failure for private companies. For a complex fan-out tool, this is a remarkably complete guide.

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

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

The input schema already documents type/value with 100% coverage, so the baseline is 3. The description adds value by providing concrete examples ('AAPL', '0000320193', 'Moderna') and by explaining the private-company edge case (resolved:false with notes), plus confirming that type values are interchangeable. This goes beyond the schema though not by a wide margin.

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

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

The description states a specific, valuable operation: a 'full cross-source profile of a US public company in ONE parallel call,' with clear trigger phrases like 'tell me about X' and 'company profile for Microsoft.' It differentiates itself from single-source lookups by instructing to 'ALWAYS PREFER' it for holistic views, so an agent can distinguish it from narrower 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?

Gives explicit when-to-use guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' This names alternatives and thecondition that selects this tool. However, it does not explicitly route to sibling tools for related cases, such as compare_entities for multi-company comparisons or resolve_entity for simply resolving an identifier, leaving some usage boundaries implicit.

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?

Matches destructiveHint annotation. Adds context about clearing sensitive data. Does not specify behavior for non-existent keys, but annotations already indicate idempotentHint=true.

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

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

Two concise sentences, immediately front-loaded with the core action. Every word serves a purpose.

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

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

Given only one simple parameter, no output schema, and annotations covering destructive/read-only nature, the description is complete and self-sufficient.

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

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

Schema coverage is 100% with a clear parameter description. The tool description adds no additional semantic information beyond the schema.

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

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

Explicitly states 'Delete a previously stored memory by key' — clear verb+resource. Distinguishes from sibling tools 'remember' and 'recall' by referencing them.

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 specific when-to-use scenarios: stale context, task completion, clearing sensitive data. Also mentions pairing with siblings for a complete workflow.

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, destructiveHint; description adds value by detailing the exact fields returned and source (BOAMP). 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?

Single sentence that efficiently conveys action, input, and output. No wasted words; front-loaded with key 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?

Given simple input (1 required param, no output schema) and annotations, description covers purpose, input format, output content, and source. No 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 parameter description. Description adds context: example ids and that it's a 'web id' from BOAMP, enhancing the schema-provided 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?

Description uses specific verb 'Fetch' and resource 'single French public-procurement notice from BOAMP'. It clearly distinguishes from sibling tool france_search_tenders (search vs. single retrieval).

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?

Clearly states when to use: fetch a single notice by id. Does not explicitly exclude alternative scenarios (e.g., searching), but sibling naming implies the distinction. Could be improved by noting alternatives explicitly.

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, destructiveHint. The description adds fine-grained behavior: full-text search on 'objet', optional department filter, sorted by most recent first, and specifies return fields (id, title, buyer, dates, etc.). 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 compact (~80 words), front-loaded with purpose and guidance, then specific parameters and return format. Every sentence adds value; 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?

Given the tool's complexity (4 params, no required, no output schema), the description covers all essential aspects: what it does, when to use, parameters, filtering, sorting, and return structure. It provides sufficient context for an agent to invoke correctly.

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

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

Schema coverage is 100% with good descriptions. The tool description provides additional context like examples ('informatique', '75') and explains behavior when parameters are omitted (e.g., query omitted lists latest). This enriches understanding beyond schema.

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

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

The description clearly states the tool searches French government procurement notices (BOAMP) and distinguishes itself from sibling 'france_get_notice' by being a search function. It also explicitly prefers this tool over web search for French tenders.

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 advises to prefer this tool over web search and explains when to omit query for latest notices. It does not fully exclude other tools like france_get_notice, but the guidance is clear and actionable.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior. Description adds process details (fetch, extract, emit markdown) without contradiction. No mention of rate limits or auth, but sufficient given annotations.

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

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

Three concise sentences front-loaded with purpose, no fluff. Every word serves a purpose.

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

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

Covers main functionality and use cases. Missing error condition details (e.g., invalid URL) but adequate for a simple tool with high schema coverage and annotations.

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 clear descriptions for both parameters. Description does not add additional meaning beyond the schema.

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

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

Description clearly states the verb 'generate', resource 'llms.txt file', and purpose for AI crawler indexing. It differentiates from siblings like ai_visibility_check by specifying it produces a file.

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 lists use cases (client indexing, drafting, auditing) but lacks explicit when-not-to-use or alternative tools. Context is clear but no exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. Description adds value by specifying the return fields (id, type, params, etc.) and implying default filtering of active subscriptions, 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?

Two sentences with no fluff: first sentence states purpose and output, second gives usage guidance. Front-loaded 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?

For a simple list tool with one optional parameter and no output schema, the description covers purpose, output fields, and usage context completely.

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 the single parameter (include_inactive). The description does not elaborate on the parameter beyond the schema, so it meets baseline but adds no extra semantic 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?

Description clearly states 'List the caller's active subscriptions' with a specific verb (list) and resource (subscriptions). It mentions the return fields, distinguishing it from sibling tools like subscribe and unsubscribe.

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

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

Provides 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 use the tool and implies alternatives (subscribe/unsubscribe).

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

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

The description adds significant behavioral context beyond the all-false annotations: claim_token flow for anonymous filing and follow-up, rate limit of 5 per identifier per day, no quota cost, and daily digest reading. It also clarifies that this does not affect tool-call quota, which is not derivable from annotations.

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

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

The description is front-loaded with the core purpose, then structured logically: use cases, exclusions, claim-token workflow, team practices, rate limit, and quota note. Every sentence carries unique information and there is no redundancy or fluff.

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

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

Despite no output schema, the description explains return values: filing returns a claim_token, and subsequent calls with that token return status and resolution details. It also covers rate limits and quota, making the tool fully understandable for an agent without additional documentation.

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

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

Schema coverage is 100%, so baseline is 3. The description adds extra meaning by explaining the claim_token link between submissions and follow-ups, and gives content guidance ('don't paste the end-user's prompt', 'describe in terms of Pipeworx tools/packs'), which goes 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?

The description opens with a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes this feedback tool from siblings (research, visibility, trading tools) by defining its scope as reporting issues or praise about Pipeworx 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 a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also clearly states when NOT to use it: 'ONLY for tools served by this Pipeworx connection' and directs to file elsewhere for other MCP servers.

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

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

Discloses data source ('CF analytics-engine'), privacy ('no PII'), and caching strategy ('5min-1h'), adding significant value beyond annotations which already mark it as safe and non-destructive.

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, all essential, front-loaded with purpose; 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?

Covers purpose, usage, data source, privacy, and caching; output schema absent but return type is inferable; annotations compensate for missing safety details.

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

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

Schema already describes the 'window' parameter with enum values; description adds interpretive guidance on how window length affects output (hot vs steady-state), supplementing the schema.

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

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

The description clearly states 'Returns the top tools, top packs, and total call volume' with specific timing, making the tool's purpose precise and distinct from siblings.

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 lists three specific use cases (e.g., discovering hot data sources, confirming canonical tool, aligning use case) providing excellent when-to-use guidance.

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

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

Annotations already indicate read-only, open-world, and idempotent behavior. The description adds essential behavioral details: default trending scan, event partition checks with sum-of-YES prices, cross-event similarity filtering, placeholder removal, and fill-check logic against live order book. 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 long but well-structured: starts with purpose, then mode details, semantic anchor, partition filter, response format, and fill check. While dense, every sentence adds value. Could be slightly more compact, but not overly verbose.

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 the tool (multiple modes, filters, fill checks) and the absence of an output schema, the description is remarkably complete. It covers default behavior, both modes, geometry checks, similarity threshold, placeholder filter, response contents, fill check, and alternative tool for sizing.

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

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

Both parameters have schema descriptions, and the tool description adds value beyond that: advises to use event for specific markets, explains slug format, describes topic as a seed question, and clarifies behavior differences. Schema coverage is 100%, but description enriches understanding significantly.

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

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

The description clearly states it finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes two modes (event and topic), and the purpose is distinct from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

Explicitly guides when to use event vs topic, recommends event for specific markets, describes default behavior with no args, and includes a fill check to avoid non-realizable trades. Also mentions alternative tool for custom sizing.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior. The description adds rich behavioral context: caching details (1h KV-level), response structure (by_segment with three segments, diagnostics, Fed bets exclusion), and model family explanations. This goes well beyond the annotations to inform agent 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 very detailed and well-structured with clear sections, but it is lengthy and could be more concise. Every sentence adds value, but the level of technical detail (e.g., specific Greek letters, funnel counters) may overwhelm some agents. It is front-loaded with purpose but not optimally concise.

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

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

For a complex tool with 9 parameters and no output schema, the description fully explains the response structure, caching, limitations (Fed bets), and tradeable-edge knobs. It provides complete context for an agent to understand what the tool returns and how to interpret results, filling the gap left by the missing 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?

With 100% schema coverage, each parameter already has a description. The tool’s description adds valuable context for several parameters (e.g., min_partition_leg_kelly explains why min_kelly doesn't filter partitions, slippage_pp mentions Polymarket fees). However, not all parameters receive additional elaboration beyond the schema.

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

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

The description clearly states the tool scans top Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. It explicitly targets 'what should I bet on today' scenarios, distinguishing it from sibling tools like polymarket_arbitrage or polymarket_edge_tracker by focusing on discovery without paging hundreds of markets.

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

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

The description is built around daily discovery and explains tradeable-edge knobs and diagnostics for empty segments. It implicitly guides usage but does not explicitly state when not to use this tool or compare directly with siblings, leaving some room for improvement.

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 adds extensive behavioral context beyond annotations: explains return structure (tracked, expired, snapshot_dates), data source (daily closes of edge_pp_net), and limitations (60-day TTL, no intraday). No contradictions with annotations (readOnlyHint=true, etc.).

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 somewhat lengthy but well-structured: purpose first, then parameter details, response format, and limitations. Every sentence adds value, though some redundancy could be trimmed. Front-loaded with the key question the tool answers.

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 thoroughly explains the return structure (tracked[], expired[], snapshot_dates[]) and their fields. Limitations about TTL and data source are covered. For a 2-parameter read-only tool, this is fully 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 covers both parameters with descriptions. Description adds defaults (days=14, window='1wk'), value constraints (days max 30), and clarifies window as 'snapshot family'. This provides meaningful additional context beyond the schema.

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

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

The description clearly states the tool provides edge persistence and decay telemetry from daily snapshots, answering specific questions about edge duration and shrinkage. It distinguishes itself from sibling tools like polymarket_edges by focusing on historical trends rather than current edge values.

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

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

The description implies usage for assessing edge persistence and comparing fresh vs. old edges. It does not explicitly list when not to use or name alternative tools, but the context suggests polymarket_edges for current values, providing clear guidance within the description.

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, destructiveHint=false. The description adds behavioral context beyond annotations: 'walks the ladder', returns specific metrics, and explains the dominant loss mode (partial fills). 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 effective but verbose, with some redundancy between schema descriptions and the narrative. It is front-loaded with the core purpose, but could be more concise without losing essential 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?

Given the complexity (two modes, multiple return fields), the description is comprehensive. It lists all output fields, explains basket risk (thin_legs, forced_directional_risk), and notes the absence of an output schema. No additional information is needed.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaning beyond schema: clarifies defaults (side 'auto' in basket mode), interpretation of size_usd as 'settlement notional' in basket mode, and the clamp range. This enhances understanding.

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

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

The description clearly states the tool performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth', and distinguishes between single-market and basket modes. The verb 'check' and resource 'edge' are specific, and the tool is differentiated from siblings like polymarket_arbitrage.

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

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

Explicit when-to-use guidance is provided: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It also explains why by highlighting the risk of partial basket fills converting arb into unhedged positions.

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

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

Annotations declare readOnly/openWorld/idempotent/non-destructive, and the description adds substantial behavioral context: compatibility code semantics, non-equivalent bet shapes, gross vs net spread due to Kalshi fees, unverifiable pairings, skipped leg logic, and null temporal_alignment meaning. This goes far beyond what the annotations already provide and does not contradict them.

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

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

The description is long but deliberately structured with labels (TWO MODES, RESPONSE, SAFETY FIELDS, codes, fees_note) and front-loads the core purpose. Some lists are duplicated from the schema, but nearly every sentence adds behavioral nuance; the 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?

With no output schema, the description carries full responsibility for return semantics and does so thoroughly: leg prices, top_spreads_pp, flags[], compatibility_codes[], skipped counters, fees_note, and temporal alignment semantics. It even handles edge cases like unclassified legs and null alignment, making the tool safely callable by an agent.

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

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

All three parameters are already documented in the schema (100% coverage), so the baseline is 3. The description adds real meaning by explaining that explicit ticker/slug override the topic-mapped side and that both modes run the identical token-overlap matcher. This is useful semantic context beyond the schema.

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

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

The description states a specific deliverable — the cross-venue spread between Kalshi and Polymarket for the same resolving question — and details the two input modes and response contents. This clearly distinguishes it from the sibling Polymarket-only tools in the list. It is specific, non-tautological, and actionable.

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

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

The description clearly explains when to use topic shortcuts versus explicit kalshi_event_ticker/polymarket_event_slug, and warns that pre-mapped topics often return compatibility_warning and are not necessarily tradeable. It does not explicitly compare against sibling tools such as polymarket_arbitrage, so alternative selection is left somewhat implicit.

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

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

Annotations already indicate readOnlyHint=true and idempotentHint=true. The description adds scoping details (anonymous IP, BYO key hash, account ID) beyond annotations, but could further clarify behavior when key is missing or invalid.

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

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

Three concise sentences, each carrying essential information. Front-loaded with the primary action, no redundant phrases.

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

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

For a simple retrieval tool with one parameter and comprehensive annotations, the description fully covers purpose, usage, scoping, and relationship to sibling tools. No 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 one optional string parameter. The description adds critical usage semantics: omitting the key lists all saved keys. This goes beyond the schema to inform agent behavior.

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

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

The description uses specific verbs ('Retrieve', 'list') and clearly identifies the resource ('value previously saved via remember'). It distinguishes the tool from its siblings (remember, forget) by explaining its role in the triad.

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

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

Explicitly states when to use the tool ('look up context the agent stored earlier') and when to list all keys ('omit the key argument'). Mentions pairing with remember and forget, providing clear guidance.

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

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

Annotations already indicate safety (readOnly, idempotent). The description adds valuable behavioral details: return fields (source, citation_uri, raw payload), the effect of mark_read on subsequent calls, and that the feed is persisted. 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?

Four sentences, front-loaded with the core action. Each sentence adds essential information without redundancy. Highly efficient and easy to parse.

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

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

Given no output schema, the description covers return structure, parameters, and behavior (mark_read, polling). Mentions an alternative API. Lacks only minor details like ordering or pagination, which are implicit from typical use.

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

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

Schema coverage is 100%, so baseline is 3. Description enhances understanding by providing a concrete example for type ('sec_8k') and explaining that mark_read flags events as read. Adds meaningful context beyond the schema definitions.

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 pulls fired events from the subscription feed, specifying both the verb ('pull') and the resource (alerts in the feed). It distinguishes itself from siblings like 'list_subscriptions' by focusing on the events themselves rather than subscription management.

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

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

Provides clear guidance on filtering by type and since, explains the mark_read parameter effect, and notes that polling works fine. Offers an alternative REST endpoint for scripts/dashboards. Does not explicitly exclude any use cases or mention 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?

Annotations already declare readOnlyHint, idempotentHint, etc. Description adds valuable behavioral context: fanning out to multiple sources, GDELT→GNews fallback, USPTO soft-fail. Does not contradict 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?

Front-loaded with example queries, packs many details (sources, fallback, return structure) in one paragraph. Slightly lengthy but every sentence adds value.

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

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

Without output schema, description covers return format (changes grouped by source, total_changes, citation URIs). Also mentions fallback behavior and soft-fail. Sufficient for a complex tool.

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

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

Schema coverage is 100% with descriptions. The description adds example values and relative shorthand for 'since', and clarifies 'value' accepts ticker or CIK. Meaningful addition beyond schema.

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

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

Description clearly states the tool aggregates recent changes (SEC, news, patents) for a company over a window. It uses specific verbs ('change feed') and distinguishes the use case from static profile via entity_profile sibling.

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 via example queries ('What's new with X', 'latest on Y') and when-not-to by pointing to entity_profile for static profile. No ambiguity.

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 adds persistence behavior (authenticated vs anonymous, 24h expiry) and scoping info beyond annotations. Annotations already indicate idempotent and non-destructive, 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?

Three sentences, front-loaded with purpose. No unnecessary words; each sentence adds distinct value.

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

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

For a simple tool with two required params and no output schema, the description fully covers usage, scope, persistence, and pairing with sibling tools.

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 adds meaningful examples (key naming conventions, value types) and contextual explanation of each parameter's purpose.

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 clearly states verb (save data), resource (key-value memory), and distinguishes from siblings recall and forget. Includes examples of when to use (resolved ticker, target address, etc.).

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 when to use (discover something worth carrying forward) and mentions pair with recall/forget. Does not explicitly state when not to use, but 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 mark it read-only, open-world, idempotent, and non-destructive. The description goes well beyond by disclosing that identifiers are source-labelled, unresolved identifiers are explicitly listed rather than omitted, ambiguous name matches return figi_candidates and assert nothing, and that the tool cascades through several internal lookups to replace 2–3 manual steps. 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?

Although lengthy, every sentence earns its place. The description is front-loaded with example queries and the core purpose, then systematically covers types, input rules, edge cases, fallback behavior, and internal cascading. It is dense but not repetitive, delivering maximum signal per word.

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

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

Given the absence of an output schema, the description fully explains return expectations: labelled identifiers, unresolved list, figi_candidates for ambiguous matches, and graceful degradation when GLEIF/OpenFIGI are down. For a tool handling two entity types with complex lookup chains, this leaves no gap that would prevent an agent from calling 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?

The schema already covers both parameters at 100% description coverage. The description nonetheless adds critical guidance: for 'value', it explicitly instructs to pass the entity name only, warns against including security-class words for bonds, and gives concrete examples for both company and drug inputs. This goes far beyond the schema and prevents common misuses.

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 immediately gives concrete example queries and states the core purpose: resolve a user-spoken name to the canonical/official identifiers other tools require. It explicitly positions itself as the first step when you have a name but need an ID, sharply distinguishing it from likely siblings like entity_profile which would use an ID after resolution.

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

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

It provides explicit when-to-use guidance ('Use FIRST whenever you have a name but need an ID'), describes the two supported entity types with input format expectations, and includes nuanced instructions like passing the issuer name exactly as printed for bonds and avoiding trailing security-class words. It also clarifies graceful degradation when external services are unavailable.

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

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

Annotations already indicate readOnly, idempotent, and non-destructive behavior. The description adds that it probes each entity with ai_visibility_check and returns a ranked list with score, confidence, signal density, which is useful behavioral context 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?

The description is a two-sentence paragraph that front-loads the purpose and immediately explains the process. Every sentence adds value 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?

The description covers the purpose, method (uses ai_visibility_check), output fields, and typical use case. No output schema is provided, but the description mentions return fields, making it sufficiently complete for a comparison tool.

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

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

Schema coverage is 100%, so baseline 3 applies. The description does not add new parameter meaning beyond what is already in the schema (e.g., first entity is subject). No extra value to 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 clearly states the tool compares AI visibility across multiple entities side-by-side, using ai_visibility_check internally and ranking results. It distinguishes itself from single-entity tools like ai_visibility_check and generic compare_entities by focusing on AI presence audits.

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) and contrasts with single-entity queries, but does not explicitly exclude alternatives or mention when not to use it. The context is strong but lacks explicit when-to-use/when-not-to-use guidance.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds critical behavioral context: fans out to two services, bundlephobia first measurement can take 5-30 seconds, and partial failures degrade gracefully with a list of failed sources. 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 front-loaded with the core purpose. While long, every sentence adds meaningful information. Could be slightly more structured, but it is efficient for the complexity of the tool.

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

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

No output schema, but the description thoroughly details the return structure: summary block with specific fields, per-advisory detail, links, and alternative versions. Also covers edge cases like partial failures and timing. For a tool with 2 parameters and complex output, this is highly 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 covers both parameters with 100% description coverage. The description adds context: scoped packages are accepted for 'package', and 'version' defaults to latest when omitted. This adds value beyond the schema definitions.

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 is a composite check for npm packages, answering questions about safety, popularity, and size. It explicitly lists the resources consulted (deps.dev and bundlephobia) and the use cases, distinguishing it from any 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?

Explicit usage guidance: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. Also specifies limitations: 'NPM ecosystem only in v1' and mentions alternative tools for other ecosystems. Describes behavior on partial failures.

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, it details internal embedding model (BGE-base-en), window size (500-char overlapping), character cap (200K with truncation flag), and that offsets enable quote verification.

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

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

Three sentences: purpose, usage, technical detail. Front-loaded, 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?

Covers input, output implicitly (passages with offsets and scores), and technical limits. No output schema but description suffices for agent understanding.

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

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

Schema coverage is 100%, so description adds little beyond default values and examples. Adequate but not enhanced.

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 'Semantic search INSIDE a fetched record' with specific use cases (SEC 10-K, article) and output (passages with offsets and scores). It distinguishes from siblings like ask_pipeworx_grounded.

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 pairs with ask_pipeworx_grounded. Lacks explicit 'when not to use' but sufficient 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?

Annotations indicate readOnlyHint=false, idempotentHint=true, which aligns with description stating 'Create' and returning a new subscription id. The description adds valuable behavioral context: requires OAuth account, delivery channel limitations (sms 10/day cap, webhook auto-disable after 10 failures), and webhook signing details. 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 well-structured with logical sections for supported types and delivery channels, using bullet-like formatting. It front-loads the main purpose and return value. While slightly verbose, every sentence adds information 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?

The description covers authentication requirements, type-specific parameter details, delivery channel options with limitations, and return value. For a tool with 3 parameters and no output schema, it provides sufficient context for an AI agent to correctly invoke the tool and understand its behavior.

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

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

Input schema has 100% coverage with descriptions for all parameters. The description adds significant value by explaining type-specific parameter structures (e.g., items for sec_8k, topic for polymarket_edge) and providing detailed delivery channel semantics (webhook HMAC signing, sms verification). This goes beyond the schema's basic descriptions.

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

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

The description clearly states the tool 'Create a proactive monitoring subscription' and specifies the return value 'Returns the new subscription id'. It distinguishes from sibling tools like 'unsubscribe' and 'list_subscriptions' by focusing on creation.

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

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

The description provides explicit context for when to use the tool: for proactive monitoring with specific supported types (sec_8k, polymarket_edge, fred_series, etc.) and delivery channels. It notes a prerequisite (Pipeworx OAuth account) and limitations (sms cap, webhook auto-disable). However, it does not explicitly state when not to use this tool versus siblings, though the purpose is sufficiently distinct.

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 that it returns example questions drawn from the live catalog, with no side effects, and explains its behavior when called with or without arguments. 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 somewhat lengthy but well-structured: it opens with user-facing questions, defines the output, and gives usage instructions. It is front-loaded and every sentence adds value, though minor tightening could improve conciseness.

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 input (one optional parameter) and no output schema, the description fully covers the tool's purpose, input usage, and output characteristics (category-bucketed examples with tool shapes). It is complete for its role.

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 one optional parameter 'topic' described. The description adds examples ('finance', 'pharma', 'betting') and explains the effect of omitting vs. providing the parameter, enriching the schema's 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 that the tool returns category-bucketed example questions with tool+argument shapes, serving as an onboarding entry point. It distinguishes itself from sibling tools (e.g., ask_pipeworx, entity_profile) by being the first tool to use when unfamiliar with Pipeworx.

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

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

The description explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you', providing clear when-to-use guidance. It also explains how to call with or without the topic parameter, and mentions its role in learning meta-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 annotations (readOnlyHint=false, destructiveHint=false), the description adds crucial context: ownership enforcement, deactivation behavior, and preservation of historical events. 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?

Two sentences with zero waste. The first sentence states the action, the second explains constraints and effects. Every word adds value.

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

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

For a single-parameter cancellation tool, the description is fully complete. It covers the action, constraints, effect on data, and cross-references a related tool (recent_alerts). No 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%, so baseline is 3. The description adds that the id comes from subscribe, which is helpful but already implied by the schema's description. No significant additional meaning beyond the schema.

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

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

The description clearly states the action ('Cancel a subscription by id') and the resource (subscriptions), distinguishing it from siblings like subscribe and list_subscriptions. It also adds behavioral nuance about ownership and deactivation.

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

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

It explicitly states the ownership constraint ('you can only cancel your own subscriptions') and explains the effect (deactivation, not deletion), referencing recent_alerts for historical data. It could be improved by explicitly stating when not to use it, but the constraint is clear.

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

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

Beyond the annotations (readOnly, idempotent), the description discloses key behaviors: the verdict set, the exact percent-delta math for financial claims, the fall-through pipeline, and the crucial distinction between could_not_verify (check did not happen) vs unsupported (no source exists). This adds substantial context and directly warns callers not to treat verification errors as evidence.

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 each segment earns its place: examples, use-case, routing paths, return format, and a critical caveat. It is structured logically, though the 'Replaces 4–6 sequential calls' clause is somewhat promotional. Still, it's appropriately sized for the tool's complexity.

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

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

Given no output schema, the description fully explains return values, verdict types, citation format, and error semantics. It covers both financial and non-financial claim paths, making the tool's behavior predictable even without structured output 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 meaningful semantics: tolerance_pct overrides the implied tolerance, gives a recommended range for hallucination detection (1–2), and states the default cap of 5%. The claim parameter is illustrated with concrete examples. This goes well beyond the schema's bare 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 concrete natural-language query examples ('Is it true that…', 'fact check'), then states the core function: natural-language claim verification against authoritative sources. This distinguishes it from sibling research/QA tools by emphasizing fact-checking of user assertions, not open-ended discovery.

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

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

It explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' It also describes the two routing paths (SEC EDGAR for financial claims, grounded pipeline for everything else), which tells the caller when this tool is applicable. It lacks explicit exclusions (e.g., when to prefer ask_pipeworx), but the claim-verification scope is well-defined.

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