Passive Aggression

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive nature. The description adds significant behavioral context: default model (Workers AI Llama-3.3-70b free), cost implications for Anthropic (BYO key), and return structure (per-model score, confidence, signals, raw_response + combined view). 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 three sentences: first sentence states core action and output, second explains parameters and cost, third gives use cases. Every sentence earns its place, no fluff, 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 the tool's complexity (multi-model probing, scoring, multiple parameters), the description covers purpose, all parameters with usage notes, return format, and use cases. No output schema exists, but the description adequately explains the response structure.

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 4 parameters. The description adds value beyond schema: default model behavior, that _apiKey is only needed for Anthropic, and that context helps disambiguate. This enriches parameter understanding.

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

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

The description clearly states the tool's purpose: probing LLMs for knowledge about an entity and scoring visibility (0-100) per model. It specifies the verb (probe, score), resource (LLMs, visibility), and distinguishes from sibling tools like ask_pipeworx or compare_entities, which focus on different tasks.

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 use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' While it doesn't list exclusions or compare to alternatives, the context is clear enough for an agent to infer 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, openWorldHint, idempotentHint, and destructiveHint false. The description adds significant behavioral context beyond these: it explains routing behavior, citation URI stability, 'works on every tier, one fast call', and that it can handle live news. No contradiction with annotations; instead it enriches the operational 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?

The description is front-loaded with a strong 'PREFER OVER WEB SEARCH' directive, followed by clear usage examples and alternatives. It is longer than average, but every section serves a purpose: differentiation, examples, escalation paths, and integration notes. The structure is logical and skimmable, though slightly verbose.

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

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

Given the tool's complexity (routing across thousands of sources), the description is highly complete. It covers purpose, when to use, alternatives, examples, and even mentions edge cases like breaking news. Although no output schema exists, the description fully explains the expected return (structured answer with citations).

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 the question parameter fully documented and aliases listed. The description does not need to add parameter-level detail, but it does provide illustrative examples of valid questions. This meets the baseline for high schema coverage, offering only marginal extra value beyond the schema.

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

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

The description clearly states the tool's function: it routes questions to the appropriate tool among 5,529 tools across 1,455 verified sources, fills arguments, and returns structured answers with stable citation URIs. It uses specific verbs like 'routes' and 'returns', and explicitly differentiates itself from web search and sibling tools like ask_pipeworx_grounded and deep_research.

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

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

The description provides explicit when-to-use guidance: 'PREFER OVER WEB SEARCH' and 'START HERE for most questions', with examples. It also names alternatives and when to use them: 'Step up only when needed: for a hallucination-resistant single answer... use ask_pipeworx_grounded; for a broad/multi-part question... use deep_research'. This fully satisfies the dimension.

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

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

Given annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, the description adds valuable behavioral context beyond these: it is a beta with candidate routing enabled live, currently matches ask_pipeworx exactly, and results feed into merge decisions. This fully sets expectations about the experimental nature and current state without contradicting 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 distinct purpose: stating the beta status and equivalence, giving usage guidance, and confirming it is a fully functional router. Information is front-loaded with the core identity and 'Beta' label, followed by current state and usage. No wasted words or repetition of schema contents.

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 essential context: what it is (beta), what it does (universal router), current state (no candidate active), usage instructions, and the no-fallback guarantee. It does not explicitly define the routing concept or return format, but it references ask_pipeworx and the same response shape, which is sufficient given the sibling context and annotations. Slightly incomplete for agents unfamiliar with ask_pipeworx, but adequate overall.

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

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

The schema covers 100% of the parameter descriptions, including all aliases for the 'question' parameter. The description adds that it accepts the same arguments as ask_pipeworx and mentions 'same response shape,' which reinforces parameter usage but does not provide new semantic details beyond what the schema already documents. This is above the baseline of 3 due to the explicit cross-reference to the sibling tool, aiding inference about parameter behavior.

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

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

The description clearly identifies this as a beta version of ask_pipeworx and specifies it is an identical universal router with the same 5,529 tools and arguments. It differentiates from the stable sibling ask_pipeworx by highlighting the experimental routing candidate. However, it does not explicitly explain what 'universal router' does (e.g., routes natural language to tools), which slightly reduces clarity for an unfamiliar agent.

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 it exactly like ask_pipeworx when you want the newest routing.' It also clarifies that results are compared against the stable router and that this is a full working router, not a fallback. The alternative (ask_pipeworx) is implicitly the stable choice, and the description distinguishes the experimental context well.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses critical behavioral details: that the answer is extracted ONLY from the tool result, the exact return shape, the five possible refusal reasons, and the extra LLM call cost. This is far beyond what annotations provide and gives the agent a complete behavioral contract.

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 highly structured: purpose, mechanism, return contract, usage scenarios, and cost trade-off. Each sentence carries distinct value, and the most decision-relevant information (purpose and usage) is front-loaded. 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 tool's complexity (no output schema, multiple refusal modes, interaction with 5,529 tools), the description is fully complete. It explains the return shape and refusal structure, when to use versus alternatives, safety (read-only), and performance cost. No gaps remain, so the agent can confidently select and invoke this 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% and every parameter is documented as an alias for the question string (q, text, input, query, prompt). The description adds no parameter-specific detail, but the schema already fully covers parameter semantics, so the baseline score of 3 is appropriate.

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

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

The description opens with 'Hallucination-resistant answer mode for high-stakes reads,' which clearly identifies the tool's specific purpose and scope. It explicitly distinguishes itself from the sibling ask_pipeworx by describing the extra extraction step and when each should be preferred, ensuring the agent can differentiate between them.

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

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

Provides explicit usage guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with concrete examples. It also gives an exclusion rule, 'prefer ask_pipeworx for casual lookups,' and explains the cost trade-off (one extra LLM call), making the when-to-use decision unambiguous.

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, openWorldHint, idempotentHint true, and destructiveHint false. The description goes far beyond by detailing fan-out behavior, classifier logic, resolution confidence handling, closed market handling, spread warnings, and cancellation rule parsing. This provides comprehensive behavioral transparency.

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

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

The description is lengthy but well-structured with bolded sections and front-loaded purpose. Every sentence adds value, but some conciseness could be achieved without losing important details. Overall, it is organized 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?

Given the complexity of the tool (multiple data sources, response shapes, resolver logic), the description covers all essential aspects: input formats, evidence sources, response fields, safety behaviors, cancellation rules, and error handling. No output schema exists, but the description compensates thoroughly.

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 all three parameters described. The description adds further context: market can be slug, URL, or question text; depth enum explained; include_raw clarified. This exceeds the schema alone, making parameter semantics exceptionally clear.

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: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It provides specific use cases like 'should I bet on X' and distinguishes it from sibling tools by focusing on Polymarket bet research with integrated data sources.

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

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

The description gives explicit usage contexts and examples of when to use the tool (e.g., 'what does the data say about Y'). It also includes practical guidance on inspecting market_match_confidence and other fields. However, it does not explicitly state when not to use this tool or mention alternatives, which would strengthen the guidelines.

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, idempotent, non-destructive behavior. The description adds valuable details: specific data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorting by primary metric, and return format including 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 front-loaded with triggers and purpose, well-structured with clear sections. While comprehensive, it is slightly verbose; a minor tightening could improve conciseness. Overall, 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?

Given the tool's complexity (two entity types, different data sources) and no output schema, the description is remarkably complete. It explains return format (paired data + citations), sorting behavior, and covers both company and drug use cases thoroughly.

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

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

Input schema has 100% coverage with descriptions for both parameters. The description adds extra meaning: examples of tickers/CIKs for company, drug name formats, and explains how values are used. A small deduction because the schema already provides adequate 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's purpose: side-by-side comparison of 2-5 companies or drugs in one call. It lists multiple natural language triggers and explicitly distinguishes from sequential lookups, making the purpose unambiguous.

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

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

The description explicitly says when to use this tool (for comparisons) and when to prefer it over alternatives ('ALWAYS PREFER over sequential single-pack lookups'). It also explains key context for each entity type, guiding correct invocation.

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, etc.), the description adds substantial behavioral context: account/login requirement, paid tier for thorough, latency expectations, the structure of the findings packet, use of gaps[] to indicate unanswered facets, contradictions[] for disagreeing findings, hop field, and the fact that records are semantically excerpted to relevant passages. It also notes that citations are always fetchable, adding trust 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 dense and well-organized, front-loading the critical account requirement and then logically progressing through use cases, features, and timing. It is longer than typical but justified by the tool's complexity. Minor redundancy exists (e.g., 'gap recovery' and 'contradictions[]' are mentioned multiple times), so a slight trim would improve it, but it remains 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?

With no output schema, the description does the heavy lifting by explaining exactly what the caller gets: verbatim evidence, confidence, source, fetched_at, citation_uri, gaps[], contradictions[], and hop field. It also covers latency, account tiers, and behavior when the topic is outside the structured catalog. For a tool of this complexity, the description is remarkably 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?

Although schema coverage is 100%, the description adds extra meaning to both parameters: for 'question', it clarifies that broad/multi-part questions are the intended use case; for 'depth', it explains the practical implications of each enum value (e.g., quick=3 facets, standard=5 with gap recovery and contradictions, thorough=8 and paid). This enriches the bare schema definitions materially.

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 grounded multi-source research tool that decomposes questions, routes facets across many tools in parallel, and returns a structured findings packet. It explicitly distinguishes itself from ask_pipeworx ('For a single lookup use ask_pipeworx') and mentions it is NOT open-web search, so the purpose is unambiguous even among siblings.

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

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

The description explicitly states when to use deep_research ('Best for broad/multi-part questions') and when NOT to use it, offering alternatives: 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. It also mentions account requirements and tier restrictions, giving the agent actionable decision rules.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, covering safety. The description adds that it returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' This explains the return behavior and efficiency benefit, adding value beyond annotations.

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

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

The description is somewhat long but each sentence serves a purpose: stating function, listing use cases, explaining return value, and providing strategic guidance. It is front-loaded with the primary action. Could be slightly more concise but remains effective.

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

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

Given no output schema, the description explains what is returned (names, descriptions, full schemas, examples). Parameter coverage is 100%. The tool's purpose is unique among siblings. It provides a complete picture for an agent to decide to use it.

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

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

Schema description coverage is 100% with all parameters having descriptions, including aliases. The description itself does not add much parameter-level meaning beyond the schema, but it provides example queries ('look up FDA drug approvals', 'analyze housing market trends') which are helpful. Baseline 3 is appropriate.

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

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

The description clearly states the tool finds tools by describing data or task, listing many example domains. It distinguishes itself from sibling search/ask tools by being specifically for discovering tools, with a specific verb 'discover' and resource '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?

Provides explicit guidance: 'Use when you need to browse, search, look up, or discover what tools exist for: [list]' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This effectively tells when to use and the strategic priority.

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 and idempotent behavior. The description adds valuable context: it fans across multiple sources, returns specific fields (filings, fundamentals, patents with soft-fail, news fallback), and reveals internal data sourcing 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 front-loaded with multiple usage examples and uses active voice. Though somewhat lengthy, each sentence adds value (data sources, limitations, fallback behavior). Could be slightly tighter but remains effective.

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

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

Despite no output schema, the description extensively details return fields (CIK, filings with URIs, fundamentals, patents, news, LEI) and handling of edge cases (patents soft-fail, name resolution prerequisite). It is fully sufficient for an agent to understand the tool's capabilities 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 coverage is 100% with descriptive parameter names. The description adds meaning by specifying allowed values for 'type' (only 'company'), and clarifying that 'value' must be a ticker or zero-padded CIK (not names), enhancing the schema's details.

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

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

The description uses specific verbs like 'profile' and resources 'US public company', with example queries. It clearly distinguishes from siblings like 'resolve_entity' (name resolution) and 'compare_entities' (comparison), making the tool's unique role evident.

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 'ALWAYS PREFER over chaining single-pack...' and clarifies when to use 'resolve_entity' first for name-based inputs. Also notes unsupported types (person/place) and value formats, providing comprehensive usage guidance.

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

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

Annotations already provide destructiveHint=true and idempotentHint=true. Description adds 'clear sensitive data' but does not substantially expand beyond what annotations convey. No additional behavioral details like permissions or side effects.

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

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

Two sentences with no fluff. First sentence states purpose, second gives usage guidance. Every word earns its place.

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

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

For a simple tool with one parameter and full schema coverage, the description is complete. It explains what it does, when to use, and related tools. No gaps.

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

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

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

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

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

The description clearly states 'Delete a previously stored memory by key,' which specifies the verb (delete) and the resource (memory by key). It distinguishes from siblings by mentioning 'Pair with remember and recall.'

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

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

Explicitly states when to use: 'when context is stale, the task is done, or you want to clear sensitive data.' Also names alternatives/related tools: 'Pair with remember and recall.'

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, which the description supports by stating it fetches and extracts data without modification. The description adds context about the process (fetching, extracting, emitting markdown), 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 concise with four sentences, front-loading the main purpose and output format. Every sentence adds value without redundancy, making it efficient for an AI agent to parse.

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

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

Despite no output schema, the description clarifies the output is a single text blob for site-root/llms.txt, which fully informs the agent about the return value. The tool is simple with only two parameters, so the description provides complete context.

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

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

Schema description coverage is 100% for both parameters ('url' and 'max_links'), so the description does not need to add significant new information. The baseline of 3 is appropriate as the schema already documents the parameters adequately.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, detailing the extraction and output format. It distinguishes itself from sibling tools like 'ai_visibility_check' and 'scan_competitor_ai_presence' by focusing specifically 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?

The description explicitly lists three use cases: getting a client's site indexed, drafting for own project, or auditing competitor visibility. While it does not mention when not to use or alternatives, the context is clear and sufficient for 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 indicate readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds that it returns specific fields and is scoped to the caller, which is useful but not essential since annotations cover safety.

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 two sentences: one stating purpose and return fields, the other providing usage guidance. 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 tool's simplicity, the description covers all needed context: what it does, what it returns, and when to use it. Sibling tools provide further context.

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

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

Schema coverage is 100% and the single parameter is well-described in the schema. The description does not add additional semantics beyond what is already present.

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

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

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

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

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

The description explicitly advises when to use the tool: 'review what you're monitoring before adding more or to find an id to cancel.' This gives clear context and implies alternatives (subscribe/unsubscribe).

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint true, and destructiveHint false; description adds that it returns severity score, flagged phrases, explanations, plain English translation, and suggested direct responses. No contradictions.

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

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

Two sentences: first covers purpose and outputs, second gives usage context. No wasted words, front-loaded with 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?

Tool has 3 simple parameters, output schema exists (though not provided in input), description lists all expected outputs. Annotations cover safety and idempotency. Sufficiently complete for an analysis tool.

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

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

Schema coverage is 100% with descriptions for each parameter. The description does not add additional parameter-level meaning beyond what the schema provides.

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

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

The description clearly states the tool analyzes text for passive-aggressive language and lists outputs. It is specific and distinct from sibling tools, which are unrelated.

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: 'reviewing emails, messages, or conversations to identify underlying hostility'. It provides clear context but does not discuss when not to use or mention 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 adds substantial behavioral context beyond the annotations: rate limiting ('Rate-limited to 5 per identifier per day'), the claim_token mechanism for reading resolution status, and the side effect of sending feedback to a human team. It does not contradict the readOnlyHint=false or other 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 longer than typical but every sentence serves a purpose: purpose, when-to-use, exclusions, token handling, and rate limits. It is front-loaded with the primary action. Though verbose, the complexity of the tool justifies the length.

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

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

Despite having no output schema, the description covers the key scenarios, the claim_token lifecycle, and the quota policy. It gives the agent enough context to invoke the tool correctly and interpret the response without further documentation.

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

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

Schema coverage is 100%, so baseline is 3. The description adds extra meaning for claim_token ('pass it back later... to read whether it was fixed') and clarifies the type categories in the usage guidance. This exceeds the schema descriptions, warranting a 4.

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

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

The description opens with a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' This clearly distinguishes it from sibling tools, which are all research or subscription-related, by positioning it as the feedback channel for the Pipeworx toolset.

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

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

Explicit usage guidance is provided: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives a clear exclusion: 'if the tool came from a different MCP server... file it with that server instead.' This tells the agent exactly when to invoke and when not to.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. Description adds valuable context: caching window (5min-1h), data source (CF analytics-engine), privacy (no PII), and self-aggregating nature. No contradictions.

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

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

Description is a single paragraph with clear structure: what it does, return contents, three use cases, and metadata. Every sentence adds value; no fluff. 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?

Despite no output schema, the description specifies the return structure: 'top tools, top packs, and total call volume.' Caching behavior, privacy, and data source are covered. No gaps remain for an agent to use this tool correctly.

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

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

Schema covers 100% of the single parameter with an enum and description. The description adds guidance on how to choose windows: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This provides decision-making 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 it returns top tools, top packs, and total call volume over recent windows. The verb 'Returns' and specific resource (trending usage on Pipeworx) make the purpose unambiguous. Distinguishes from siblings like discover_tools and recent_changes by focusing on aggregated usage signal.

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?

Three explicit use cases are listed: discovering hot data sources, confirming a canonical tool, and checking alignment with agent needs. While it doesn't explicitly state when not to use, the context is clear enough for an agent to decide.

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

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

The annotations (readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false) already indicate safety. The description adds rich behavioral context: fill check against live CLOB depth, semantic anchor for cross-event pairs, partition filter, and detailed return format. 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 well-structured, with a clear front-loaded summary and logical progression through modes, filters, and fill check. Each sentence adds value; minor redundancy could be trimmed but overall 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?

Given the tool's complexity (three modes, partition filter, similarity check, fill check) and no output schema, the description covers all aspects: return format (opportunities[], partition_check), edge cases (placeholder slugs, low similarity), and actionable guidance (when not to trade). Very 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%, but the description adds substantial meaning beyond the schema. It explains event slug vs topic, examples, and how each mode affects behavior (e.g., partition_check, cross-event similarity). This provides critical context for correct invocation.

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 on Polymarket via monotonicity violations and partition-sum checks. It distinguishes three modes (no-args, event, topic) with specific use cases, making it distinct from sibling tools like polymarket_edges or polymarket_fill_risk.

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

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

The description explicitly states when to use each mode: no args for trending scan, event for a specific market, topic for cross-event scanning. It also warns when not to trade (realizable_edge_pp ≤ 0) and directs to polymarket_fill_risk for custom sizing.

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

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

The description extensively covers behavioral traits beyond annotations: model families, caching (1h at KV level), response structure, warnings like 'Market moved X.Xpp in 24h', and details on edge calculation. This adds significant value beyond the readOnlyHint, openWorldHint, and idempotentHint annotations.

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

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

The description is dense and technically rich, but overly verbose. It contains extensive details on model families and internal logic that, while informative, could be more concise. The structure is logical but not front-loaded; the core purpose is stated early, but the length may hinder quick parsing.

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 lack of output schema, the description fully explains the return structure (by_segment, fed_candidates, _diagnostics) and each opportunity's fields. It also covers caching behavior, edge calculation, and filter rationale, making it complete for an intelligent 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 detailed parameter descriptions. The tool description adds context on how parameters interact (e.g., min_partition_leg_kelly vs min_kelly, tradeable-edge knobs). This enhances understanding beyond the schema alone, justifying 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?

The description explicitly states the tool scans top Polymarket markets to find opportunities where Pipeworx data disagrees with market price. It clearly defines the use case: 'what should I bet on today'. It distinguishes itself from siblings like polymarket_arbitrage by detailing unique model families and output structure.

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

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

The description provides clear context on when to use the tool—for discovering betting opportunities without paging hundreds of markets. It explains tradeable-edge knobs and filters, but does not explicitly compare to sibling tools or state when not to use it. The implied usage is clear but lacks explicit exclusions.

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

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

Annotations already indicate readOnlyHint, idempotentHint, and not destructive. The description adds valuable behavioral context: data source (daily snapshots), potential gaps ('snapshots are written when polymarket_edges runs on a cache-miss'), decay computation basis ('daily closes of edge_pp_net, not intraday'), and TTL (60-day). This goes beyond the annotations without contradicting them.

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

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

The description is moderately long but efficiently packed. It front-loads the purpose in the first sentence, then clearly structures the response fields (tracked[], expired[], snapshot_dates[]) with inline explanations. Every part adds value, though it could be slightly tighter.

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 compensates by detailing the response structure: tracked[] with time-series, first_seen, trend, decay_pp_per_day; expired[] with lifespan_days and median lifespan; snapshot_dates[]. It also covers LIMITS on history depth, leaving no significant ambiguity about what the tool returns.

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

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

Schema coverage is 100% with both parameters described. The description adds the default values (14 for days, '1wk' for window) and additional context (days max 30, window as 'snapshot family'). This meaningfully supplements the schema, though the schema already covers the core meaning.

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

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

The description begins with a clear, specific verb+resource: 'Edge persistence and decay telemetry'. It then answers the core question 'how long has this edge existed and is it shrinking?', explaining the nuance between fresh and old wide edges. This distinguishes it from siblings like polymarket_edges, which likely provides raw edge data.

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

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

The description explicitly states when to use this tool over alternatives via the trade example: 'a fresh wide edge and a 3-week-old wide edge are different trades (the latter is wide for a reason nobody is willing to take).' It also includes LIMITS that clarify history depth and data characteristics, guiding appropriate 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 declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=False. Description adds behavioral context: walks the ladder, returns verdict (clean|degraded|cannot_fill), identifies thin_legs and forced_directional_risk. Warns about partial basket fills converting arb to directional position. 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 bold headers and bullet points. Somewhat lengthy but every sentence adds value. Could be slightly more concise, but very clear and 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 complexity (two modes, multiple return fields, no output schema), the description covers purpose, usage, parameter details, risks, and returns. Provides enough context for an agent to decide when and how to invoke the tool.

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

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

Schema coverage is 100%; description adds meaning beyond schema: explains side parameter in both single-market and basket contexts, clarifies size_usd interpretation (max spend on buys, target proceeds on sells, settlement notional for baskets), provides default 1000 and clamp range.

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 'Realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes between single-market and basket modes. The description details what the tool returns (e.g., top_of_book, vwap_fill_price, slippage, verdict) and differentiates from sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

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.' Provides reasons why (theoretical overround not capturable on thin books, partial basket fills create directional 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 goes beyond annotations to detail behavior: it fetches from both venues, compares legs, and provides safety fields (compatibility_warning, temporal_alignment, skipped_cross counters). It explains edge cases like mismatched bet shapes and temporal misalignment.

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 (modes, response, safety fields). Every sentence adds value. It is front-loaded with the main purpose, though it could be slightly 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?

Despite having no output schema, the description thoroughly explains the response structure (leg-by-leg prices, top_spreads_pp, safety fields, temporal alignment, skipped counters). It also covers error conditions and when spreads are meaningless, making it complete for an agent to invoke correctly.

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

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

The input schema covers all three parameters (two optional) with examples and descriptions. The description adds context: the topic macro list, the fact that explicit tickers override topics, and the behavior of the mode selection, which is valuable 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 that the tool computes cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes itself from sibling tools by focusing on cross-venue comparison and explains two modes of operation.

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

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

The description explains when to use the tool (to find spreads) and provides explicit usage modes (topic shortcuts vs. explicit tickers). It also warns that pre-mapped topics often return compatibility warnings, but does not explicitly contrast with alternatives like polymarket_arbitrage.

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 idempotentHint=true. The description adds context about scoping (anonymous IP, BYO key hash, account ID) and pairing with remember/forget, 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?

Three sentences front-load the primary function, then provide examples, use case, and scoping. Every sentence adds value with no waste.

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, good annotations, and no output schema, the description fully covers purpose, usage, and constraints.

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

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

Schema coverage is 100% for the single parameter 'key'. The description adds the meaning of omitting it to list all keys, which goes beyond the schema's 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 states 'Retrieve a value previously saved via remember, or list all saved keys', which is a specific verb+resource combination. It clearly distinguishes from siblings like remember and forget.

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

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

It explicitly states when to use: 'to look up context the agent stored earlier', and implies when not to use by noting 'without re-deriving it from scratch'. It also mentions scoping and pairing with other tools.

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

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

Annotations already declare readOnly, idempotent, non-destructive. Description adds behavior: mark_read:true flags events as read for next call, and explains return fields (source, citation_uri, payload). 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?

Three sentences, each earning its place: purpose, filtering options, behavioral note and alternative. No wasted words.

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

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

Given no output schema, description explains return data (source, citation_uri, payload) and mentions polling/alternative endpoint. Missing explanation of unread_only parameter, but schema covers it.

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

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

Schema covers 100% of parameters with descriptions. The description adds extra meaning for mark_read (how it affects future calls) beyond the schema, but does not mention all parameters (e.g., unread_only).

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 'Pull fired events from your subscription feed' with specific resources and fields, clearly distinguishing from sibling tools like list_subscriptions and subscribe.

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 context: mentions polling works fine and points to an alternative direct endpoint for scripts/dashboards, but lacks explicit when-not-to-use guidance for the tool itself.

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 explains the multi-source fan-out, fallback from GDELT to GNews, and the soft-fail of USPTO. It describes the return structure (changes[] grouped by source). It does not detail rate limits or caching, but 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?

The description is moderately long but front-loaded with practical examples. Each sentence contributes distinct information (sources, fallback, parameter details). Minor redundancy could be trimmed but overall well-structured.

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

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

Despite having no output schema, the description sufficiently covers return structure. It explains all data sources, fallback logic, and the soft-fail for one endpoint. For a complex tool, this is comprehensive enough for an agent to use correctly.

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

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

With 100% schema coverage, baseline is 3. The description adds value by explaining 'since' syntax in detail, suggesting typical values, and clarifying that 'value' accepts ticker or CIK. It also notes 'type' is currently limited to 'company'.

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 provides a change feed for a company (SEC filings, news, patents) within a time window. It distinguishes from the sibling tool entity_profile, which gives static profiles, and uses concrete examples like 'updates on Acme' to clarify its 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 says to use entity_profile when a static profile is needed, providing clear when-not guidance. It also lists example queries, indicating appropriate use cases without repetition.

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

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

Annotations include idempotentHint: true (write is idempotent) but no mention of persistence. The description adds critical behavioral details: 'Stored as a key-value pair scoped by your identifier. Authenticated users get persistent memory; anonymous sessions retain memory for 24 hours.' No contradiction with annotations.

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

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

Four sentences: purpose, usage guide, behavioral detail, companion tools. Each sentence serves a distinct purpose with no wasted words. Front-loaded with the core action.

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

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

For a simple write tool with 2 parameters and no output schema, the description covers all necessary aspects: what it does, when to use, persistence behavior, scope, and companion tools. Nothing 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 description coverage is 100%, but the description adds value by providing example keys in the key description ('subject_property', 'target_ticker') and clarifying value type ('any text — findings, addresses, preferences, notes'). This enhances the schema's already clear 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's purpose: 'Save data the agent will need to reuse later — across this conversation or across sessions.' It uses a specific verb ('Save') and resource ('data to reuse later'), and distinguishes itself from sibling tools 'recall' and 'forget' by mentioning them as companions.

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 tells when to use: 'Use when you discover something worth carrying forward...' and provides exclusions: 'Pair with recall to retrieve later, forget to delete.' This gives 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?

Annotations already indicate read-only/idempotent/non-destructive, but the description adds substantial behavioral detail: graceful degradation when GLEIF/OpenFIGI is unavailable, explicit `unresolved` field rather than omission, source labeling for each identifier, and internal cascading through multiple endpoints. These go well 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?

The description is dense and every sentence contributes useful information, but the opening list of example queries is somewhat lengthy. It is well-organized with supported types and fallback notes clearly separated, though it could be tightened without losing value.

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

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

Since there is no output schema, the description thoroughly explains return values for both entity types: CIK/ticker/company_name, LEI with ownership hierarchy, FIGI, RxCUI with ingredient/brand, and the `unresolved` field. It also covers failure modes (GLEIF/OpenFIGI unavailable) and confirms that EDGAR identifiers still return, making it complete for this complex tool.

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

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

The input schema already describes both parameters with 100% coverage, including value formats for company and drug. The description reinforces these with examples but does not add significant new parameter-level meaning beyond what the schema provides, so the 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 the tool resolves user-spoken names to canonical/official identifiers, with a specific verb ('resolve') and resource ('entity names to IDs'). It includes a rich set of example queries and explicitly says 'Use FIRST whenever you have a name but need an ID', distinguishing it from siblings like compare_entities or entity_profile.

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

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

Provides explicit when-to-use guidance ('Use FIRST whenever you have a name but need an ID') and explains that it replaces 2-3 manual lookups. However, it does not mention any exclusions or alternative tools, so it falls short of fully explicit when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds valuable behavioral context: it probes each entity with ai_visibility_check, ranks by score, and surfaces which is most/least recognized. It also describes the return structure (score, confidence, signal density). 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 four well-structured sentences with the main purpose front-loaded. Every sentence adds value: purpose, behavior, use case, return format. 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?

Given the tool has 4 parameters, no output schema, and moderate complexity, the description explains the return structure (ranked list with score, confidence, signal density) and the underlying process (probes ai_visibility_check). It covers the essential behavioral and output aspects, though it omits potential edge cases (e.g., ties) or 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 description coverage is 100%, so the schema already describes each parameter. The tool description adds meaning beyond the schema: it explains that the first entity is treated as the 'subject' for narrative and the rest as competitors, and provides context on the 'context' parameter ('disambiguates common names'). This additional guidance enhances understanding.

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

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

The description clearly states the tool's purpose: 'Compare AI visibility across multiple entities side-by-side.' It specifies a specific verb ('compare'), resource ('AI visibility'), and scope ('multiple entities'). The 'side-by-side' and ranking aspects differentiate it from siblings like ai_visibility_check (single entity) and compare_entities (generic 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 provides clear usage context: 'Useful for competitive AI-marketing audits' with an example question. It implies when to use (multi-entity comparison) but does not explicitly state alternatives or when not to use. The context signals list ai_visibility_check as a sibling, hinting at the single-entity alternative, but the description could be more explicit.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds value by explaining the composite nature, partial failure handling (bundlephobia timeout, sources_failed), and timing behavior (5-30s for first measurement). 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?

Description is relatively long but well-structured with front-loaded purpose and clear details. Every sentence adds value; minor redundancy could be trimmed but overall 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 composite external service nature and no output schema, description thoroughly covers inputs, behavior, limits, partial failure, and output fields. Complete for agent guidance.

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

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

Schema coverage is 100%, so baseline is 3. Description adds nuance by clarifying scoped packages accepted and version defaulting to latest, which is already in schema but reinforces usage.

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 using deps.dev and bundlephobia, covering safety, popularity, and size. It distinguishes from siblings by noting NPM-only in v1 and fallback to deps.dev:version 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?

Explicitly says 'Use whenever an agent asks...' and gives concrete examples. Also provides context about when not to use (other ecosystems) and alternatives (deps.dev:version directly).

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds significant behavioral details beyond annotations: embedding model (BGE-base-en), similarity metric (cosine), chunking (500-char overlapping windows), character offsets in results, and a 200K char cap with truncation flag. 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 concise and well-structured. It starts with the core purpose, then provides usage conditions, examples, and technical details. Every sentence adds value. Formatting with bold and capitalization aids readability without excess.

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 (top-N passages with offsets and scores) and internal algorithm. For a tool with 3 parameters and moderate complexity, this covers all necessary information for correct 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%, so the description adds context beyond schema. It explains the max size for 'text', provides example queries for 'query', and specifies the range and default for 'limit'. This adds meaningful context for an agent to select appropriate 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 semantic search inside a fetched record, using specific verbs like 'Semantic search INSIDE' and provides examples (SEC 10-K). It distinguishes from siblings by mentioning its pairing with ask_pipeworx_grounded and its focus on local text retrieval rather than external 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?

The description explicitly states when to use the tool: when the record is too large for the prompt, and provides an alternative strategy: fetch with gateway and ground over passages. It gives concrete examples of queries and explains the benefit (saving context, returning relevant passages with offsets for verification).

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: OAuth requirement, phone verification, 10/day SMS cap, webhook signing secret returned once, auto-disable after 10 failures. Annotations only hint at read/write and idempotency.

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

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

Single paragraph is well-structured with colons and examples, but dense. Could be broken into sections for easier scanning; still efficient overall.

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

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

Covers all required aspects: subscription types, delivery options, constraints, return value (subscription id). No gaps given tool complexity and annotations.

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

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

Schema coverage is 100%, but description adds significant value: explains each type's params with examples, delivery sub-schema details (email, sms, webhook with signing and limits). Goes far beyond 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 'Create a proactive monitoring subscription to a live-data event stream', specifying the verb and resource. 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?

Provides clear context for when to use, including supported types and delivery channels. Implicitly excludes anonymous users by requiring Pipeworx OAuth. Lacks explicit when-not guidance but sibling names provide 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 cover readOnly, idempotent, non-destructive behavior. The description adds context about the return format (category-bucketed questions with tool+argument shapes) and that it draws from a live catalog, which is useful 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 comprehensive but slightly verbose. It front-loads with common user queries and explains usage well; however, some sentences could be tightened.

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

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

Given the tool's simplicity (1 optional param, no output schema) and rich annotations, the description covers purpose, usage, behavior, and parameter meaning completely. No gaps remain.

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

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

Schema coverage is 100% for the single optional parameter. The description adds that omitting topic gives a full spread, and lists example values, adding meaning beyond the schema's generic string description.

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

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

The description clearly states the tool returns categorized example questions with tool calls. It lists specific categories and distinguishes itself as the onboarding entry point, differentiating from sibling tools like 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?

Explicitly advises using this tool first when the agent doesn't know what Pipeworx can do, and to learn how to call meta-tools. Mentions alternatives (ask_pipeworx, entity_profile), but lacks explicit when-not-to-use guidance.

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

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

Discloses that operation is not destructive (deactivates, not deletes) and enforces ownership, adding beyond annotations. No contradictions with annotations (idempotentHint=true, destructiveHint=false).

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-loaded with the action. Every sentence adds necessary context.

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 ownership, behavioral effects, and parameter source, making it fully complete.

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

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

Single parameter 'id' is fully described in schema. Description does not add meaning beyond the schema, so baseline 3 applies.

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

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

Clearly states 'Cancel a subscription by id' with a specific verb and resource. Distinguishes from its sibling 'subscribe'.

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 ownership enforcement and that rows are deactivated not deleted, providing context for when to use. Could explicitly mention alternatives 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 discloses critical non-obvious behaviors: could_not_verify indicates the check didn't happen and must not be treated as evidence; unsupported means no source coverage. It also reveals the dual-path architecture (structured SEC EDGAR vs grounded pipeline) and the presence of citations and error details. The annotations already cover read-only/idempotent safety, so this added context goes well beyond structured hints.

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

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

The description is long but efficient, organized with trigger phrases, purpose, routing, output semantics, and a caller warning. Every sentence adds value, and the structure front-loads the core purpose. It is dense but not bloated, appropriate for a tool with no output schema.

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 covers return values: six verdicts, actual value with citation, reasoning, and verification_error details. It also explains the two pipeline paths and the meaning of could_not_verify vs unsupported. This is sufficiently complete 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?

Schema coverage is 100% with detailed descriptions for both parameters (`claim` with examples, `tolerance_pct` with range and default). The description itself doesn't add parameter-specific meaning beyond mentioning 'exact percent-delta math', so the schema carries the burden. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: natural-language claim verification against authoritative sources. It lists explicit trigger phrases ('fact check', 'verify the claim that…') and distinguishes itself by focusing on checking the truth of a user's statement. It also notes it replaces 4–6 sequential calls, further clarifying its specific role among 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 direct usage guidance: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains the routing logic for company-financial claims vs other claims, providing clear context for when the tool applies. However, it doesn't explicitly name alternative tools to avoid or exclusions for open-ended research, which would push 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.