Pulsedive

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

The description adds significant behavioral context beyond annotations: it clarifies the default model (Workers AI, free) and the cost model for Anthropic (BYO key, pay directly), the return format (per-model + combined), and the role of the context parameter for disambiguation. This enhances the agent's understanding of side effects and costs.

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 (4 sentences) and front-loaded: first sentence states the core action and output, second adds model details, third describes return, fourth lists use cases. No redundancy or filler.

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

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

The description covers the main aspects: input (entity, models, apiKey, context), output (per-model and combined view), and use cases. There is no output schema, so the description adequately explains the return structure. However, it does not mention error scenarios, rate limits, or case sensitivity for model names, which could be gaps for complex usage.

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. The description adds value by explaining the default model, the purpose of '_apiKey' (pass-through to Anthropic), and how 'context' helps disambiguate. 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 clearly states the tool probes LLMs for knowledge about an entity and scores visibility (0-100) per model. It specifies the default model and optional Anthropic probing. However, it does not explicitly differentiate from sibling tools like 'scan_competitor_ai_presence', which may have overlapping functionality.

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 use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') but does not specify when not to use the tool or suggest alternatives. The context is clear but lacks exclusion criteria.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds context about routing to multiple tools and returning structured answers with pipeworx:// citation URIs, 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?

The description is well-structured with key information front-loaded. Every sentence adds value, making it appropriately sized for the tool's complexity.

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

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

Given the tool's complexity (6 parameters, no output schema), the description provides sufficient context: it explains what the tool does, when to use it, what it returns, and gives extensive examples. It is complete for an entry-point 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 the schema already documents all parameters and their aliases. The description adds example questions but does not provide additional semantic detail about parameters beyond what the schema offers.

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 routes questions to 5,008 tools across 1,318 sources and returns structured answers with citations. It distinguishes itself from sibling tools by specifying it is the default entry point and should be preferred over web search.

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

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

Explicitly says 'PREFER OVER WEB SEARCH' and provides guidance on when to step up to ask_pipeworx_grounded or deep_research. It also lists example queries and types of questions suitable for this tool.

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

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

Annotations provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds behavioral details: it is experimental, applies source-preference ranking, and is a complete working router. It does not contradict annotations, and the added context about being beta and live candidate improvements is valuable beyond the annotations.

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

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

The description is three sentences, each serving a purpose: identifying as beta, explaining the improvement, and giving usage guidance. It is well-structured and front-loaded with the key identity. Slightly longer than necessary but efficient.

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

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

Given the tool's complexity (universal router with 5,008 tools) and the absence of an output schema, the description adequately covers identity, differences from stable, usage instructions, and behavior. It does not detail return values, but the 'same response shape' reference provides enough context for agents familiar with ask_pipeworx.

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

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

The input schema describes all parameters with 100% coverage, including aliases. The description adds that it uses the same arguments as ask_pipeworx but does not provide additional semantic meaning beyond what the schema already covers. Baseline of 3 is appropriate.

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

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

The description clearly states it is a beta version of ask_pipeworx, an identical universal router with the same 5,008 tools, arguments, and response shape. It distinguishes itself by including candidate routing improvements such as source-preference ranking, making it clear what the tool does and how it differs from siblings.

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

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

Explicitly instructs to use it exactly like ask_pipeworx when wanting the newest routing, and notes that results are compared against the stable router. It also clarifies that it has no fallback, being a full working router, which guides when to choose this over the stable version.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds behavioral context: it costs an extra LLM call, returns explicit refusal reasons, and uses grounding. 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?

Well-structured with key info front-loaded. However, it is somewhat lengthy (multiple sentences). Each sentence is informative, so it earns its place, but could be trimmed slightly.

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

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

Despite no output schema, the description fully explains the return format (answer, evidence, confidence, source) and refusal reasons. Also mentions cost. Complete for a grounded question-answering 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 6 parameters (all aliases for question). Description notes 'Accepts query, q, prompt, text, input as aliases' but this is already in schema descriptions. Adds no new meaning beyond the schema, so baseline 3.

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

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

The description clearly states it is a 'Hallucination-resistant answer mode for high-stakes reads' and specifies that it extracts answers using only the tool result. It distinguishes itself from its sibling 'ask_pipeworx' by noting the difference in cost and use cases.

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

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

Explicitly says 'Use whenever an answer will be quoted, cited, or acted on' and gives examples like financial verdicts, legal claims. Also advises to 'prefer ask_pipeworx for casual lookups', providing clear when-to and when-not-to 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 only provide readOnlyHint, idempotentHint, and destructiveHint=false. The description adds extensive behavioral context: market resolution, classification, fan-out logic, response shapes, error handling (low confidence, closed markets, wide spreads), and resolution rule risk. This far exceeds the annotations' coverage.

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

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

The description is long but well-structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.). Every sentence adds value, though it could be more concise. The structure aids scanning for agents.

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 return fields (market, analysis, evidence, resolver contract, parent event, news fields) and edge cases (low confidence, closed markets, wide spreads, resolution rule risk). It is fully complete for an agent to understand the tool's 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 coverage is 100% with descriptions for all three parameters. The description adds value by explaining how depth ('quick=2-3 evidence sources, thorough=full fan-out') and include_raw (controls payload size) affect behavior, beyond the schema's basic descriptions.

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

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

The description clearly states it researches a Polymarket bet by pulling Pipeworx data, with specific verb 'research' and resource 'Polymarket bet'. It distinguishes from sibling tools like polymarket_edges by focusing on a single bet and providing evidence, not edge tracking.

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

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

The description explicitly says when to use it ('should I bet on X', 'what does the data say about Y', 'is there edge in Z'). While it doesn't explicitly state when not to use it, the sibling tool list provides context, and the description implies usage scenarios clearly.

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 discloses that for companies it pulls the latest 10-K financials from SEC EDGAR/XBRL with correct fiscal year handling, and for drugs it pulls FAERS data. It states results are sorted by primary metric and returns citation URIs. Annotations confirm read-only, open-world, and idempotent behavior, with 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. Every sentence provides value: usage guidance, data sources, sorting behavior, and efficiency claim. No redundant or filler language.

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 parameter simplicity (2 params) and no output schema, the description fully explains what data is returned for each type, how results are ordered, and that citations are included. It also highlights the efficiency gain (replaces 8-15 sequential lookups). The tool's behavior and output are clearly communicated.

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: for 'company' it lists specific financial metrics (revenue, net income, cash, debt) and for 'drug' it lists counts (adverse events, FDA approvals, trials). Values parameter is explained with concrete examples and required formats (tickers/CIKs or drug names). This goes well beyond the schema enums and types.

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

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

The description clearly states the tool performs side-by-side comparison of 2-5 companies or drugs. It lists example queries and distinguishes itself from sequential single-pack lookups. The verb 'compare' and resource 'entities' are explicit, and the scope is well-defined.

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 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' providing strong guidance for when to use this tool. It also specifies the types of entities and metrics retrieved, leaving no ambiguity about appropriate usage.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds rich behavioral context: decomposition into facets, parallel routing to 5,008 tools, output format (findings packet with verbatim evidence, confidence, source, fetched_at, citations, gaps[], contradictions[]), hop field, semantic excerpting, and expected latency. 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 lengthy but every sentence adds value. It front-loads the account requirement and key guidance. Could be slightly more structured (e.g., bullet points for depth levels) but remains efficient and well-organized.

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

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

Given the tool's complexity and the absence of an output schema, the description covers all necessary aspects: prerequisites, alternative tools, usage scenarios, internal mechanism, output structure, edge cases (gaps, contradictions), and performance considerations. No gaps in contextual completeness.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning: explains depth levels (quick=3, standard=5, thorough=8) and their behaviors (gap recovery, contradictions scan, iterative hop). For the question parameter, it clarifies that broad/multi-part questions are fine. This adds value 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 what the tool does: 'Grounded multi-source research across Pipeworx's 1318 STRUCTURED data sources in ONE call'. It distinguishes from siblings like ask_pipeworx with explicit examples and contrasts (e.g., 'not open-web search', 'for a single lookup use ask_pipeworx').

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

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

Provides explicit when-to-use and when-not-to-use guidance: 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. Also addresses account requirements and an alternative tool if not signed in.

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. The description adds that it returns full input schemas with curated examples and that results are ready to call directly, which goes beyond the annotations to clarify behavior. Slightly more detail on what happens with ambiguous queries would push it higher, but it's already good.

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 long but front-loaded with the main purpose. Every sentence serves a purpose, though a slight trimming of the domain list could make it more concise. Still, it's well-structured and informative.

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

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

Despite lacking an output schema, the description fully explains what the tool returns: top-N relevant tools with names, descriptions, and full input schemas (with examples), and that each result is ready to call directly. It also mentions the default limit and max. This is complete for a discovery tool.

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

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

Schema coverage is 100%, but the description adds value by explaining that multiple aliases (task, q, search, description) are accepted for the same query parameter, and by providing example queries. This clarifies the natural language input format 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 discovers tools by describing a data or task, and lists many example domains. It distinguishes itself from sibling tools by instructing to call this first to see the option set, making the purpose unmistakable.

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

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

The description explicitly says when to use this tool: 'Use when you need to browse, search, look up, or discover what tools exist for...' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear usage context and implies when not to use it.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false. The description adds valuable context beyond annotations: it fans out across multiple sources (SEC, XBRL, USPTO, news, GLEIF), mentions a potential sunset for USPTO PatentsView API (soft-fails until reactivated), and details the return fields. There is 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 somewhat long but well-structured, front-loading with examples and then detailing the data sources and return fields. It could be slightly more concise by reducing the number of example queries, but every sentence adds value. The structure is logical.

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

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

Given the tool's complexity, it has only 2 parameters with full schema coverage, rich annotations, and no output schema. The description explains the return fields (cik, company_name, recent_filings, fundamentals, patents, news, LEI) and data sources. It also mentions the USPTO soft-fail. While it doesn't cover error handling or rate limits, the provided information is sufficient for an agent to understand the tool's behavior and output.

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

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

Schema coverage is 100% with descriptions for both parameters (type enum with only 'company', value with ticker or CIK). The description adds context about ticker vs CIK (zero-padded) and clarifies that names are not supported, which is beyond the schema. It also mentions that type 'company' is the only supported entity type today.

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

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

The description clearly states the tool provides a full cross-source profile of a US public company, with examples of user queries ('Tell me about X', 'research Acme', etc.) and lists the data sources (SEC EDGAR, XBRL, USPTO, news, GLEIF). It distinguishes itself from siblings by explicitly stating 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.'

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 guidance on when to use (for a holistic view, when user asks for a company profile) and when not to use (if only a name, use resolve_entity first). It also directs the agent to prefer this tool over chaining other lookups.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds context about clearing stale or sensitive data but does not disclose significant additional behavioral traits beyond what annotations provide.

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

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

Two sentences with zero wasted words. Front-loaded with the action, then usage guidance, all essential. No fluff.

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

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

Given the tool's low complexity (1 required parameter, no output schema, no nested objects), the description is complete. It covers purpose, usage context, and relation to siblings, leaving no gaps.

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

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

Schema coverage is 100% with a single parameter 'key' described as 'Memory key to delete'. The description does not add any further semantics beyond the schema, so baseline 3 is appropriate.

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

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

The description uses the specific verb 'Delete' and clearly identifies the resource as 'previously stored memory by key'. It distinguishes from siblings by mentioning pairing with 'remember' and 'recall', making its unique role clear.

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

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

The description explicitly states when to use the tool: 'when context is stale, the task is done, or you want to clear sensitive data'. It also suggests pairing with 'remember' and 'recall', providing clear context and 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?

The description details the internal steps (fetch page, extract title/description/key links, emit markdown) beyond the annotations, which already signal safety (readOnly, idempotent, non-destructive). It adds context about the extraction process without contradicting annotations.

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

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

The description is concise: two sentences and a bullet list of use cases. Every sentence adds value, and the key information (purpose, output, usage) is front-loaded. No superfluous 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's simplicity (2 params, no output schema, clear annotations), the description is complete. It explains the output format (single text blob, standard llms.txt) and covers usage scenarios. No missing essential information.

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

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

Schema coverage is 100% with clear descriptions for both parameters (url and max_links). The tool description does not add new information beyond the schema; it only restates the url requirement. Hence, baseline score of 3 is appropriate.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, specifying the verb 'generate', the resource 'llms.txt file', and the target audience (AI crawlers). It distinguishes itself from sibling tools by its unique function that no other sibling appears to cover.

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

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

The description provides explicit use cases (getting a client's site indexed, drafting llms.txt, auditing competitor), offering clear context for when to use the tool. However, it lacks explicit guidance on when not to use it or mention of alternatives, which would elevate it to a 5.

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

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

Annotations already declare readOnly, idempotent, and not destructive. The description adds value by specifying return fields and that it defaults to active subscriptions, with an optional parameter to include inactive ones. 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, no wasted words. First sentence states purpose and return fields, second states usage. Perfectly front-loaded and efficient.

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

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

For a simple list tool with one optional parameter and no output schema, the description covers purpose, return fields, usage scenario, and default behavior comprehensively. Minor omission of pagination or error handling, but acceptable given low complexity.

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

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

Schema coverage is 100%, so the baseline is 3. The description reinforces the schema by saying 'active subscriptions' but does not add new meaning beyond what the schema's 'Include cancelled subscriptions' already 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?

Description uses specific verb 'List' and resource 'the caller's active subscriptions', clearly distinguishing from sibling tools like subscribe and unsubscribe. It also states what fields are returned, leaving no ambiguity about the tool's function.

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.' This tells the agent when to use it, but does not explicitly state when not to use it or name alternatives, though siblings imply them.

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

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

Description adds critical behavioral traits beyond annotations: rate-limited to 5 per identifier per day, free, does not count against tool-call quota. Also states team reads digests daily and feedback affects roadmap. Annotations provide no contradicting info.

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, well-structured paragraph with no wasted words. Every sentence adds value, and it is appropriately 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 what happens with the feedback (digests, roadmap impact). Input schema fully documents all parameters. The tool's purpose is simple and entirely covered.

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

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

Schema description coverage is 100% with clear descriptions for each parameter. The description adds extra guidance on message content (describe in terms of tools/packs), which adds meaningful context beyond the schema.

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

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

The description clearly states the tool is for sending feedback (bug, feature, data_gap, praise) to the Pipeworx team. It distinguishes from siblings by being the dedicated feedback channel, not a data retrieval or analysis 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 lists when to use: when a tool returns wrong/stale data (bug), when a tool is missing (feature/data_gap), or for praise. Also provides a negative guideline: don't paste the end-user's prompt. No alternative feedback tool exists 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?

The description adds transparency beyond annotations by stating the data source ('CF analytics-engine'), that it contains no PII, and that results are cached for 5min-1h. Annotations already declare readOnlyHint and idempotentHint; the description reinforces safe behavior and adds caching details.

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 plus a bulleted list of use cases. It is front-loaded with the main purpose and returns quickly to key details. No 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?

Given the tool's simplicity (one optional parameter, no nested objects, no output schema), the description fully covers return values (top tools, packs, call volume), caching behavior, and data source. Annotations cover safety. 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?

The description adds semantic guidance to the single parameter 'window' by explaining that shorter windows surface what is hot now and longer windows show steady-state demand. This complements the schema's enum description, providing actionable context for parameter selection.

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

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

The description clearly states the tool returns 'top tools, top packs, and total call volume', using specific verb 'Returns' and naming the resource (Pipeworx trending data). It also differentiates from siblings by framing it as a self-aggregating signal for discovering what is 'hot' and for confirming canonical choices before asking questions.

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 sources, confirming canonical tools, and checking alignment with use case. This gives clear when-to-use guidance. However, it does not explicitly mention when not to use or name alternatives, though the sibling list provides context.

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

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

Annotations indicate readOnlyHint=true and destructiveHint=false. The description adds significant behavioral context: internal checks (partition_filter, semantic anchor, fill check), response structure, and conditions like skipped_low_similarity. No contradiction with annotations; it enhances transparency beyond structured fields.

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

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

The description is relatively long but well-organized with clear sections and bolded key terms. Every sentence contributes to understanding the tool's behavior. While verbose, it avoids fluff and maintains a logical flow.

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

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

Given the complexity of arbitrage detection, the description fully covers inputs, modes, internal algorithms, response structure, and integration with fill_risk. No output schema exists, but the description details return fields. Annotations and schema are rich, and the description ties everything together comprehensively.

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 brief descriptions. The tool's description enriches param meaning with examples, mode explanations, and internal logic (e.g., event slug format, topic seed question). This adds value beyond the schema, though the schema already covers basics.

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 also distinguishes three modes (trending_scan, event, topic) with specific instructions, making the purpose highly clear and distinct from sibling tools.

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

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

The description gives explicit guidance on when to use each argument (NO args, event, topic) and recommends event mode for specific markets. It also mentions the FILL CHECK and when not to trade. However, it does not explicitly contrast with sibling tools or state when not to use this tool, leaving some ambiguity.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds extensive behavioral context: caching (1h at KV level), diagnostics for empty segments, Fed bets exclusion reason, and 24h-move warnings. 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 very long and detailed, with multiple sections and technical specifics. While front-loaded with core purpose and structured with headings, the length may overwhelm an agent. Some sentences (e.g., detailed model family descriptions) could be condensed without losing critical 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?

Given the complexity (9 parameters, no output schema, rich behavioral details), the description is highly complete. It details return structure (by_segment, fed_candidates, _diagnostics), explains each segment and knob, and covers filtering logic and limitations. Agents can confidently invoke the tool without guessing return format or assumptions.

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

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

Schema coverage is 100% (all 9 parameters described). The description adds value beyond schema by grouping knobs under 'TRADEABLE-EDGE KNOBS' and providing context (e.g., slippage_pp explains Polymarket fee structure, min_partition_leg_kelly clarifies why partition arbs need per-leg filtering). This extra context justifies a score above baseline 3.

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 specifies verb 'scan', resource 'top Polymarket markets', and outcome 'return opportunities where Pipeworx data disagrees with market price'. It clearly differentiates from sibling tools like polymarket_arbitrage by focusing on Pipeworx vs market price discrepancies and providing three distinct segments. The phrase 'what should I bet on today' reinforces the tool's 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?

The description explicitly states the use case: 'what should I bet on today' and explains tradeable-edge knobs (e.g., min_liquidity, max_spread_pp) for filtering. However, it does not explicitly contrast with sibling tools like polymarket_edge_tracker or polymarket_arbitrage, leaving agents to infer when to choose this tool over alternatives.

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

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

Discloses data source (daily snapshots with TTL), response structure (tracked, expired, snapshot_dates), trend classification, and limitations (time bounds, intraday not captured). Adds significant 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?

Well-structured with clear purpose, response fields, and limitations. Slightly verbose but every sentence adds value; front-loaded with the core question.

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 2-parameter tool with no output schema or enums, the description is comprehensive, covering all relevant aspects: data source, behavior, field-by-field explanation, and limitations.

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 fully (100% coverage). The description adds usage context (defaults, max days) and explains the response format, enhancing meaning beyond the schema.

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

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

The description clearly states the tool's purpose: edge persistence and decay telemetry from daily snapshots, answering a specific question about edge longevity. It distinguishes itself from sibling tools like polymarket_edges by focusing on temporal tracking.

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 implies usage for edge persistence analysis, it does not explicitly state when to use this tool versus alternatives (e.g., polymarket_edges for current edges) or when not to use it.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint) are consistent with a non-destructive read operation. The description adds behavioral context: walks the order-book ladder, returns verdicts (clean/degraded/cannot_fill), and warns about thin legs and forced directional risk. 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 headings for SINGLE-MARKET and BASKET, making it easy to scan. It is front-loaded with the purpose, and every sentence provides essential information without redundancy. Despite length, it is efficient and focused.

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

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

Despite lacking an output schema, the description thoroughly enumerates return fields for both modes (e.g., top_of_book, vwap_fill_price, slippage_pp, verdict for single; theoretical_sum, capture_ratio, profit_usd, thin_legs, forced_directional_risk for basket). It also explains the risk of partial fills. The tool's complexity is fully 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 description coverage is 100%. The description adds significant meaning beyond the schema: explains side defaults and auto-logic for basket, clarifies event vs market modes, and describes size_usd interpretation for both modes (spend for buys, target proceeds for sells; settlement notional for basket). It also mentions clamps and default values.

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

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

The description clearly states the tool performs a realizable-vs-theoretical edge check against live CLOB order-book depth. It distinguishes two modes (single-market and basket) and explicitly 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?

The description provides explicit usage guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It explains why (theoretical overround not capturable, partial fills create directional risk) and gives a threshold, making it highly actionable.

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

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

Beyond annotations (readOnlyHint, idempotentHint, destructiveHint false), the description discloses key behaviors: it returns safety fields (compatibility_warning, temporal_alignment, skipped_cross_type), explains why spreads might be invalid (mismatched bet shapes, temporal gaps), and details how counters track dropped comparisons. 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 relatively long but well-structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS). Every sentence adds necessary context or behavior. Minor redundancy in explaining the spread concept could be tightened, but overall it is efficient for the tool's complexity.

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

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

Given no output schema, the description thoroughly explains the response structure (leg-by-leg prices, spread, safety fields) and conditions where spreads are meaningful. It covers temporal alignment, skipped types, and compatibility warnings, making the tool's behavior fully understandable without external documentation.

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

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

Schema coverage is 100% with descriptions for all parameters. The description adds value by explaining the relationship between parameters (topic vs explicit override) and provides examples for each mode. It clarifies that explicit tickers override the topic-mapped side, which is not stated in the schema.

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

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

The description clearly states the tool computes cross-venue spreads between Kalshi and Polymarket for the same resolving question. It distinguishes from sibling tools like polymarket_arbitrage (intra-venue) by specifying the cross-venue nature and mentions explicit modes for topic-based or custom pairing.

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 two modes (topic shortcuts vs explicit tickers) and warns that most pre-mapped topics return compatibility_warnings, advising that pre-mapped is not automatically tradeable. While it doesn't explicitly say 'when not to use' as a direct sentence, the warnings implicitly guide agents to avoid relying on the tool when compatibility issues arise.

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

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

Annotations already indicate read-only, open-world, and idempotent behavior. Description adds context about the query language but does not disclose rate limits, output format, or potential edge cases. 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?

Extremely concise: two sentences and an example. Information is front-loaded and every sentence adds value. No unnecessary 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 simplicity of the tool (3 params, no output schema, rich annotations), the description is largely complete. However, it could mention that results are returned in a structured format (list of indicators) to fully bridge the gap.

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

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

Schema covers all 3 parameters with descriptions. The tool description provides an example that reinforces the schema but adds no additional semantic depth beyond what the schema already conveys.

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

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

Description clearly states verb ('Search') and resource ('Pulsedive threat DB') and explains the query language. Differentiates from sibling tool 'pulsedive_indicator' (single indicator lookup) by emphasizing search with boolean filters.

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 an example of usage but does not explicitly state when to use this tool vs. alternatives like 'pulsedive_indicator' or other search tools. No guidance on when not to use it.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds that it returns risk level, risk factors, threats, intel feeds, but no further behavioral traits (e.g., rate limits, authentication details). This adds some context but is not exceptional.

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 an example, efficient and front-loaded. Every sentence serves a purpose with no fluff.

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

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

With no output schema, the description hints at return values (risk level, threats, feeds). It is sufficient for a simple lookup tool, though more detail on output format could be provided.

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 description adds minimal value beyond the schema. The example shows usage, but parameter descriptions in the description are nearly identical to schema. Baseline 3 is appropriate.

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

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

The description states the tool looks up an IOC in Pulsedive and returns risk level, threats, etc. It clearly identifies the resource (IP/domain/URL/hash) and action (look up), distinguishing it from siblings like pulsedive_explore.

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 includes an example call, implying when to use it (checking a specific IOC). However, it does not explicitly mention when not to use it or compare to alternatives like pulsedive_explore.

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 aligns with annotations (readOnlyHint, idempotentHint) and adds behavioral context: it retrieves previously saved values, lists keys when omitted, and is scoped to the user's identifier. No contradiction.

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

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

Three sentences with no wasted words. Front-loaded with core action, then usage context and pairing. 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?

Tool is simple with one optional parameter and no output schema. The description fully covers behavior, usage, and pairing with siblings. No gaps.

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

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

Schema coverage is 100%, so parameter is already well-documented. Description adds context about omitting the key to list all, but this is also in the schema description. Does not add significant new meaning.

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

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

Description clearly states the tool retrieves a saved value or lists all keys, with specific verb and resource. It distinguishes from sibling tools 'remember' and 'forget' by explaining the pairing.

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 (look up context stored earlier, avoid re-deriving) and implies alternatives (use 'remember' to save, 'forget' to delete). Also mentions scoping to the user's identifier.

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 states 'Set mark_read:true to flag returned events read', indicating state modification, but annotations declare readOnlyHint=true, implying no writes. This contradiction undermines transparency. Additional behavioral context like rate limits or return structure is absent.

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

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

The description is three sentences, front-loading the purpose and adding essential details efficiently without redundancy.

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

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

Given five parameters and no output schema, the description covers purpose, filtering, mark_read behavior, and an alternative endpoint. However, it lacks details on return structure, pagination, or ordering, leaving gaps for an agent.

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

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

Schema coverage is 100% with descriptions for all parameters. The description adds context like example type 'sec_8k' and meaning of mark_read, but the value is reduced by the contradiction with readOnlyHint.

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

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

The description clearly states the tool pulls fired events from a subscription feed, specifying the resource and action. It details return fields and filtering options, but does not explicitly differentiate from sibling tools like list_subscriptions.

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

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

The description mentions an alternative access method (GET registry.pipeworx.io/alerts.json) for scripts and dashboards, implying when not to use this tool. However, it does not provide explicit guidance on when to use this tool over siblings or when to avoid it.

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

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

Adds rich behavioral context beyond annotations: fans out to multiple sources, fallback logic, API sunset note, grouped return structure with URIs, parameter format 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?

Well-structured with usage examples front-loaded, then source details, then parameter info. Every sentence adds value; slightly verbose but justified by 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?

Comprehensive for a multi-source aggregation tool without output schema: covers sources, failure modes, return structure, parameter formats, and comparison to sibling. 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?

Adds meaning beyond schema: explains since accepts ISO or relative shorthand with examples, value can be ticker or CIK, type restricted to company. Schema coverage is 100% but description enhances understanding.

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

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

Description specifies verb+resource: 'change feed for a company' and lists concrete sources (SEC, news, patents). Distinguishes from entity_profile sibling 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?

Provides multiple usage examples ('What's new with X') and explicit alternative ('Use entity_profile instead when you want the static profile'). Includes fallback behavior details.

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: key-value store scoped by identifier, persistence details for authenticated vs anonymous sessions. Annotations only provide idempotentHint=true and destructiveHint=false, so description enriches behavioral understanding.

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

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

Highly concise: three sentences front-loaded with purpose, then usage, then details. No wasted words.

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

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

Covers purpose, usage, persistence, and pairing with recall/forget. No output schema, but for a write tool that's acceptable. Adequate for the complexity.

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

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

Input schema has 100% coverage with good descriptions. Description adds examples of keys and values, and mentions scoping and persistence, but does not significantly expand beyond schema.

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

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

The description clearly states the tool saves data for later reuse, with specific examples like 'resolved ticker', 'target address', 'user preference'. It distinguishes from siblings 'recall' and 'forget' by mentioning them as pairs.

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: 'when you discover something worth carrying forward' and how to use with examples. Notes pairing with recall and forget, but no explicit when-not-to-use or alternatives beyond 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 indicate safety and idempotency. The description adds that calls cascade through several endpoints and specifies exact return fields (ticker, CIK, URIs for company; RxCUI, ingredient for drug). Omits error handling or limits.

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 relatable query examples, then succinctly covers both entity types. No fluff; 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 no output schema, description fully details return fields and citation URIs for both entity types. Explains internal cascade and efficiency gains. Covers input variations adequately.

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 enriches semantics: explains input flexibility (ticker, CIK, name for company; brand/generic for drug) and auto-disambiguation. Links inputs to outputs.

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

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

The description clearly states the tool resolves names to official identifiers, with examples like 'What's the ticker for...' and details for company and drug entities. It distinguishes itself as a first-use tool for ID lookup.

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

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

The description advises 'Use FIRST whenever you have a name but need an ID' and explains it replaces multiple lookups. However, it does not explicitly discuss when to use siblings like compare_entities or entity_profile.

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 fully discloses behavior beyond annotations: it orchestrates ai_visibility_check, ranks by score, and returns score/confidence/signal density. It also mentions API key requirement for Anthropic model. No contradictions with readOnlyHint and idempotentHint.

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

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

Three sentences, front-loaded with purpose, includes a use case example and output details. Every sentence adds value; 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?

Description explains internal mechanism (probes with ai_visibility_check) and output format (ranked list with score, confidence, signal density). No output schema but compensation is adequate. Could mention limits on entity count beyond schema (2-8), but that is already in the schema.

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

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

Schema description coverage is 100%, so all parameters are already documented. The description adds no extra meaning beyond the schema, 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 it compares AI visibility across multiple entities, probes with ai_visibility_check, and returns a ranked list. It distinguishes from sibling tools like ai_visibility_check (single entity) and compare_entities by specifying the competitive audit use case.

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

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

The description provides a clear use case ('competitive AI-marketing audits') and example question, implying when to use it. However, it does not explicitly state when not to use it or contrast with alternatives like compare_entities, which would clarify scope exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. The description adds valuable behavioral context: partial failures degrade gracefully, bundlephobia's first measurement may take 5-30s, and sources_failed lists timeouts. 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 relatively long but well-structured: front-loaded with the composite nature and use case, then details return format and exceptions. Every sentence adds value, but minor trimming could improve conciseness.

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

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

Even without an output schema, the description fully details return fields (summary block, advisory details, links, alternatives). It covers input constraints, behavioral nuances (partial failures, timing), and sibling alternatives. 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 both parameters described. Description adds only minor clarifications (scoped packages accepted, version defaults to latest) that are already in the schema descriptions. Thus, 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 the tool's purpose as a composite check for evaluating npm packages, listing specific data sources (deps.dev, bundlephobia) and what it answers ('is X safe / popular / small'). It distinguishes from sibling tools by noting NPM-only scope and directing to deps.dev directly for other ecosystems.

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

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

Provides clear when-to-use guidance: whenever an agent asks about safety, popularity, size, or cost of adding a package. Also states when not to use (non-NPM ecosystems) and gives the alternative: 'deps.dev:version directly'. Partial failure behavior is explained, helping agents set expectations.

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

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

Annotations indicate readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description goes well beyond these by specifying the embedding model (BGE-base-en), similarity metric (cosine), windowing approach (500-char overlapping windows), and a hard character limit of 200K with truncation and flagging. It also details the output: top-N passages with character offsets and similarity scores. 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 concise yet comprehensive, front-loading the core purpose and usage, then adding technical details in the second sentence. Every sentence adds value, with no filler. It is well-structured and easy to parse for an AI agent.

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

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

Despite no output schema, the description fully explains return values (passages with offsets and scores). It covers input constraints (200K char limit), behavior (truncation flagging), and pairing with a sibling tool. For a retrieval tool, this provides all necessary context for correct usage.

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. The description adds extra context: for 'text', it gives examples like SEC 10-K body; for 'query', it offers natural-language examples; for 'limit', it clarifies 'top-N passages' and the default. This adds meaningful value beyond the schema, justifying a 4.

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

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

The title 'Search Within a Source' and opening sentence 'Semantic search INSIDE a fetched record' clearly state the action (semantic search) and the target resource (a fetched record). It distinguishes itself from sibling tools like ask_pipeworx_grounded, which uses the same concept but for grounding, and explicitly mentions pairing with that sibling.

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

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

The description explicitly advises when to use: 'Use when the record is too big to cram into the prompt — search_within saves context.' It also explains how it pairs with ask_pipeworx_grounded, providing a clear alternative and integration pattern. Additionally, it mentions the return of character offsets for quote verification, guiding the agent on how to use the results.

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

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

The description adds significant behavioral context beyond annotations, such as auth requirements, delivery channel constraints (SMS cap, webhook auto-disable), and the always-on feed. It does not clarify idempotency, but the idempotentHint annotation already covers that.

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 into logical sections (purpose, auth, types, delivery) and front-loads the main action. While somewhat verbose, each sentence adds value and there is no fluff.

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

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

Given the complexity of the tool (nested objects, multiple options) and the absence of an output schema, the description covers creation, auth, types, delivery details, and rate limits. A minor gap is the lack of discussion on duplicate subscription behavior, but the idempotentHint mitigates this.

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 coverage is 100%, and the description enriches every parameter with concrete examples, validation rules, and constraints. For example, the 'params' parameter provides type-specific filter structures and required fields.

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 'Create' and the resource 'proactive monitoring subscription to a live-data event stream'. It also specifies the return value, making the purpose unambiguous. It distinguishes from sibling tools like 'list_subscriptions' and 'unsubscribe'.

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

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

The description lists a prerequisite (Pipeworx OAuth account) and provides detailed examples for each subscription type. While it does not explicitly exclude alternative tools, the context is sufficient for understanding when to use this tool.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral context: it returns category-bucketed example questions with live tool info, and is safe for repeated calls.

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 common user queries, then explains return format and usage in a structured way. Every sentence adds value, no wasted words.

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

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

Given the parameter count of 1, high schema coverage, and rich annotations, the description fully covers the tool's purpose, usage, and output format. No gaps identified.

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 value by explaining the default behavior (full spread) and providing example values for the topic parameter, going beyond the schema description.

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

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

The description clearly identifies the tool as the onboarding entry point for suggesting example questions, with a specific verb ('suggest_questions') and resource ('Pipeworx capabilities'). It distinguishes itself from siblings like 'discover_tools' and 'ask_pipeworx' by focusing on example questions and getting started.

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

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

The description explicitly states to use this FIRST when you don't know what Pipeworx can do, and provides guidance on optional topic parameter usage. While it doesn't mention when NOT to use it, the context is clear enough for the AI agent.

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 destructiveHint=false and idempotentHint=true. The description explains that the row is deactivated (not deleted) and historical events remain, which adds valuable context beyond the annotations. No contradiction with annotations.

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

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

The description is two sentences, front-loaded with purpose, and every sentence adds value. No wasted words. 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?

For a tool with one parameter, no output schema, and annotations already present, the description is complete. It explains ownership, the non-destructive nature, and the impact on historical data, leaving no obvious gaps.

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

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

Schema coverage is 100%, providing a baseline of 3. The description mentions 'by id' and the schema already describes the parameter as 'Subscription id (uuid) returned by subscribe.' The description adds no new semantic info 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 'Cancel a subscription by id.' with a specific verb (cancel) and resource (subscription). It distinguishes this tool from siblings like 'subscribe' and 'list_subscriptions' by indicating it performs a cancellation.

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: ownership enforcement ('you can only cancel your own subscriptions') and the effect on data ('row is deactivated, not deleted'). This guides the agent on when to use and what to expect, though it does not explicitly mention when not to use it.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable context: the two verification pathways, exact percent-delta math for financial claims, return verdicts, and citation details. 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 paragraph that front-loads trigger phrases and examples. While not overly verbose, it could be more structured (e.g., bullet points) to improve readability. Every sentence adds value, but length is slightly above ideal.

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

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

Given no output schema, the description fully explains return values (verdict, actual value, citation, reasoning) and the two pipelines. It provides complete context for a tool with 2 parameters and high schema coverage.

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

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

Schema coverage is 100% for both parameters. The description adds meaning beyond the schema by explaining that tolerance_pct overrides implied tolerance and giving specific use cases (e.g., 1-2 for hallucination detection).

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 verifies natural-language claims against authoritative sources, distinguishing it from siblings by noting it replaces 4-6 sequential calls. It specifies two distinct verification paths: company-financial claims via SEC EDGAR+ XBRL and other claims via a grounded pipeline.

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

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

The description provides explicit when-to-use guidance with examples like 'fact check' and 'verify the claim that...'. It describes the tool's role in checking factual correctness but does not explicitly compare it to sibling tools like deep_research or compare_entities, or state when not to use it.

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