Outlook Contacts

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

Beyond the annotations (readOnlyHint, idempotentHint, etc.), the description adds critical behavioral context: the default free model (Workers AI Llama-3.3-70b), the requirement to bring your own API key for Anthropic, and the return structure (per-model {score, confidence, signals, raw_response} + combined view). This gives the agent a complete picture of behavior without contradiction.

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

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

The description is four sentences with no wasted words. It front-loads the purpose and immediately provides the key behavioral details. Every sentence adds necessary 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 moderate complexity (4 params, no output schema), the description covers enough: it explains return format, use cases, and model options. Sibling tools are distinct, and annotations cover idempotency. No obvious gaps exist for effective agent invocation.

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

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

Schema description coverage is 100% with each parameter well-documented. The main description adds extra value: it specifies the default model, explains the API key billing, and provides examples for the entity parameter (e.g., 'Pipeworx', 'OpenInvoice'). 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 verb 'probe' and resource 'LLMs for what they know about a business/brand/product/topic', and specifies the output as a visibility score 0-100. It distinguishes itself from sibling tools like 'ask_pipeworx' (which queries one LLM) and 'scan_competitor_ai_presence' (which may scan multiple entities) by focusing on scoring visibility across models.

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 concrete use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' This gives clear context for when to use the tool. However, it does not explicitly state when NOT to use it or provide alternative tools for different scenarios.

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

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

With annotations already declaring readOnly, openWorld, idempotent, and non-destructive, the description adds significant behavioral context: it routes the question, fills arguments, returns a structured answer with stable pipeworx:// citation URIs, works on every tier, and is described as 'one fast call'. This goes well beyond the annotations and clarifies the tool's internal behavior.

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

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

The description is longer than some but well-structured: it fronts the key instruction ('PREFER OVER WEB SEARCH'), organizes use cases by domain, gives trigger phrases, examples, and clearly separates alternatives. Every sentence adds value, though it could be tightened slightly without losing substance.

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

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

For a complex routing tool with no output schema, the description is remarkably complete. It covers the return format (structured answer with citation URIs), when to use it, when to prefer alternatives, and even how it handles breaking news. An agent would have ample context to select and invoke this tool correctly.

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

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

The input schema already provides full coverage with descriptions for each property and explains that the main 'question' field accepts aliases. The tool description does not add parameter-level detail beyond examples of questions, so the baseline of 3 is appropriate given the schema's 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 identifies the tool as a factual question router that selects from 5,529 tools across 1,455 sources and returns structured answers with citation URIs. It distinguishes itself from sibling tools by explicitly naming ask_pipeworx_grounded and deep_research as alternatives with different characteristics.

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

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

The description is exceptionally explicit: it says 'PREFER OVER WEB SEARCH', 'START HERE for most questions', lists trigger phrases ('what is', 'look up', 'find', 'get the latest', 'how much', 'current'), and provides precise when-to-use guidance for alternatives (ask_pipeworx_grounded for verbatim evidence, deep_research for broad/multi-part questions).

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

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

The description goes well beyond the annotations by disclosing the experimental beta behavior: candidate routing improvements are enabled live, no candidate is active as of 2026-07-26, so it currently matches ask_pipeworx exactly. It also clarifies 'Falls back to nothing — this IS a full working router, just the experimental edge,' providing valuable stateful context beyond the read-only/idempotent hints.

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

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

The description uses four sentences, each delivering essential context: beta identity, current routing candidate state, usage instruction, and non-fallback assurance. It is front-loaded with the purpose and avoids fluff, though the repeated references to 'ask_pipeworx' and 'matches exactly' introduce slight redundancy.

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

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

The description covers the beta purpose, current candidate state, usage guidance, relationship to the stable router, and response-shape parity with ask_pipeworx. With no output schema, noting that the response shape matches ask_pipeworx is helpful, and there are no major contextual gaps for invoking the tool.

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

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

Schema description coverage is 100%: all six parameters including q, text, input, query, prompt, and question are described, with question as the required natural-language input. The description only says 'same arguments' and adds no extra parameter detail beyond the schema, placing it at the baseline for fully documented schemas.

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 beta version of ask_pipeworx, an identical universal router with the same 5,529 tools, arguments, and response shape. It explicitly states its purpose: 'Use it exactly like ask_pipeworx when you want the newest routing,' which differentiates it from the stable ask_pipeworx 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?

It provides explicit when-to-use guidance: 'Use it exactly like ask_pipeworx when you want the newest routing' and explains that results are compared against the stable router. However, it does not explicitly state when not to use it or mention the ask_pipeworx_grounded alternative, so it stops short of full exclusion guidance.

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

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

Beyond the readOnly/openWorld annotations, the description details the grounding mechanism (extraction only from tool result), exact refusal reasons like 'not_in_source' and 'tool_error', and the cost of one extra LLM call. This gives the agent full visibility into success/failure behavior without relying on an output schema.

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

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

The description is dense but efficiently structured: purpose first, then mechanism, return format, refusal modes, usage trigger, and cost trade-off. Every sentence contributes new information, and it remains readable despite its length.

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

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

Even though there is no output schema, the description fully specifies both success return fields (answer, evidence, confidence, source, fetched_at, refusal_reason:null) and refusal structure with enumerated reasons. It also explains routing and the extra-cost trade-off, making the tool's behavior fully predictable for an agent.

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

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

Schema description coverage is 100%: all six parameters are aliases for 'question' and are fully described in the schema. The description adds no additional parameter-specific semantics, but the schema already handles the heavy lifting, so the baseline of 3 is appropriate.

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

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

The description clearly defines the tool as a 'hallucination-resistant answer mode' for high-stakes reads, with a specific verb ('extracts the answer') and explicit scoping to grounded, evidence-based responses. It distinguishes itself from the sibling ask_pipeworx by emphasizing that it uses ONLY the tool result, not invented knowledge.

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

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

Provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on' and when the agent 'must not invent facts.' It also names the alternative ask_pipeworx and gives a trade-off: 'prefer ask_pipeworx for casual lookups' due to an extra LLM call.

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

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

The description extensively covers behavioral traits beyond annotations: fan-out processes, response shapes, resolver contract with confidence levels, parent_event extraction, safety mechanisms for low-confidence and closed markets, wide-spread liquidity warnings, and cancellation rule parsing. 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 long but well-structured with clear section headers and no redundancy. While it could be slightly more concise, every sentence adds necessary detail for a complex tool, justifying its length.

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

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

Given the tool's complexity, no output schema, and only 3 parameters, the description is exceptionally complete. It covers input, internal logic, output fields, edge cases, and security considerations, leaving no significant 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%, and the description adds value by explaining market input flexibility, depth options, and include_raw usage with size estimates. It also provides defaults and recommendations, augmenting the schema information.

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 researches Polymarket bets by pulling Pipeworx data, accepting slugs, URLs, or question text. It details the process but does not explicitly differentiate from sibling tools like 'polymarket_edges' or 'polymarket_arbitrage', leaving some ambiguity.

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 specifies use cases ('should I bet on X', 'what does the data say') and provides category-specific fan-out examples. However, it does not explicitly state when not to use the tool or suggest alternative tools for different scenarios.

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

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

Adds rich behavioral details beyond annotations: data sources (EDGAR/XBRL, FAERS), specific metrics, sorting behavior, citation URIs, and handles fiscal year offsets. 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?

Dense but well-structured: starts with trigger phrases, then explains behavior per type, sorting, and return value. Every sentence adds value 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 no output schema, description explains return values (paired data + citation URIs), covers both entity types, sorting, and edge cases (off-calendar fiscal years). Complete for a comparison tool.

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

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

Schema coverage is 100%, but description adds value by explaining what values mean (tickers/CIKs for company, names for drug) and giving examples, going 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 does side-by-side comparison of 2-5 companies or drugs, with specific trigger phrases and data types per entity. It distinguishes from siblings like entity_profile by emphasizing it replaces sequential lookups.

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

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

Explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and gives example queries, providing clear guidance on when to use this tool versus 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?

Goes far beyond annotations by disclosing account requirements, fallback behavior when not signed in, decomposition into facets, parallel routing to 5529 tools, findings packet structure with gaps[] and contradictions[], never-invented guarantee, citation_uri resolvability, semantic excerpting, and latency expectations. This is rich behavioral context beyond 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?

The description is long, but nearly every sentence adds unique value. It is front-loaded with the critical account requirement and fallback, then proceeds through purpose, usage, depth semantics, output format, and latency. Structured with semicolons and clauses, it packs information efficiently for a complex tool, though slightly dense.

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 return value semantics: findings packet fields (verbatim evidence, confidence, source, fetched_at), citation_uri resolvability, gaps[] for unanswered facets, contradictions[] for deeper depths, and hop field. It also covers latency, depth behaviors, and failure modes, making it complete for a tool of this complexity.

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

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

The schema already fully documents both parameters (100% coverage). The description adds extra semantics beyond the schema by explaining depth variants in detail ('quick=3', 'standard=5', 'thorough=8') and noting that broad/multi-part questions are suitable. This goes beyond the baseline without being redundant.

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

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

The description clearly states the tool performs multi-source research across 1455 structured data sources, with explicit differentiation from open-web search and sibling tool ask_pipeworx. The verb 'research' and resource 'Pipeworx's structured data sources' are specific and unambiguous.

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

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

Provides explicit when-to-use and when-not-to-use guidance: 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS ... prefer ask_pipeworx'. Also covers account tier requirements and depth selection, making alternatives and exclusions clear.

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

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

Annotations already indicate readOnly, idempotent, non-destructive. The description adds significant behavioral context: returns top-N relevant tools with full schemas and curated examples, ready to call directly without second lookup. This goes well 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 purpose first, then domain list, then output description. Every sentence adds value, though slightly verbose with the long list of domains.

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 the return format (names, descriptions, schemas). It also covers the behavior of returning top-N results and being ready to call directly.

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 parameter descriptions are adequate. The description adds value by providing natural language query examples and clarifying that multiple aliases (task, q, etc.) are accepted.

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 'Find tools' and the resource 'by describing the data or task'. It lists many specific domains (SEC filings, FDA drugs, etc.) and distinguishes itself from sibling tools, none of which are for tool discovery.

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

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

Explicitly advises 'Call this FIRST when you have many tools available and want to see the option set'. Provides clear context for when to use it, though it does not explicitly 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.

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

Beyond annotations (readOnlyHint, etc.), the description discloses that the tool fans out across multiple sources, notes the USPTO patents API sunset (soft-fails until reactivated), and specifies output format details (up to 5 filings with URIs, fundamentals sorted). No contradictions with annotations.

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

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

The description is a single paragraph but densely packed with useful information. While not strictly concise (it runs long), every sentence earns its place. No wasted words, though better structuring (e.g., bullet points) could improve readability.

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

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

Given the tool's complexity (multisource output) and rich annotations, the description covers inputs, outputs, sources, and limitations (soft-fail). It lacks explanation of return value interpretation, but output schema is absent, so this is acceptable. Slightly incomplete for a new user.

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 baseline 3. The description adds context: explains the 'type' enum (only company), clarifies 'value' can be ticker or zero-padded CIK, and explicitly excludes names, with examples. This enhances understanding beyond schema.

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

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

The description clearly states the tool provides a 'full cross-source profile of a US public company in ONE parallel call' with example queries and detailed outputs (CIK, filings, fundamentals, patents, news, LEI). It also distinguishes itself from sibling tools like single-source lookups by advising preference over chaining.

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

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

The description explicitly tells when to use (holistic company view), when not to use (names not supported), and provides an alternative (use resolve_entity first). It also states 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups', offering clear decision guidance.

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

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

The description adds context beyond annotations by noting the use case for clearing sensitive data. Annotations already indicate destructiveHint=true and idempotentHint=true, and the description aligns with these without contradiction.

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

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

The description is two sentences, front-loaded with the core action, and contains no unnecessary words.

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

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

For a simple tool with one parameter and no output schema, the description covers purpose, usage guidelines, and context completely. Annotations further fill in behavioral details.

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

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

The description adds no additional meaning to the parameter beyond what the input schema provides. Schema coverage is 100%, so baseline is 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 'Delete a previously stored memory by key', specifying the verb (delete), resource (memory), and method (by key). It also mentions pairing with 'remember' and 'recall', distinguishing it 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 explicitly states when to use the tool: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It does not explicitly mention when not to use, but provides sufficient context.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, establishing a safe, non-destructive profile. The description adds basic steps (fetch, extract, emit) but no deeper behavioral context like rate limits or authentication needs.

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, front-loaded with the main purpose, and structured logically. Every sentence adds value, though it could be slightly more terse.

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, annotations, and schema coverage, the description provides adequate context about output format and use cases. Missing error handling or validation details, but acceptable for a read-only tool with openWorldHint.

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

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

Schema coverage is 100% with both parameters described. The description implicitly references the URL and max_links but adds no additional meaning or constraints 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 generates a production-ready llms.txt file for any URL, specifying verb, resource, and output. It distinguishes from siblings like 'scan_competitor_ai_presence' by focusing on llms.txt generation.

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

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

Explicit use cases are provided: indexing a client's site, drafting for own project, or auditing competitors. However, it lacks explicit when-not-to-use or direct comparison to siblings.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds the list of returned fields and the optional include_inactive parameter but does not disclose further behavioral traits beyond what annotations offer.

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

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

Two concise, front-loaded sentences with no wasted words. Every sentence adds value: purpose and usage guidance.

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 lists return fields. The single optional parameter is covered in schema. Sibling tools are present. Guidance on using the results (find id to cancel) makes it complete for a simple list 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 one boolean parameter fully described in the schema. The description does not add parameter information beyond what the schema provides, so baseline score of 3 applies.

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

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

The description clearly states it lists the caller's active subscriptions, specifies the returned fields (id, type, params, etc.), and distinguishes from sibling tools like subscribe and unsubscribe.

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

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

It advises to use this tool to review monitored items before adding more or to find an id to cancel, providing clear context on when to use it versus alternatives. It lacks explicit when-not guidance but context is sufficient.

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

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

The description goes well beyond the sparse annotations (all hints false) by disclosing important behavioral details: filing returns a claim_token, rate limit of 5 per identifier per day, free and doesn't count against tool-call quota, and that the team reads digests daily. It also includes the guidance to describe issues in terms of Pipeworx tools, which is an unstated behavioral expectation.

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 carefully structured, starting with the core purpose, then use cases, exclusions, and operational details. Every sentence adds value, though some repetition exists (e.g., restating 'ONLY for tools served by this Pipeworx connection'). It remains highly readable and front-loaded, so a 4 is warranted.

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

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

Given the tool's complexity (nested context object, optional params, no output schema), the description is fully self-contained. It covers all invocation modes, exclusions, the claim_token retrieval flow, rate limiting, quota impact, and what happens after filing. Nothing about usage seems omitted.

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 each parameter already well-described in the schema, so baseline is 3. The description adds extra semantic constraints: the message should not contain the end-user's prompt and the claim_token usage pattern ('pass it back later as pipeworx_feedback({claim_token:"..."})'), which are not explicit in the schema. This added meaning justifies 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 first sentence 'Tell the Pipeworx team something is broken, missing, or needs to exist' provides a specific verb+resource+scope. The description clearly enumerates use cases (bug, feature, data_gap, praise) and distinguishes this from tools on other MCP servers by explicitly stating it only applies to this Pipeworx connection.

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

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

The description gives explicit when-to-use directives (tool returns wrong data, wish for a new tool, positive note) and avoids misdirected feedback by stating that tools from other MCP servers should be reported elsewhere. It also provides the distinguishing criterion ('Pipeworx tool names are the ones this connection lists') and the claim_token workflow for follow-up, giving clear situational guidance.

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

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

Annotations already provide readOnlyHint=true, idempotentHint=true. The description adds valuable behavioral context: 'Self-aggregating signal — derived from CF analytics-engine, no PII' and 'Cached 5min-1h depending on window.' This goes beyond annotations.

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

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

Description is well-structured with clear sections and bullet-like use cases. It is front-loaded but slightly verbose; each sentence adds value but could be more concise.

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

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

For a simple tool with one optional parameter and no output schema, the description fully covers what is returned (top tools, packs, volume, window), caching, and derivation. No gaps apparent.

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 meaning: explains that shorter windows surface hot trends and longer windows show steady-state demand. This extends the enum 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 returns top tools, packs, and call volume over a window. It uses a specific verb ('Returns') and resource ('top tools, top packs, total call volume'), and distinguishes from sibling tools like discover_tools by focusing on trending usage from AI agents.

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

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

Explicitly lists three use cases (discovering hot data sources, confirming canonical tools, aligning use cases). However, it does not provide exclusions or alternatives, which would improve guidance.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. Description adds rich behavioral details: internal algorithms (Jaccard similarity, partition filter), fill check against CLOB depth, return format, and trade guidance. 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 long but well-structured with clear sections for modes, internal mechanisms, and return format. Every sentence adds value, though some redundancy exists (e.g., repeating partition check details). Slightly verbose but not wasteful.

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

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

No output schema, so description must explain return values. It does: 'opportunities[]' with fields, and 'partition_check' object in event mode. Also covers fill check and trade decision logic. Complete for a complex analytical tool.

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

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

Schema description coverage is 100%, but the description adds significant meaning beyond schema: explains event slug examples, topic seed questions, and the internal logic behind each parameter. It also provides usage recommendations.

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 finds arbitrage opportunities via monotonicity violations and partition-sum checks, and distinguishes three modes: no-arg trending scan, event mode for specific events, and topic mode for cross-event scanning. The verb 'find' and resource 'arbitrage opportunities on Polymarket' are specific.

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

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

Explicit guidance: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', 'topic (for cross-event scanning)'. It explains when to use each mode and mentions cross-event mode catches patterns that single-event misses. Also references fill check and custom sizing via polymarket_fill_risk.

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 extensive behavioral traits beyond annotations, including caching at KV level for 1 hour, specific models and calculations (e.g., lognormal barrier, GDELT, partition_overround), response structure with diagnostics, and warnings like '24h-move warning'. This goes well beyond the read-only and idempotent hints provided by annotations.

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

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

The description is front-loaded with the purpose and well-structured, but it is lengthy with considerable technical detail (e.g., exact alpha values for sports). While all content is relevant, it could be more concise without losing key 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 lack of an output schema, the description thoroughly explains the response structure, including top-level keys (by_segment, fed_candidates, _diagnostics) and field details within opportunities (edge_pp_net, kelly_fraction, etc.). This fully compensates for the missing output schema.

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

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

All 9 parameters have schema descriptions, providing baseline insight. The description adds integrated context, such as explaining how tradeable-edge knobs (min_liquidity, max_spread_pp) interact and detailing the purpose of min_partition_leg_kelly. This adds value beyond the standalone schema descriptions.

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

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

The description clearly states the tool scans Polymarket markets to find opportunities where Pipeworx data disagrees with market price, using the specific verb 'scan'. It distinguishes itself from siblings like polymarket_arbitrage and polymarket_edge_tracker by detailing three unique segments (model-driven, structural arbitrage, concentrated longshot) and the 'what should I bet on today' 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 implies usage for discovering betting opportunities and provides guidance on knobs, but does not explicitly state when not to use this tool or compare it to alternatives like polymarket_arbitrage or polymarket_edge_tracker. Given the presence of sibling tools, explicit differentiation would improve the score.

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?

Disclosures about response structure (tracked, expired, snapshot_dates), field meanings (trend, decay_pp_per_day, lifespan_days), and limits (60-day TTL, snapshot gaps) go well beyond the readOnly and idempotent annotations.

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

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

Well-structured with purpose first, then response details and limits. Slightly lengthy but every sentence adds value; no redundancy.

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

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

Despite lacking an output schema, the description thoroughly explains all response fields and their interpretations, including edge cases like gaps in snapshots. Complete for the tool's purpose.

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 clarity to both parameters: explains default, max, and clamp for 'days'; explains 'window' as snapshot family with defaults. This supplements the schema which already has 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?

Clearly states it provides edge persistence and decay telemetry from daily snapshots. Distinguishes from sibling 'polymarket_edges' by focusing on historical trends rather than current snapshots.

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?

Explains the use case via the question 'how long has this edge existed and is it shrinking?' and contrasts fresh vs old edges. Does not explicitly list alternatives or negative cases, but context is clear.

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

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

Discloses detailed behavior: walks the ladder, returns top_of_book, vwap_fill_price, slippage_pp, verdict, etc. Warns about forced directional risk. Annotations already indicate readOnly, but description adds significant context.

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

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

Well-structured with clear sections (REQUIRES, SINGLE-MARKET, BASKET, USE THIS). However, somewhat lengthy; some details could be trimmed or moved to parameter descriptions. Still effective.

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

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

Comprehensive coverage: both modes explained, all return fields mentioned, practical usage advice, and risk warnings. No output schema, but description compensates fully.

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

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

Schema coverage is 100%, but description adds valuable context beyond schema definitions: explains default for side in basket mode, interpretation of size_usd for buys vs sells, and the difference between single-market and basket parameters.

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

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

States specific purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' Clearly distinguishes from sibling tools like polymarket_arbitrage and polymarket_edges by explicitly mentioning when to use this check before acting on those signals.

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: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' Also explains dangers of thin books and partial fills.

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

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

Annotations already declare readOnlyHint and idempotentHint. The description adds significant context: compatibility warnings for non-equivalent bet shapes, temporal alignment checks, skipped cross types/subtypes, and the realistic expectation that most pre-mapped topics yield warnings. 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 with sections for modes, response, safety fields. Every sentence adds value. Slightly verbose but maintains clarity; could be shortened without losing meaning.

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

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

Given the tool's complexity (cross-venue spread with compatibility logic) and no output schema, the description covers inputs, behavior, warnings, temporal alignment, and response structure. It is thorough and leaves little ambiguity about what the tool returns and its 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 coverage is 100% with descriptions for all 3 parameters. The description adds context: topic lists the 10 shortcuts, explicit tickers override topic-mapped sides, and provides examples. While schema already has descriptions, the description enriches with behavioral context for each parameter.

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

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

The description clearly states the tool computes cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes itself from siblings like polymarket_arbitrage by focusing on spread across venues, and explicitly describes two usage modes (topic shortcuts and explicit tickers). Action-oriented and specific.

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 each mode (topic vs explicit tickers), includes a list of 10 topic shortcuts, and warns that many pre-mapped topics return compatibility warnings, thus not all are tradeable. This helps the agent decide when this tool is appropriate vs alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds scoping detail ('Scoped to your identifier'), which is valuable beyond annotations. 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?

Four sentences with no fluff. Core action stated first, usage context second, scoping and sibling references follow. Every sentence earns its place.

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

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

For a tool with one optional param, no output schema, and annotations covering safety, the description fully covers purpose, usage, scoping, and sibling relationships. Nothing obvious missing.

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 description 'Memory key to retrieve (omit to list all keys)'. Description further clarifies the parameter behavior ('omit the key argument to list all keys'), reinforcing schema info.

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 action ('Retrieve a value previously saved... or list all saved keys'), identifies the resource (memory key), and distinguishes from sibling tools (remember, forget). The verb 'recall' and resource 'value' are specific.

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

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

Explicitly says when to use ('Use to look up context the agent stored earlier... without re-deriving it from scratch') and mentions pairing with remember and forget. Could state when not to use but context suffices.

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 claims mark_read:true flags events as read, implying a side-effect, which contradicts the annotation readOnlyHint=true. This is a serious inconsistency that misleads about the tool's safety profile.

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

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

The description is concise with four sentences, front-loading the main purpose. It could be more structured but contains 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 no output schema, the description provides return field details, filtering, mark_read behavior, and alternative access. It lacks explanation of pagination and ordering, but is fairly complete for the tool's complexity.

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

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

Schema coverage is 100%, but the description adds context only for type, since, and mark_read. It does not explain limit or unread_only beyond the schema, so the added value is partial.

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

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

The description clearly states the tool pulls fired events from the subscription feed, specifies the return fields (source, citation_uri, raw payload), and distinguishes it from sibling tools by focusing on recent alerts retrieval.

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

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

The description mentions that polls work fine and provides an alternative access method (GET endpoint), giving clear usage context. However, it does not explicitly compare with sibling tools or state when not to use.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) already indicate safety. The description adds rich behavioral details: fan-out to multiple APIs, fallback from GDELT to GNews, soft-fail for USPTO due to sunset, and the return structure (changes[], total_changes, citation URIs). 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. It is front-loaded with example queries but could be more scannable with breaking into sentences or bullet points. However, every sentence adds value—no fluff. It earns a 4 for being effective but slightly unstructured.

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 3 parameters, full schema coverage, and rich annotations, the description covers the return format (changes[], total_changes, URIs), source details, fallback mechanisms, and when to use the sibling tool. No output schema exists, so the description compensates well by outlining the return structure. The agent has all necessary context to invoke correctly.

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

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

Schema coverage is 100%, so descriptions for all three parameters are present. The description expands on the 'since' parameter with examples ('2026-04-01', '7d', '30d', '3m', '1y') and a recommended default ('30d' or '1m'). For 'value', it clarifies ticker or CIK format. The 'type' parameter is noted as only 'company' supported. While helpful, the description doesn't detail how each parameter affects the fan-out logic, leaving room for improvement.

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

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

The description starts with user-facing example queries ('What's new with X') and clearly states it's a 'change feed for a company in the last N days/weeks/months in ONE parallel call.' It identifies the verb as 'recent changes' and distinguishes from the sibling 'entity_profile' by contrasting dynamic vs. static profile. The purpose is specific and unambiguous.

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

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

The description explicitly tells when to use the tool ('change feed...') and when to use the alternative ('Use entity_profile instead when you want the static profile...'). It also outlines the data sources (SEC EDGAR, GDELT→GNews, USPTO) and fallback behavior, providing situational guidance.

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

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

Annotations already provide idempotentHint=true, but description adds valuable behavioral details: scoped storage, persistence differences between authenticated and anonymous users (24 hours), and pairing with recall/forget. 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?

Four clear sentences with no filler information. Purpose stated first, followed by usage guidance, then storage details. Efficient and front-loaded.

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

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

Given only 2 simple parameters, no output schema, and good annotations, the description fully covers usage, storage semantics, 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 already covers both parameters with descriptions. The description adds example keys (subject_property, target_ticker) and clarifies the value as any text, slightly exceeding schema detail.

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

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

Clearly states the tool saves data for reuse across sessions, with specific examples of what to store (ticker, address, preference). Distinguishes from siblings (recall, forget) by implication.

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 mentions when to use ('when you discover something worth carrying forward') and pairs with recall/forget. Does not explicitly state when not to use, but context is clear.

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

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

The description discloses cascading internal lookups, graceful degradation of LEI/FIGI enrichment, and the explicit handling of unresolved identifiers. These behavioral details go well beyond the provided annotations (readOnlyHint, idempotentHint, etc.), enriching the agent's understanding of the tool's execution and failure modes.

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 practical examples and a clear purpose statement, then provides detailed type-specific information. Every sentence adds value, and the structure is logical: purpose → usage → supported types → behavioral nuances. It is 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?

With no output schema, the description thoroughly covers return values and behavior: it lists the identifiers returned, sources, unresolved handling, and degradation. It also covers accepted input formats. This is a complete and self-sufficient description for an agent to invoke the tool correctly.

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

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

Even though the schema already describes both parameters, the description adds substantial meaning: it details what each type returns (company identifiers with sources, drug identifiers), gives input examples, and explains edge cases like unresolved identifiers. This significantly exceeds the schema's basic coverage.

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

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

The description clearly states the tool resolves user-spoken names to canonical/official identifiers, with specific verbs and resources (ticker, CIK, LEI, FIGI, RxCUI). It distinguishes itself from siblings by explicitly positioning it as the first tool to use when you have a name but need an ID.

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

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

Provides explicit usage guidance: 'Use FIRST whenever you have a name but need an ID.' It also explains that it replaces 2-3 manual lookups. However, it does not name alternative tools or explicitly state when not to use it, so it lacks the full 'when-not/alternatives' spectrum.

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

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

Annotations already indicate readOnly, idempotent, openWorld, and non-destructive behavior. The description adds details about the internal process (calls ai_visibility_check for each entity), ranking, and output structure (score, confidence, signal density). No contradiction.

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

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

The description is three concise sentences: purpose, process, and use case/output. Front-loaded with the primary action, no 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?

Given no output schema, the description adequately explains return format (ranked list with scores). It also addresses the special handling of the first entity. Slightly more detail on output structure would improve completeness, but it is sufficient for effective use.

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

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

Schema coverage is 100%, but the description adds beyond it: explains that the first entity is treated as the subject for narrative, clarifies that models defaults to workers-ai, and provides concrete examples for the context parameter. This adds significant semantic value.

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

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

The description clearly states the tool compares AI visibility across multiple entities, uses ai_visibility_check internally, and returns a ranked list. It distinguishes itself from the sibling 'ai_visibility_check' and 'compare_entities' by specifying side-by-side comparison.

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

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

The description explicitly mentions the tool is useful for competitive AI-marketing audits with an illustrative example. However, it does not explicitly state when to use alternatives like ai_visibility_check for single entities, though this can be inferred from the mention of probing each entity with that 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 indicate readOnly, openWorld, idempotent, and non-destructive. The description adds significant behavioral details: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed will list timeouts. 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. It front-loads the composite nature and use case. Every sentence conveys useful information without redundancy. The structure flows logically from purpose to details to error handling.

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 lists the return fields (summary block, per-advisory detail, links, alternative versions). It covers edge cases like partial failures. Given the tool's complexity and rich annotations, the description is fully adequate.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by specifying scoped packages are accepted for 'package' and clarifying the default behavior for 'version'. It provides examples that enhance understanding beyond the schema.

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

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

The description clearly states it is a composite check for npm packages, combining deps.dev and bundlephobia. It specifies the exact purpose: evaluating safety, popularity, size. This distinguishes it from sibling tools which are broader research or platform-specific tools.

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

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

Explicitly states when to use: when an agent asks about safety, popularity, size, or cost of adding a package. Also provides exclusions: NPM only in v1, and directs to deps.dev:version for other ecosystems. This offers clear guidance on 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?

Despite comprehensive annotations (readOnlyHint, openWorldHint, etc.), the description adds rich behavioral context: embedding model (BGE-base-en), chunking strategy (500-char overlapping windows), input limit (200K chars with truncation flagging), and output details (passages with offsets and scores). 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 compact yet comprehensive, with purpose front-loaded in the first sentence. Every sentence adds unique value—no redundancy or filler. Ideal length given the tool's complexity.

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

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

The description covers all aspects: input (text, query, limit), output (passages with offsets and scores), algorithmic details, and usage pairing. Even without an output schema, the description sufficiently explains return values, making the tool fully understandable.

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

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

Schema has 100% description coverage for all three parameters, providing basic meaning. Description adds valuable context beyond schema, such as example queries and implicit behavior (e.g., 'limit' defaults to 5). This extra context elevates the 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?

The description clearly states 'Semantic search INSIDE a fetched record' with specific verb and resource. It distinguishes from sibling tools like 'ask_pipeworx_grounded' by mentioning pairing, making uniqueness 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?

Explicitly provides when to use: 'when the record is too big to cram into the prompt' and suggests pairing with 'ask_pipeworx_grounded' as an alternative context, offering clear usage guidance.

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

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

Adds behavioral details beyond annotations: OAuth requirement, subscription types, delivery options including webhook signing and SMS rate limits. No contradiction with annotations (idempotent, non-destructive, open-world).

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

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

Description is thorough but efficient; packs necessary details without redundancy. Could be slightly tighter but remains well-organized with key info front-loaded.

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

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

Covers all essential aspects: purpose, prerequisites, types, parameters, delivery channels, and return value. No output schema exists, but description adequately specifies the subscription id.

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?

Despite 100% schema coverage, description provides rich examples for each type's params and delivery options, adding significant meaning and usage 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?

Description clearly states 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' It uses a specific verb and resource, and 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?

Includes prerequisite ('Requires a Pipeworx OAuth account') and discusses alternative delivery channels. Could explicitly state when not to use, but provides adequate context for decision-making.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds behavioral details such as the return format (category-bucketed examples with exact tool+argument shape) and the ability to call with no arguments for a full spread. 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 three sentences long, front-loaded with common queries, and packs substantial information without unnecessary fluff. Slightly verbose due to listing all categories, but generally 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 has only one optional parameter, no output schema, and rich annotations, the description fully explains what the tool does, how to use it, and why. It covers the return value, usage patterns, and relationship to sibling tools, making it complete for the task.

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% (one optional parameter with description). The description adds that calling with no arguments gives a 'full spread' and that passing a topic focuses results. This adds some value but does not significantly extend the schema's clarity; baseline 3 is appropriate.

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

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

The description clearly states that the tool returns category-bucketed example questions for onboarding, using specific verbs like 'returns' and 'call'. It distinguishes itself from sibling tools by positioning as the entry point for new agents, saying 'Use this FIRST when you do not yet know what Pipeworx can do for you.'

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 FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. It names related tools (ask_pipeworx, entity_profile, etc.) but does not explicitly specify when not to use it, which is acceptable given the onboarding 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?

Discloses key behavioral traits beyond annotations: ownership enforcement, deactivation vs deletion, and impact on historical events. No contradictions with annotations; the description adds valuable context.

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

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

Two concise sentences front-load the key action, followed by important behavioral details. No filler or repetition.

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 (single required parameter, no output schema), the description fully covers purpose, constraints, and side effects. 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?

Only one parameter 'id' with schema description 'Subscription id (uuid) returned by subscribe.' The description adds no additional semantics beyond what the schema already provides. With 100% schema coverage, baseline 3 is appropriate.

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

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

The description clearly states the action ('Cancel a subscription') and the resource ('by id'). It effectively distinguishes from sibling tools like 'subscribe' and 'list_subscriptions' by specifying the operation and scope.

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

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

Provides explicit guidance on ownership enforcement ('you can only cancel your own subscriptions') and the nature of the cancellation ('deactivated, not deleted'), including the rationale for historical availability via recent_alerts. This helps the agent choose this tool appropriately.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior. The description adds critical semantic context: 'could_not_verify' means the check did not happen and must not be treated as evidence, while 'unsupported' means no source covers it. It also explains how the grounded pipeline vs structured fast path behave, which is not available in annotations.

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

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

The description is dense but every sentence serves a purpose: trigger phrases, usage context, routing logic, return values, and caller warnings. It is long but appropriate for the tool's complexity, though it could benefit from bullet-point formatting for easier scanning.

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

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

Without an output schema, the description fully explains the return envelope: verdict enum, actual value with pipeworx:// citation, and reasoning. It thoroughly disambiguates failure modes (could_not_verify vs unsupported) and explains how the tool replaces a multi-step workflow. This is complete for the tool's complexity.

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

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

Schema coverage is 100% and both parameters (claim, tolerance_pct) already have detailed descriptions. The tool description adds nothing beyond the schema, though the mention of 'exact percent-delta math' subtly reinforces tolerance_pct's role. Meets baseline but does not exceed it.

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

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

The description uses specific verbs ('verify', 'fact check', 'confirm or refute') and identifies the resource (natural-language claims) and the output (a verdict with evidence). It clearly distinguishes itself from sibling tools by positioning as a single-call verifier that replaces 4–6 sequential pipeline steps.

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

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

Explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct' and provides routing rules for company-financial claims vs any other factual claim. It does not name alternative sibling tools or give specific when-not-to-use cases, but the guidance is clear and actionable.

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