Ine Pt

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

Annotations already convey read-only, open-world, idempotent, non-destructive. Description adds that it probes multiple LLMs, uses default free model, requires Anthropic API key (paid separately), and returns per-model details. 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?

Three concise sentences, front-loaded with action and output. Every sentence adds unique value: what it does, default vs. paid option, return structure, use cases. 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?

Without output schema, description adequately explains return format (per-model {score, confidence, signals, raw_response} + combined view). Covers parameter usage and use cases. Could mention rate limits or cost implications more, but overall sufficient for a probing 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 covers all 4 parameters with descriptions (100% coverage). Description adds value by clarifying default model, the role of _apiKey (BYO key, direct billing), and the context parameter's function for 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 verb 'probe' and the resource 'LLMs', specifies the output (visibility score 0-100 per model with detailed fields), and distinguishes from sibling tools by focusing on AI visibility auditing rather than direct queries or research.

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

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

Explicitly states use cases like AI-marketing audits, pre-launch brand checks, competitive monitoring. Implicitly distinguishes from siblings by purpose. Could improve by stating when not to use (e.g., for simple factual queries), but the context is clear enough.

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 supply readOnlyHint=true and destructiveHint=false. The description adds valuable behavioral context: it routes to many tools, fills arguments on behalf of the user, and returns stable pipeworx:// citation URIs. It also notes performance ('one fast call') and that it works on every tier. This goes beyond the annotations though slight missing details (e.g., error behavior) prevent a 5.

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

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

The description is long but every sentence earns its place: it front-loads the priority directive, then provides scope, mechanics, trigger phrases, examples, and escalation paths. Structure is logical and scannable, with no redundant or filler text.

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 is a broad router with a simple input (one question) and no output schema, the description covers the output format ('structured answer with stable pipeworx:// citation URIs') and mentions alternatives for edge cases. It lacks details about possible clarifications or failure modes, but for the tool's scope, this is reasonably complete.

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

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

Schema coverage is 100%, and the description adds no additional parameter semantics beyond the schema. The examples in the description mirror those in the schema. Per the rubric, high schema coverage means a baseline of 3 is appropriate; no extra nuance is provided in the description.

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

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

The description clearly states what the tool does: it routes factual questions to the appropriate one of 5,529 tools across verified sources, fills arguments, and returns structured answers with citations. Specific domain areas are listed, and it distinguishes itself from siblings like ask_pipeworx_grounded and deep_research by explicitly naming when to step up.

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

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

Provides explicit when-to-use guidance: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and identifies trigger phrases like 'what is', 'look up', 'find'. Also gives clear alternatives for more advanced needs (ask_pipeworx_grounded for hallucination-resistant answers, deep_research for broad/multi-part questions), making usage boundaries unmistakable.

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?

Given annotations declaring readOnlyHint, idempotentHint, and destructiveHint=false, the description adds context about the experimental nature, that it may differ from stable when candidates are active, and that it currently matches ask_pipeworx exactly. It also clarifies it is a full working router, not a stub. This aligns with annotations and adds value.

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 moderately concise, with all sentences contributing relevant information: what it is, current status, usage, and caveat. It is front-loaded with the definition. Slight lengthiness from the tool count detail but acceptable.

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 effectively covers the tool's purpose, current behavior, and usage context, and refers to the same response shape. Combined with the comprehensive schema and annotations, it gives a complete picture. It could mention return format but the schema and 'same response shape' suffice.

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

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

Schema coverage is 100% with detailed descriptions of all six parameters (question and aliases). The description mentions 'same arguments' but adds no new parameter-level detail. Since the schema fully documents parameters, a baseline of 3 is appropriate, though the description doesn't enhance semantics beyond that.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx, a universal router with 5,529 tools, and states its function. It distinguishes it from the stable ask_pipeworx by noting it has experimental routing improvements, which is a specific and clear purpose.

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 instructs to use it exactly like ask_pipeworx when wanting the newest routing, and explains that results are compared against the stable router. It also notes current state (no active candidate) and that it falls back to nothing, meaning it's a fully functional router. This provides clear usage context but no explicit exclusions.

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

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

Discloses important behavioral traits beyond annotations: return format including evidence verbatim quote and refusal reasons, plus the cost of an extra LLM call. Annotations already confirm read-only and idempotent, and the description adds valuable context on refusal behavior without contradicting them.

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

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

Three dense sentences pack purpose, behavior, and usage guidance without any waste. The description is front-loaded with the core value proposition and correctly scoped in length 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?

Despite having no output schema, the description fully specifies the return object and refusal variants, including the verbatim evidence field. It also covers the cost tradeoff and typical use cases, providing complete guidance for 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?

Schema coverage is 100% with detailed descriptions for the question parameter and its aliases. The description does not add parameter-specific details beyond what the schema already provides, so the baseline score of 3 is appropriate.

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

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

The description explicitly states this is a hallucination-resistant answer mode that extracts answers from tool results, clearly distinguishing it from ask_pipeworx. It names the resource (answer generation) and the specific behavior (grounding in evidence), making the tool's purpose unambiguous.

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

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

Provides explicit when-to-use guidance: for quoted, cited, or acted-on answers where facts must not be invented. It also gives exclusion criteria, indicating to prefer ask_pipeworx for casual lookups, and names the alternative directly.

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

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

Despite annotations already indicating read-only, idempotent, and open-world behavior, the description adds extensive behavioral detail: low-confidence resolution short-circuit, closed-market handling, wide-spread tradeability flag, resolver contract, parent event extraction, news fallback mechanics, and resolution-rule risk. This far exceeds what annotations convey.

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

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

The description is excessively long and dense, with many details that could be summarized or structured as an output schema. While front-loaded with the main purpose, it then dives into extensive detail (response shapes, resolver contract, etc.) that makes it hard to parse quickly. Conciseness is sacrificed for completeness.

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

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

The description is extremely comprehensive, covering input formats, output shape, edge cases (low confidence, closed markets, wide spreads), resolver behavior, parent events, news fallback, and resolution rule risk. Since there is no output schema, the description fully compensates by detailing response fields and 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?

Schema covers 100% of parameters with descriptions. The description adds value by explaining how the 'market' parameter is interpreted (slug, URL, or question text) and includes examples in the schema. The extra context for 'depth' and 'include_raw' is already in the schema, but the description reinforces key details.

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 researches a Polymarket bet by pulling Pipeworx data, and specifies input formats (slug, URL, question text) and output (evidence packet + comparison). However, it does not explicitly differentiate from sibling tools like polymarket_edges or polymarket_arbitrage, leaving the agent to infer uniqueness.

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 example use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z'), giving clear context for when to use. However, it does not mention when NOT to use the tool or suggest alternatives (e.g., for single-source queries or other sibling tools), limiting its 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 mark the tool as read-only, idempotent, etc. The description adds valuable behavioral details: off-calendar fiscal year handling, result sorting by primary metric, returned paired data with citation URIs, and data sources per entity type. 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 a single dense paragraph that front-loads example queries. It is concise but covers all key aspects. Minor improvement could be using bullet points for clarity, but overall well-structured.

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

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

Given the tool has two parameters and no output schema, the description fully explains input requirements, data pulled, output format (paired data + URIs), and edge cases (calendar handling). It is complete for an AI agent to select and invoke correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds significant context beyond the schema: for 'type', explains what data is pulled; for 'values', provides formatting examples and constraints (tickers/CIKs for company, names for drug). This elevates the score to 4.

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

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

The description explicitly states the tool performs side-by-side comparison of 2-5 companies or drugs, provides example queries ('X vs Y', 'compare', 'rank'), and names specific data sources (SEC EDGAR/XBRL for companies, FAERS for drugs). It clearly distinguishes from siblings by advising to prefer over sequential single-pack lookups.

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

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

The description gives explicit when-to-use guidance: queries involving comparison, ranking, 'vs', 'versus'. It states 'ALWAYS PREFER over sequential single-pack lookups', implying when not to use alternatives. However, it does not explicitly name sibling tools or provide when-not scenarios, so a 4 is appropriate.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description adds rich behavioral context: parallel decomposition, gap recovery, contradiction scanning, semantic excerpting, citation resolvability, and expected latency (15-90s). It provides a thorough picture of what happens during execution without contradicting any annotation.

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

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

The description is dense and information-packed; every sentence contributes useful detail, but it is a single wall of text without visual structure. It could benefit from paragraph breaks or bullet lists, but no sentence is wasted. This is effective but not maximally scannable.

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

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

With no output schema, the description fully compensates by explicitly listing the return fields (findings packet with verbatim evidence, confidence, source, fetched_at, pipeworx:// citation, gaps[], contradictions[], hop field, citation_uri). It also covers edge cases (unanswerable facets, unresolved citations) and performance expectations, making it complete for a complex tool.

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

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

Schema coverage is 100%, so both parameters are already well-documented. The description adds value by explaining the behavioral implications of depth choices ('quick=3 facets, standard=5 with gap-recovery, thorough=8 with iterative hop') and clarifies the paid tier for thorough. 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 clearly states the tool's verb+resource: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' and distinguishes it from siblings by explicitly noting it is NOT open-web search and recommending ask_pipeworx for single lookups. This makes the tool's unique role unambiguous.

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

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

The description gives explicit when-to-use and when-not-to-use guidance: 'For a single lookup use ask_pipeworx' and for breaking news 'prefer ask_pipeworx — it routes to live news APIs'. It also notes that deep_research returns empty gaps for topics outside the structured catalog, and explains the account/tier requirements. This is exemplary usage guidance.

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

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

Annotations declare readOnlyHint, idempotentHint, and destructiveHint; the description adds critical behavioral context: returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples)' and that each result is 'ready to call directly, no second schema lookup needed.' 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 front-loaded with purpose and usage, and every sentence contributes useful information. It is slightly verbose but not overly wasteful. A minor trim could improve conciseness without losing substance.

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 adequately explains return content (top-N relevant tools with schemas). It covers purpose, usage, behavior, and output format. All key aspects are addressed for a discovery tool with 6 parameters.

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

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

Schema coverage is 100% and descriptions already explain each parameter (including aliases). The description adds minimal parameter insight beyond the schema—only mentioning default/max limit in passing. The description's main value is about the output, not parameter semantics.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It enumerates numerous domains (SEC filings, FDA drugs, etc.) and explains that it returns the top-N relevant tools with complete schemas, making it distinct from siblings that perform specific analyses.

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 advises when to use the tool: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear, actionable guidance for selection among siblings.

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

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

Annotations already declare safe behaviors (readOnly, idempotent). The description adds rich behavioral context: parallel fan-out across five sources, specific data returns, USPTO PatentsView sunset (soft-fail), GDELT→GNews fallback, and LEI via GLEIF. 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?

Front-loaded with example queries and concise structure. Minimally redundant, though 'ALWAYS PREFER' could be trimmed. Every sentence adds value.

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

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

Despite lacking an output schema, the description thoroughly documents all return fields (cik, company_name, recent_filings with URIs, fundamentals sorted, patents, news, LEI), constraints (US public companies only, name resolution needs prior tool), and error handling (patents soft-fail). No gaps for expected use.

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

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

Schema coverage is 100% and the description adds critical meaning beyond property names: clarifies 'type' is limited to 'company', 'value' must be ticker or zero-padded CIK (not names), and provides examples. This eliminates ambiguity about accepted formats.

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

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

The description specifies a precise verb-resource pair ('full cross-source profile of a US public company') with concrete data sources and return fields, and clearly distinguishes from sibling tools like 'resolve_entity' (name resolution) and 'compare_entities' (comparison).

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 ('if the user asks for a holistic view') and when not to ('use resolve_entity first if you only have a name'), even recommending an alternative sibling tool.

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

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

Description mentions 'Delete' aligning with destructiveHint=true. Adds context about clearing sensitive data. No contradiction with annotations.

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

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

Two sentences: first defines action, second provides usage guidelines. No wasted words.

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

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

For a simple single-parameter tool with no output schema, the description covers purpose, usage, and relationships to siblings 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% and description does not add extra meaning beyond schema definition of 'key'.

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?

Clearly states verb 'Delete' and resource 'memory by key'. Distinguishes from siblings by referencing remember and recall.

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 (stale context, task done, clear sensitive data) and pairs with alternatives (remember, recall).

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 true and destructiveHint false. The description adds behavioral context: it fetches the page, extracts title/description/key links, emits standard markdown, and outputs a text blob ready for site-root. This goes beyond annotations without contradiction.

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

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

The description is two sentences plus a clear list of use cases. Every sentence earns its place, no redundant words, and front-loaded with the core purpose.

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

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

Given no output schema, the description adequately explains the output format (a single text blob in standard markdown). Parameters are well-documented, complexity is low, and the tool's behavior is fully described for an AI agent to select and invoke it correctly.

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

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

Schema coverage is 100% with both parameters described. The description adds meaning by mentioning default 25 and max 50 for max_links, and gives an example for url. 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 generates a production-ready llms.txt file for any URL, specifying the verb (generate), resource (llms.txt), and the target AI crawlers. It distinguishes from sibling tools by focusing on a very specific output format, with no similar tools in the sibling list.

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

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

The description explicitly lists three use cases (client indexing, own project drafting, competitor auditing), providing good context for when to use. It does not explicitly mention when not to use or alternatives, but the purpose is clear and sibling differentiation is strong.

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 read-only, idempotent, non-destructive. Description adds behavioral details: no keyword search endpoint, external code lookup needed, and behavior when dims slots are omitted (returns all values).

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 packed with essential information. First sentence states purpose, second provides detailed usage. No unnecessary words, front-loaded.

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

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

Fully covers all needed information for an agent: how to get indicator code, how to use dims, language parameter, and links to metadata. No gaps despite lack of output schema. Complete and self-contained.

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 has 100% description coverage, but description adds context: explains dims as dimension slot mapping, notes dims can be array, and explains varcd requires external lookup. Adds significant meaning 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?

Clearly states the verb 'Fetch' and resource 'data values for an INE indicator'. Distinguishes from sibling tool indicator_meta by noting that dimension codes come from there.

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 explains when to use (fetch data by indicator code) and when not (no keyword search, need external lookup). Gives guidance on optional parameters and the external dependency on www.ine.pt.

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

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

Annotations already indicate a safe, idempotent read operation. Description adds specific behavioral details: what data is returned (title, periodicity, unit, time range, full dimension-value list) and the intended usage sequence.

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 succinct sentences plus a brief note. No wasted words; each sentence adds crucial information: purpose, usage order, and parameter sourcing.

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

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

Despite lacking an output schema, the description adequately conveys what the tool returns, making it functional. Could optionally include response format, but not critical.

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 and enum. Description reinforces importance of varcd and how to obtain it, adding value beyond the schema.

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

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

The description clearly states it returns metadata for an INE indicator, listing specific fields (title, periodicity, unit, time range, dimensions with codes). It also distinguishes from the sibling get_indicator by advising to call it first.

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 instructs to call this before get_indicator to obtain valid dimension codes. Provides external lookup instruction for the required varcd parameter, acknowledging INE's lack of a search API.

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 provide readOnlyHint, idempotentHint, and destructiveHint. The description adds return field details but no behavioral traits beyond what annotations convey. 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?

Two concise sentences: first 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 no output schema, the description covers what the tool returns, when to use it, and leverages annotations. Complete enough given the context.

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

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

Schema coverage is 100% with the parameter 'include_inactive' fully described in the schema. The description does not add extra meaning beyond what the schema provides.

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

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

The description clearly states 'List the caller's active subscriptions' and lists the returned fields. It distinguishes itself from sibling tools like 'subscribe' and 'unsubscribe' through its focus on listing.

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

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

Provides explicit usage context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' Does not explicitly mention when not to use, but it's clear enough.

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 thoroughly discloses behavioral traits beyond the annotations, including the claim_token flow (filing without an account returns a token, which can be used later to check status), rate limits (5 per day), that it's free, and that it doesn't count against quota. Since annotations are sparse (all false), the description carries the full disclosure burden and does so well.

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 the description is longer than average, every sentence earns its place, covering purpose, usage, exclusions, claim workflow, and operational limits. It is front-loaded with the core purpose and structured logically from when-to-use to how-to-use, 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?

Given the tool has no output schema and moderate parameter complexity, the description provides comprehensive context: what the tool does, when to use it, when not to, what to include in the message, the claim_token flow for retrieving feedback status, and rate-limiting. This is sufficiently complete for an agent to invoke the tool correctly in a variety of scenarios.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining the claim_token lifecycle (filing without an account yields a token, and passing it back later checks resolution), which is a nuance not fully covered by the schema's parameter description. This practical usage scenario enhances 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 opens with a specific, action-oriented purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' This clearly defines the tool's resource (Pipeworx team/tools) and distinguishes it from the sibling research and query tools, which focus on data retrieval rather than feedback submission.

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

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

Explicit usage guidance is present: '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 provides an exclusion criterion, stating to file with a different server if the tool is not from this Pipeworx connection, which aids in tool selection.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false), the description adds valuable behavioral context: it states the data source (CF analytics-engine), privacy handling (no PII), and caching behavior (5min-1h depending on window). This fully informs the agent about side effects and data freshness.

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

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

The description is concise (three sentences) with the main action front-loaded. Every sentence adds value: the first states the output, the second lists use cases, the third explains the data source and caching. No superfluous words.

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

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

Given the single parameter and no output schema, the description adequately covers purpose, parameters, and behavioral traits. It could clarify how 'top' is determined (by call volume) but the phrase 'top tools, top packs, and total call volume' implicitly links them. An explicit ranking criterion would make it perfect.

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

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

The schema covers the single parameter 'window' with enum values and a description. The description adds semantic guidance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This helps the agent choose intelligently beyond just the enum options.

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 verb ('returns') and the specific resources ('top tools, top packs, total call volume') with time windows. It distinguishes itself from siblings by focusing on trending data derived from call volume, which is not covered by other tools like 'discover_tools' or 'entity_profile'.

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

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

The description provides three explicit use cases (discovering hot data, confirming canonical tools, checking alignment) that guide when to use the tool. It does not explicitly mention when not to use it or name alternatives, but the use cases are specific enough to imply appropriate and inappropriate contexts.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. The description adds behavioral details such as scanning top 200 markets, partition checks with thresholds, similarity filtering, placeholder removal, and fill check against live depth. 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 well-structured and front-loaded with purpose, but somewhat verbose with detailed technical explanations. Could be slightly more concise without losing value.

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

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

Despite no output schema, the description thoroughly explains the response format including opportunities array, partition_check fields, and fill_check results. Covers edge cases like low similarity and placeholder filters, making it 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 coverage is 100% with clear descriptions for event and topic. The description enriches each parameter with practical examples (slugs, seed questions) and explains behavior differences between modes.

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 arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It specifies the return type and differentiates 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?

Provides explicit guidance on when to use each mode: no args for trending scan, event for specific market (recommended), topic for cross-event scanning. Also advises when not to trade based on fill check and references polymarket_fill_risk 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?

No annotation contradiction. Annotations (readOnlyHint, idempotentHint) are consistent and the description adds extensive behavioral details: caching at KV level keyed on knobs, diagnostics for empty segments, and tradeable-edge knobs. This goes beyond annotations to help the agent understand what the tool does.

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 and dense, containing detailed model explanations and output structure. While it is well-structured with clear sections (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, etc.), it could be more concise. It is front-loaded with the core purpose.

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

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

Given no output schema and 9 parameters, the description is exceptionally complete. It explains the output structure (by_segment, diagnostics), the different model families, and the meaning of fields like edge_pp_net. This fully compensates for the lack of output schema.

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

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

Schema coverage is 100% so baseline is 3. The description adds context about tradeable-edge filters and how parameters like min_liquidity and max_spread_pp are used, but doesn't add significant meaning 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 clearly states the tool scans Polymarket markets to find opportunities where Pipeworx data disagrees with market price. It specifies the resource (Polymarket markets), action (scan and return), and the unique approach of detecting disagreements.

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 for 'what should I bet on today' and emphasizes discovering opportunities without paging hundreds of markets. While it doesn't explicitly compare to sibling tools like polymarket_arbitrage, it provides clear context for when to use this tool over paging through markets manually.

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

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

The description extensively details behavior beyond annotations: it reads snapshots, returns three arrays (tracked, expired, snapshot_dates), explains computation of trend and decay_pp_per_day, and notes limitations like 60-day TTL and cache-miss gaps. 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 fairly long but well-structured: starts with the core question, then details response components, and ends with limits. Every sentence adds value, though some internal details (like negative = SELL YES) could be condensed.

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

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

With no output schema, the description fully explains the response structure (tracked, expired, snapshot_dates) and their fields. It covers parameters, constraints, and edge cases, making it complete for an agent to understand the tool's capabilities and outputs.

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 the effect of 'days' (lookback, default 14, clamp 2-30) and 'window' (snapshot family with examples like 24hr, 1wk, 1mo), providing context beyond the schema's brief 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's purpose: tracking edge persistence and decay over time from daily snapshots. It uses specific verbs ('answers', 'returns') and distinguishes from siblings like polymarket_edges and polymarket_arbitrage by focusing on time-series analysis of 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 context on when to use the tool by explaining the difference between a fresh wide edge and a 3-week-old wide edge. It implies using this for edge aging analysis, but does not explicitly mention alternatives like polymarket_edges for current edges.

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, non-destructive. Description adds context on return values (verdict, thin legs, forced directional risk) and partial fill behavior, enhancing transparency 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?

Description is long but well-structured with clear sections for single-market and basket modes, and a bolded usage note. Could be more concise, but all sentences add 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?

No output schema, but description lists all return fields for both modes, explains the verdict, and warns about risks (thin books, partial fills, directional exposure). Comprehensive for a complex tool with two modes.

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 meaning by explaining size_usd interpretation per mode (spend on buys vs target proceeds vs settlement notional), defaults, and side auto-detection logic for baskets.

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 it is a realizable-vs-theoretical edge check against live CLOB order-book depth, distinguishing between single-market and basket modes. It differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by specifying when to use this tool.

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

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

Explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. Also warns against partial basket fills converting arbs into unhedged directional positions, providing clear when-not-to-use guidance.

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

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

Beyond the annotations (read-only, idempotent), the description discloses detailed behavior: two modes, response structure with leg-by-leg prices and matched spreads, compatibility_warning conditions (non-equivalent bet shapes or unrelated events), temporal_alignment checks, and skipped cross-type/subtype counters. This surpasses annotation coverage.

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

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

The description is verbose but well-structured with clear sections for overview, modes, response, and safety fields. It front-loads the purpose, but could be more concise without losing critical 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 lack of an output schema, the description thoroughly explains the response structure (venue leg-by-leg prices, matched spreads with top_spreads_pp, compatibility_warning, temporal_alignment, skipped_cross counters). It also covers input modes and edge cases, making the tool fully understandable.

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 each parameter has a description, but the tool description adds context: the topic parameter lists all 10 pre-mapped shortcuts, and explains that kalshi_event_ticker and polymarket_event_slug override the topic mapping. This enriches understanding beyond the schema.

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

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

The description clearly states the tool computes the cross-venue spread between Kalshi and Polymarket for the same resolving question, with two explicit modes (topic shortcuts and explicit tickers). It is distinct from sibling tools like polymarket_arbitrage which focus on single-venue 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 explains when to use macro shortcuts vs explicit tickers, and warns that pre-mapped topics often yield compatibility warnings and are not automatically tradeable. It provides context for usage but does not explicitly exclude alternative tools.

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

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

Annotations already declare readOnly, idempotent, non-destructive. Description adds scoping detail and listing behavior, providing 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?

Three sentences front-load purpose and include usage context, scoping, and pairing. No filler; every sentence earns its place.

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

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

For a simple read tool with one optional parameter and safety annotations, the description covers purpose, usage, scoping, and pairing. Minor gap: no mention of return format or error cases.

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 critical semantics: omitting key lists all saved keys. This clarifies a behavior not obvious from the schema alone.

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

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

Description uses specific verbs ('Retrieve', 'list') and distinguishes from siblings: 'remember' and 'forget'. Clearly states the resource (saved values) and the two modes of operation.

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

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

States when to use: 'look up context the agent stored earlier', and mentions scoping. Lacks explicit when-not-to-use or alternatives, but pairing with siblings is implied.

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 note readOnlyHint, idempotentHint, and openWorldHint. The description adds valuable context: setting mark_read:true flags events as read, affecting future calls; and it specifies the return format (source, citation_uri, payload). 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 concise at 5 sentences, with the main action front-loaded. It efficiently covers purpose, return fields, filter options, and a behavioral note (mark_read). The inclusion of an alternative access point is slightly extraneous but not harmful.

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 adequately explains return fields and filter capabilities. It covers all 5 parameters with context. Missing details like default behavior for 'unread_only' or pagination are minor given the optional nature and schema descriptions.

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, baseline is 3. The description adds meaning by providing examples (e.g., 'sec_8k' for type), clarifying format for 'since' as ISO timestamp, and explaining the effect of 'mark_read.' This 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 uses the specific verb 'Pull' with the resource 'fired events from your subscription feed,' immediately clarifying the tool's function. It distinguishes itself from sibling tools like 'list_subscriptions' by focusing on events rather than subscription lists, and includes details about returned fields (source, citation_uri, payload).

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?

While the description mentions 'Polls work fine' and provides an alternative endpoint for scripts, it does not explicitly state when to use this tool versus siblings like 'recent_changes' or 'list_subscriptions.' The guidance is implied but lacks clear exclusions or comparisons.

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 context beyond annotations: fans out to multiple APIs, soft-fails for USPTO, rate-limit fallback, and describes return structure. No contradictions, though pagination details are omitted.

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?

Dense single paragraph front-loads examples and key behavior. Efficient but could benefit from more structure like bullet points separating sources.

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, description adequately covers return format (changes grouped by source, total_changes, citation URIs). All aspects of the complex tool are addressed.

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. Description adds minimal extra meaning beyond schema, but provides context on how parameters interact with sources.

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 it's a change feed for a company in the last N days/weeks/months, provides example queries, and distinguishes from sibling tool entity_profile for static profiles.

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

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

Explicitly says when to use (queries like 'what's new with X'), when not to use (use entity_profile for static profile), and describes fallback behavior between GDELT and GNews.

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 idempotentHint=true, non-destructive. The description adds valuable context: scoping by identifier, persistence differences (authenticated vs anonymous, 24-hour limit), and pairs with recall/forget. 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?

Three sentences, none wasted. Front-loaded with purpose, then usage, then storage details. Efficient and clear.

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 low complexity (2 required params, no output schema), the description fully covers purpose, usage, persistence, 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%, but the description adds examples for key and value (e.g., 'subject_property', 'any text'), which enriches the semantics beyond the schema's bare descriptions. A 5 would require more detailed parameter constraints.

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 saves data for later reuse, with specific verbs ('Save', 'Store') and resource ('key-value pair'). It distinguishes from siblings recall and forget by mentioning them explicitly.

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 (discover something worth carrying forward) and mentions paired tools (recall, forget). However, it lacks explicit 'when not to use' statements, which would make it a 5.

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

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

The description goes beyond annotations by disclosing that it cascades through multiple lookup endpoints, degrades gracefully when GLEIF/OpenFIGI are unavailable, and explicitly reports unresolved identifiers under `unresolved`. It also clarifies that identifiers are labeled with their source, adding transparency about data provenance. This is substantial behavioral context not present in the readOnly/openWorld/idempotent hints.

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

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

The description is detailed and well-organized, with examples leading into a clear purpose statement and structured supported-types sections. While long, every sentence contributes necessary information such as fallback behavior and output specifics, making it dense rather than padded. It could be tightened but remains effective.

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 takes on the responsibility of detailing return values, which it does comprehensively: for company it lists CIK, ticker, LEI, FIGI with source labels and unresolved handling; for drug it specifies RxCUI, ingredient, brand, and citation. It also covers graceful degradation and the cascading nature of lookups, ensuring the agent understands failure modes. Given the tool's complexity, this is complete.

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

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

The input schema already provides 100% coverage with clear descriptions for both `type` and `value`, including examples for ticker, CIK, and drug names. The tool description enriches this by explaining the output structure and enrichment process, but it does not add additional parameter-level semantics beyond what the schema already states. Baseline 3 is appropriate given the schema's thoroughness.

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 resolves user-spoken names into canonical identifiers required by other tools, with specific verbs and resources. It distinguishes itself from siblings like entity_profile by emphasizing it provides IDs, not profiles. Example queries illustrate the purpose effectively.

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 instructs to use this tool 'FIRST whenever you have a name but need an ID,' providing a clear when-to-use directive. It does not explicitly mention when not to use it or alternatives, but the context of replacing manual lookups and cascading suggests it is the preliminary step for subsequent tools. The focused guidance earns a 4.

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 explains the tool probes each entity with ai_visibility_check, ranks results, and surfaces most/least recognized. This adds behavioral context beyond the annotations (which already indicate read-only, idempotent, non-destructive). 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?

Concise, well-structured description: core function, process, usage context, and output summary. 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?

Despite no output schema, the description clearly states the return format (ranked list with score, confidence, signal density). Given moderate complexity and complete annotations, description is fully adequate.

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 baseline is 3. Description adds minimal extra semantics (e.g., first entity is the subject). The schema already explains all parameters adequately.

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 verb 'compare' and resource 'AI visibility' across multiple entities, distinguishing it from sibling tools like ai_visibility_check (single entity) and compare_entities (general comparison).

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?

Describes use case for competitive AI-marketing audits with an example question. While it does not explicitly state when not to use, the context implies it is for batch comparisons, which differentiates it from single-entity alternatives.

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

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

Beyond the annotations (read-only, idempotent), the description adds critical behavioral details: the tool fans out across external services, may experience delays (5-30s for bundlephobia), handles partial failures gracefully, and specifies the return structure (summary block, details, links, alternatives).

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

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

The description is a single paragraph but effectively front-loads the core purpose. It is dense with information but remains readable. A structured format with bullet points could improve scannability, but the current form is acceptable.

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 specifies the return type (summary block with fields, advisory details, links, alternative versions). It also covers limitations (NPM only), timing behavior, and error handling (sources_failed). The tool's full behavior is well-documented.

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

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

The schema covers both parameters with 100% coverage, describing package name format and version default. The description minimally adds context by confirming the version default and implying that the package parameter is an npm package, but doesn't significantly enhance understanding beyond the schema.

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

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

The description clearly states the tool's function: a composite check for npm packages, combining license, advisories, version history, and bundle size data from multiple sources. It distinguishes itself by specifying the NPM-only scope in v1 and directing non-NPM packages to another tool.

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

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

The description explicitly recommends using this tool when an agent asks about a package's safety, popularity, or size, and gives a concrete example ('what does adding lodash cost me'). It also clarifies the NPM-only limitation and mentions partial failure handling.

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

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

Beyond annotations (readOnly, idempotent), description discloses internal details: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation flag. Also mentions character offsets for 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?

Four sentences, front-loaded with purpose, then usage, then technical details. No redundant or extraneous information.

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

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

Explains return values (passages, offsets, scores) and truncation behavior. Lacks explicit error handling info but adequate for a simple retrieval 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 good descriptions. Description adds example queries but does not significantly enhance parameter understanding. 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?

Clearly states 'semantic search INSIDE a fetched record' with specific examples (SEC 10-K, article). Distinguishes from sibling tool ask_pipeworx_grounded which fetches the record, while search_within operates on already-fetched text.

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

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

Explicitly says when to use (record too big for prompt) and when not to use (alternatively, pair with ask_pipeworx_grounded for fetch+ground workflow). Provides clear context for agent decision.

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 include idempotentHint=true, readOnlyHint=false, destructiveHint=false, openWorldHint=true. The description adds behavioral details beyond annotations: OAuth requirement, delivery channel limits (10/day SMS), webhook signing, auto-disable after failures. 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 well-structured with the purpose first, then requirements, types, and delivery channels. It is moderately long but efficient, with most sentences adding necessary information. Slight room for trimming but overall 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?

Given the complexity (3 parameters, nested objects, no output schema), the description covers requirements, type-specific filters, delivery options, and limitations. It lacks explicit error handling or return format details but is adequate for invocation.

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

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

Schema coverage is 100%, but the description adds significant meaning with detailed examples for each type and delivery channel, constraints (phone must be verified, email validation, webhook HTTPS requirements). This goes 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 creates a proactive monitoring subscription to a live-data event stream and returns the new subscription id. It distinguishes from sibling tools like 'list_subscriptions' and 'unsubscribe' by specifying creation and listing supported types.

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 requirements (Pipeworx OAuth account, not for anonymous/BYO) and details supported types and delivery channels. While it doesn't explicitly exclude alternatives, the context is clear.

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

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

Annotations already declare the tool as read-only, open-world, idempotent, and non-destructive. The description adds significant behavioral context: it is an onboarding tool that returns structured example questions with tool+argument shapes. 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 that front-loads key information (aliases, purpose). While it is not overly long, it could be more scannable with bullet points for the categories, but it efficiently conveys all necessary details without fluff.

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

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

Given the tool's role as an onboarding entry point and no output schema, the description adequately explains what the output contains (category-bucketed example questions with tool+argument shape). It also mentions the live catalog of thousands of tools. Minor missing details like output format or pagination are acceptable for this tool type.

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

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

Schema coverage is 100% with the topic parameter description. The description adds meaningful context by listing example values (finance, pharma, betting) and explaining that omitting topic gives a cross-category spread. This goes beyond the schema's basic focus area list.

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 the onboarding entry point that returns category-bucketed example questions with exact tool and argument shapes. It explicitly distinguishes from siblings like ask_pipeworx (which answers questions) and discover_tools by positioning itself as the first call for understanding Pipeworx's capabilities.

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

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

The description explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. It also explains the optional topic parameter to focus the results. While it lacks explicit when-not-to-use scenarios, the guidance is clear and sufficient for an onboarding tool.

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

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

Discloses that the row is deactivated (not deleted) and that historical events remain available via 'recent_alerts'. This adds behavioral context beyond annotations, which already indicate idempotency and non-destructiveness.

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: first states purpose, second provides key behavioral details. No fluff, efficiently front-loaded.

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

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

Covers purpose, ownership, and data lifecycle. Missing error handling details (e.g., invalid id), but the tool is simple and idempotent, so the description is largely 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 description of the 'id' parameter. The description adds no new semantic information beyond what the schema provides, meeting the baseline for high coverage.

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

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

The description clearly states the action (Cancel a subscription by id) and the resource (subscription). It is distinct from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

Specifies ownership enforcement and that the subscription is deactivated, not deleted. Implicitly guides use for own subscriptions only, though no explicit alternative or when-not-to-use is given.

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

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

Beyond the readOnly/idempotent annotations, the description adds critical behavioral detail: could_not_verify means the check did not happen and must not be treated as evidence, unsupported means no source coverage, and financial claims use exact percent-delta math. This materially improves the caller's ability to interpret results correctly.

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

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

The description is longer than average but front-loaded with trigger examples and 'Use whenever'. Each subsequent section — routing, return value, and caller warnings — earns its place, and the formatting makes it easy to scan. The complexity of the tool justifies the length.

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

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

With no output schema, the description compensates well by enumerating the possible verdicts, the return components (actual value, pipeworx:// citation, reasoning), and the meanings of error-related verdicts. The routing detail and the note that it replaces 4–6 sequential calls give a complete picture for agent invocation.

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

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

The input schema already provides full descriptions for both parameters (claim and tolerance_pct) with examples, achieving 100% schema coverage. The description adds context about tolerance being implied and capped at 5, but this information is also in the schema, so it does not substantially elevate the parameter semantics beyond the baseline.

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

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

The description leads with explicit trigger phrases ('fact check', 'verify the claim that…') and states the core function: natural-language claim verification against authoritative sources. It clearly distinguishes this from sibling tools by specifying it returns a verdict (confirmed / refuted / etc.) rather than general information.

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 whenever the agent needs to check whether something a user said is factually correct,' which is a strong when-to-use signal. It also differentiates routing for company-financial vs other claims. However, it does not explicitly name alternative tools or give a when-not-to-use case, so it stops short of a 5.

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