Schrodingers Boolean

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

Annotations already mark the tool as readOnly, openWorld, idempotent, and nondestructive. The description adds behavioral context: probing multiple models, default free model, and the need for a key to enable Anthropic. 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?

Two sentences that efficiently convey purpose, usage, return value, and key behavior. No wasted words; information is front-loaded and 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?

The description explains the return structure (per-model score, confidence, signals, raw_response, combined view) despite no output schema. It addresses the tool's complexity with optional models and API key, though it could be slightly more detailed on error conditions.

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 adequate descriptions for all four parameters. The description adds marginal value by explaining the default model for 'models' and the role of 'context' for disambiguation, but does not exceed the schema's own 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?

Description clearly states it probes LLMs about an entity and scores visibility (0-100) per model. It specifies the default model and distinguishes from sibling tools like scan_competitor_ai_presence by focusing on general brand awareness rather than competitive analysis.

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

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

Explicitly mentions use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and clarifies that Anthropic probing requires a BYO key. However, it does not explicitly contrast with siblings like compare_entities or scan_competitor_ai_presence, which could lead to ambiguity.

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

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

Annotations already mark the tool as read-only, idempotent, open-world, and non-destructive. The description adds meaningful behavioral context beyond this: it is a routing tool across 5,798 tools and 1,517 sources, it auto-fills arguments, and it returns stable citation URIs. There is no contradiction with 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 front-loaded with the most important routing directive, then gives triggers, examples, and exclusions in a logical order. Every sentence earns its place, and the length is justified for a broad factual-query router.

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 a single required natural-language parameter, no output schema, and rich annotations, the description provides sufficient context: it explains scope, exclusions, alternatives, and the nature of the returned structured answer with citation URIs. An agent can confidently invoke it without additional lookups.

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

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

The input schema already documents the question parameter and its aliases with 100% coverage. The description adds value by showing what kinds of natural-language values are appropriate, with examples like 'current US unemployment rate', 'Apple's latest 10-K', and 'active clinical trials for GLP-1', which helps an agent compose valid queries.

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 exactly what the tool does: it routes a natural-language question to one of many verified-source tools, fills arguments, and returns structured answers with pipeworx:// citation URIs. It also distinguishes itself from web search and several sibling research tools by naming alternatives like deep_research, bet_research, compare_entities, and entity_profile.

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

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

The description provides explicit when-to-use signals such as 'what is', 'look up', 'find', 'get the latest', and 'current', plus concrete examples. It also gives explicit when-not-to-use guidance for non-factual, creative, code, planning, math, logic, and private/access-controlled queries, and names alternatives for those cases.

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

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive, so the bar for added value is high. The description goes well beyond: the tool's behavior is state-dependent ('candidate routing improvements enabled live whenever one is under test'), the current inactive state is disclosed with an evidence-based retirement date, current parity with ask_pipeworx is stated, and the no-fallback property is clarified ('Falls back to nothing — this IS a full working router, just the experimental edge'). This is exactly the dynamic behavioral context an agent cannot infer from structured fields.

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

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

Identity and scope are front-loaded in the first sentence, and each subsequent sentence carries distinct information: candidate state, usage direction, comparison behavior, and fallback clarification. At roughly 90 words it is slightly verbose, and the specific retirement date is more precision than strictly necessary, but there is no redundant or filler content.

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 high-complexity router (5,798 tools) with no output schema, the description covers the essential ground: what the tool is, its beta status, its live-candidate behavior, current state, usage direction, and fallback behavior. The response shape is handled by reference ('same response shape' as ask_pipeworx); describing the response format directly would be the only notable omission.

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 the question parameter already documents all five aliases (query, q, prompt, text, input). The description only confirms 'same arguments' as ask_pipeworx, which adds cross-tool consistency but no new semantic meaning about any parameter, so the 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?

The description frames the tool as 'Beta version of ask_pipeworx: identical universal router (same 5,798 tools, same arguments, same response shape)', which identifies the resource and its scope clearly and distinguishes it from the stable sibling ask_pipeworx. The core verb, routing a natural-language question to one of many tools, is implied by 'universal router' and the comparison-to-stable-router language rather than stated with an explicit action phrase, which keeps it from a 5.

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 directs when to use it: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also contrasts with the stable router ('results are compared against the stable router to decide what merges') and gives essential current-state context: no candidate is active as of 2026-07-26, so it currently matches ask_pipeworx exactly. It stops short of 5 because it never states exclusions, such as preferring ask_pipeworx for stable/production behavior or ask_pipeworx_grounded for grounded responses.

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 readOnlyHint/openWorldHint/idempotentHint annotations, the description reveals refusal semantics and all refusal_reason enum values, states that evidence is a verbatim quote, and discloses the extra LLM-call cost. It also explicitly says it will refuse rather than invent when the data doesn't directly answer.

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 dense sentences cover purpose, output shape, refusal cases, use cases, cost, and alternative routing with no filler. The main purpose is front-loaded and the trade-off appears at the end where it is most useful for decision-making.

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

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

With no output schema, the description compensates by specifying the success response fields and refusal payloads. Together with the annotation safety profile and the parameter-rich input schema, an agent has everything needed to select and 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 description coverage is 100%, so the schema already fully documents the 'question' parameter and its six aliases. The description adds no parameter-specific detail, but it doesn't need to; the baseline 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 opens with a specific, high-signal characterization: 'Hallucination-resistant answer mode for high-stakes reads' and contrasts with ask_pipeworx by describing extraction 'using ONLY what the tool result contains.' It clearly states the tool answers with evidence and explicit refusal, which distinguishes it from siblings like ask_pipeworx and ask_pipeworx_beta.

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 gives explicit when-to-use guidance ('when an answer will be quoted, cited, or acted on ... must not invent facts'), names ask_pipeworx as the preferred alternative for casual lookups, and explains the trade-off ('Costs one extra LLM call'). This is exactly the decision-routing information an agent needs.

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

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

Annotations indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds extensive behavioral details: resolution steps, fan-out examples, response shapes, safety mechanisms (low-confidence resolution, closed markets, wide spreads), and resolution-rule risk. 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 comprehensive but verbose (~600 words). While well-organized with sections, it could be more concise for quick parsing. Every sentence adds value, but length reduces conciseness.

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

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

Despite no output schema, the description thoroughly covers response shapes, edge cases (low-confidence matches, closed markets, wide spreads), resolver contract details, and resolution-rule risk. It is complete for an AI agent to understand and use 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%, baseline 3. The description adds meaning to 'market' (slug, URL, or question text), explains 'depth' options (quick/thorough), and specifies 'include_raw' default and use cases. This adds value beyond the schema definitions.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies inputs (slug, URL, question text) and outputs (evidence packet + market vs model comparison), distinguishing it from sibling tools that focus on other aspects like arbitrage or edge tracking.

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

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

The description explicitly advises when to use: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' While it does not list when not to use or name alternatives, the provided usage scenarios are clear and practical.

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, idempotentHint=true, and destructiveHint=false. The description adds key behavioral details: for company type it pulls financial data from SEC EDGAR/XBRL with off-calendar year handling, for drug type it pulls FAERS and FDA data. It also mentions results are sorted by primary metric and returns citation URIs. No contradiction with annotations.

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

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

The description is a single paragraph but effectively structured: starting with user query examples, then stating purpose, then detailing type-specific behavior. It's slightly long but every sentence adds value. Could be slightly more concise but still very good.

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, financial and drug data, sorting, citation URIs), the description covers essential aspects. It mentions return format (paired data + URIs) but doesn't detail exact output structure. However, annotations and schema compensate. A brief note on rate limits or pagination would improve completeness.

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

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

Schema coverage is 100% but the description adds significant value: it provides example inputs (e.g., 'AAPL','MSFT'), explains what each type does, and clarifies constraints (2-5 values). This goes well beyond the schema's brief descriptions.

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

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

The description starts with explicit user queries ('Compare X and Y', 'X vs Y', 'which is bigger') and states the tool provides side-by-side comparison of 2-5 companies or drugs. It clearly distinguishes itself from sequential lookups by saying 'ALWAYS PREFER over sequential single-pack lookups'. The verb 'compare' and resource 'entities' are 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 to prefer this tool over sequential lookups when comparing entities. It also explains what each type returns (company vs drug). It doesn't explicitly state when not to use it, but the context is clear.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses account requirements, the paid tier, parallel internal routing, the findings-packet fields, the gaps[] no-hallucination behavior, contradictions[], fetchable citation semantics, semantic excerpting, and expected latency. This far exceeds what annotations alone provide, and it does not contradict them.

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

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

The description is information-dense and front-loaded with the account prerequisite, but it is a long single paragraph that repeats the ask_pipeworx fallback in two places. Every sentence adds valuable behavior or context, but clearer separation of preconditions, behavior, alternatives, and performance would improve readability.

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

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

With no output schema, the description fully compensates by describing the return packet fields, gap and contradiction handling, citation behavior, and latency expectations. Combined with the rich annotations and complete parameter schema, nothing needed for safe and correct invocation is 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?

The schema already covers 100% of the parameter descriptions, so the baseline is 3. The description adds useful extra context: thorough depth requires a paid plan, expected response times differ by mode, and question shape (broad multi-part vs single lookup) affects tool selection. That extra context justifies moving above baseline.

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

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

The description clearly states that this tool performs grounded multi-source research across Pipeworx's 1,517 structured data sources, and it explicitly distinguishes the tool from open-web search. It also differentiates it from a sibling by directing single-lookup questions to ask_pipeworx instead.

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

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

It provides explicit when-to-use guidance ('best for broad/multi-part questions over structured data'), concrete examples, and names ask_pipeworx as the alternative both for single lookups and for users who are not signed in. The depth parameter behavior is also described per tier, helping the agent choose the right mode.

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 and idempotent hints. The description adds valuable behavioral details: returns top-N tools with names, descriptions, full schemas, and curated examples, ready to call directly without a second lookup.

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

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

The description is well-structured, front-loading the core purpose and usage advice, then listing domains and return behavior. Every sentence adds value without redundancy.

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

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

Given the tool's purpose (discovery), the description covers all necessary aspects: what it does, when to use it, what it returns, and how to call it. No output schema is needed because the return format is described.

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, the description adds meaning by listing aliases for the query parameter (task, q, description, search) and providing example queries. This helps agents understand how to use the parameter flexibly.

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: to find/browse/discover tools by describing a task or data. It distinguishes itself from sibling tools by being a meta-search tool among many domain-specific tools.

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

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

The description explicitly advises calling this tool FIRST when many tools are available, providing clear context. It lists example domains but does not explicitly state when not to use it, though the guidance is strong.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses concrete behaviors: fan-out across SEC, XBRL, USPTO, federal contracts, FDA, DOL, news, GLEIF; soft-failure for the PatentsView sunset; 'an empty section is a real "no data", not a bug'; and private-company resolution returning resolved:false. It also explains sources_failed and what happens with name inputs.

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 almost every clause carries information: examples are front-loaded, the ALWAYS PREFER rule appears early, and the return sections are itemized. It loses a point for mild repetition of schema content ('company'/'ticker' interchangeability) and a minor future note ('person/place coming soon') that isn't needed for invocation.

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

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

With no output schema, the description carries the full burden of explaining what is returned, and it does so thoroughly: cik/company_name, recent_filings with URI scheme, latest 10-K fundamentals, patents with sunset soft-fail, federal_contracts, fda_products semantics, hiring, news fallback, LEI, and sources_used/sources_failed. It also covers no-data expectations and private-company behavior, leaving no decision-critical gap.

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

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

The input schema already covers both parameters at 100%, so the baseline is 3, but the description adds useful resolution semantics: a value can be a ticker, zero-padded CIK, or company name, name resolution now happens via SEC EDGAR, and a private company returns resolved:false with a notes line. This gives the agent expectations for how different value shapes will behave.

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

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

The description leads with concrete user-phrase examples then states the core behavior: 'full cross-source profile of a US public company in ONE parallel call.' It names the resource and data domains clearly, and explicitly contrasts itself with 'chaining single-pack SEC/XBRL/news lookups,' so an agent can tell it apart from narrower lookups.

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

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

It gives an explicit trigger and preference rule: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' and clarifies that a private company yields resolved:false rather than a failure. However, it does not explicitly draw boundaries against sibling tools such as compare_entities or deep_research, so the agent is left to infer those distinctions.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. Description adds minimal extra behavioral context ('clear sensitive data') but no further details on permissions or side effects. Since annotations cover the safety profile, a baseline score of 3 is appropriate.

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

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

Three concise sentences: one for purpose, one for usage context, one for related tools. No wasted words; all content 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, clear annotations, and no output schema, the description fully covers purpose, use cases, 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 description 'Memory key to delete'. Description does not add extra meaning beyond the schema, so baseline score of 3 applies.

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

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

Explicitly states 'Delete a previously stored memory by key' with a specific verb, resource, and method. Clearly distinguishes from sibling tools 'remember' (store) and 'recall' (retrieve).

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 contexts for use: stale context, completed tasks, clearing sensitive data. Mentions pairing with related tools. Does not explicitly state when not to use, but the positive guidance is strong.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds process details (fetching, extracting, emitting markdown) without contradicting annotations. It could mention error handling or limitations, but the transparency is adequate.

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

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

The description is concise, front-loaded with the main purpose, and structured with a clear process and use case list. No unnecessary words or redundancy.

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

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

Given two simple parameters and no output schema, the description explains the input (URL, optional max_links) and output (markdown text blob) completely. The use cases provide full context for when to use 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 describes both parameters fully with examples and defaults. The description adds no extra meaning beyond the schema, so a baseline score of 3 is appropriate given 100% coverage.

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

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

The description clearly states the tool generates an llms.txt file for any URL, specifying the process (fetches, extracts, emits) and distinguishing it from siblings like scan_competitor_ai_presence by focusing on general URL indexing for AI crawlers.

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 use cases (client indexing, personal projects, competitor auditing), providing clear context. It does not explicitly mention when not to use or name alternatives, but the use cases are 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?

Annotations already provide readOnlyHint, idempotentHint, destructiveHint. The description adds value by listing specific return fields, consistent with annotations. 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: two sentences with no unnecessary words. First sentence states purpose and output, second gives usage guidance. Highly efficient.

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

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

Given the tool's simplicity, annotations cover safety, and the description covers purpose, return fields, and usage. No output schema needed. Slightly lacking in potential details like pagination but complete for a list tool.

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

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

Schema coverage is 100% with one boolean parameter. The description doesn't add further meaning beyond the schema, so baseline score of 3 is appropriate.

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

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

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

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

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

The description provides explicit guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' It doesn't state when not to use, but the context is clear enough.

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

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

The description discloses several non-obvious behaviors: filing without an account returns a claim_token that can be used later to check resolution status, the tool is rate-limited to 5 per identifier per day, it is free and doesn't count against tool-call quota, and the team reads digests daily. These go well beyond the annotations (which only mark safety hints) and help the agent understand side effects and expectations.

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

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

The description is dense but every sentence serves a purpose: purpose, use cases, scope exclusion, content guidelines, claim_token mechanics, rate limits, and free/quota status. It is front-loaded with the primary purpose and then systematically covers all critical usage details. No wasted words.

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

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

Given the tool's complexity (dual-mode behavior, scope restrictions, rate limits, and no output schema), the description covers all essential context: how to submit, how to follow up, what returns, what not to include, and operational limits. It is fully self-contained and leaves no major 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 description coverage is 100%, so the baseline is 3. The description adds value by explaining the claim_token workflow (submit vs. follow-up mode) and the requirement to describe issues in terms of Pipeworx tools/packs, which clarifies the 'message' parameter's content beyond the schema's generic 'Be specific.'

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 clear statement: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It identifies the specific resource (Pipeworx team) and the action (submit feedback), and distinguishes this tool from all siblings by emphasizing it is for reporting issues about Pipeworx tools only, not for direct research or data 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 provides explicit when-to-use guidance: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives a clear exclusion: do not report tools from other MCP servers, and instructs to describe issues in terms of Pipeworx tools/packs rather than pasting user prompts. This is rich, actionable 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, openWorldHint, idempotentHint, and not destructive. Description adds valuable context: data is aggregated from CF analytics-engine, no PII, cached 5min-1h. No contradictions.

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

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

Concise at 5 sentences, front-loaded with main capability, structured bullet-like for uses. Every sentence provides unique value.

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

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

For a simple read-only tool with one optional parameter and no output schema, the description covers return structure, caching, privacy, and usage context. Completely adequate.

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

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

Schema has 100% coverage with enum and description. Description adds meaning beyond schema: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This helps parameter selection.

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

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

Clearly states it returns top tools, packs, and call volume over configurable windows. Distinguishes from sibling tools like 'discover_tools' by focusing on trending/popularity signals.

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

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

Lists three explicit use cases and explains window tradeoffs. Does not include negative guidance (when not to use), but use cases are clear enough to guide selection.

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

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

Annotations indicate readOnlyHint=true and idempotentHint=true, which match the description's non-destructive nature. The description adds significant behavioral context: semantic anchor (Jaccard similarity threshold), partition filter (placeholder detection), fill check (live CLOB depth analysis), and explicit 'do not trade' conditions.

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

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

The description is verbose but all sentences contribute useful information about modes, filtering, and response structure. It is front-loaded with the main purpose and then systematically details each mode. The length is justified by the tool's complexity.

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

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

Despite having no output schema, the description thoroughly explains the response structure: opportunities[] with fields (gap_pp, suggested_trade, reasoning), partition_check details, and fill_check logic. It also mentions custom sizing with polymarket_fill_risk, covering all contextual needs for effective tool use.

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

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

Schema coverage is 100%, so baseline is 3. The description adds substantial value beyond the schema by explaining event mode slugs/URLs, topic mode seed questions, and providing examples. This extra context justifies a score above baseline.

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

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

Description clearly states 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks', which is a specific verb+resource combination. It distinguishes from siblings like polymarket_edges and polymarket_fill_risk by detailing its unique method and modes.

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

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

Explicitly explains when to call with no args (trending_scan), event mode (recommended for a specific market), and topic mode (cross-event scanning). Provides guidance on alternatives (e.g., polymarket_fill_risk for custom sizing) and includes examples.

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

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

Description goes far beyond annotations by detailing the three model families, edge calculations, caching behavior (1h KV-level), diagnostics for empty segments, and tradeable-edge knobs. All behavioral traits are disclosed transparently with no contradictions to 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 clear sectioning (key-value pairs, knobs, response structure). It front-loads the purpose and use case. Some technical details (e.g., exact alpha values) could be shortened, but the complexity warrants 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?

Given 9 params, no output schema, and no nested objects, the description comprehensively covers the response structure (by_segment, diagnostics, fed candidates), explains why segments may be empty, and describes caching. It leaves no significant gaps for an agent to use the tool effectively.

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

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

All 9 parameters are described in the schema, but the description adds significant semantic value by explaining the rationale behind defaults (e.g., slippage_pp, min_liquidity) and how parameters like min_partition_leg_kelly apply. This enriches the schema's descriptions without repeating them.

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

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

Description clearly states the verb ('Scan'), resource ('Polymarket markets'), and outcome ('opportunities where Pipeworx data disagrees with market price'). It distinguishes from sibling tools like polymarket_arbitrage by focusing on Pipeworx disagreement and from polymarket_edge_tracker by being a daily scan tool. The purpose is specific and unambiguous.

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

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

Description explicitly states the use case: 'what should I bet on today' and 'agents discover opportunities without paging hundreds of markets.' It provides context for when to use this tool vs alternatives, though it does not explicitly state when NOT to use it. Sibling names give implicit differentiation.

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

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

Annotations indicate read-only, idempotent, non-destructive. Description details data source (daily snapshots, cache-miss triggers), limits (60-day TTL, snapshot start), and computation specifics (daily closes, not intraday). 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 detailed but well-organized with bullet-style output sections (tracked[], expired[], snapshot_dates[]). It front-loads the key question. Slightly verbose but every sentence adds value.

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

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

Given no output schema, the description fully explains the response structure and computed fields (trend, decay, first_seen, lifespan). It covers data limitations and interpretation details (signed values, negative meaning). 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 describes both parameters with 100% coverage. Description adds context: days default (14) and max (30), window options (24hr, 1wk, 1mo) and default (1wk). Slight mismatch in max (schema says clamp 2-30, description says max 30) but not misleading.

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 edge persistence and decay telemetry from daily snapshots, answering specific questions about edge duration and trend. It distinguishes from the sibling tool 'polymarket_edges' by adding time-series analysis.

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 the context of when to use it (comparing fresh vs. old edges) and implies an alternative (polymarket_edges for current state). It lacks explicit 'when not to use' or direct sibling comparisons, but the intent is clear.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, etc. Description adds behavioral context beyond annotations: it walks the order book ladder, returns specific fields like slippage_pp and forced_directional_risk, and warns about thin books. No contradiction with annotations.

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

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

The description is long but well-structured with sections (REQUIRES, SINGLE-MARKET, BASKET, USE THIS). Front-loaded with key purpose. Every sentence adds value given the tool's complexity. Could be slightly tighter but justified.

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

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

Despite no output schema, the description thoroughly covers return values (top_of_book, vwap_fill_price, slippage_pp, etc.) and risks. Addresses both modes, edge cases (thin_legs, forced_directional_risk), and usage context. Complete for a complex tool.

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

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

Schema description coverage is 100%. The description adds significant meaning beyond schema: e.g., 'size_usd interpreted as settlement notional S (shares per leg)' for basket mode, and 'max spend on buys, target proceeds on sells.' Clarifies parameter behavior across modes.

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

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

The description explicitly states it checks 'realizable-vs-theoretical edge against live CLOB order-book depth.' It clearly distinguishes between single-market and basket modes, with specific verbs like 'walks the ladder' and 'returns.' It differentiates from siblings 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 requires one of `market` or `event`. Provides clear when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' Also explains risks of partial fills converting arb to unhedged position.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior, so the bar for additional value is high — and the description clears it. It discloses that spreads are gross not net of Kalshi fees, that compatibility codes can be non-empty even on returned pairs, that 'unknown' legs are never paired, and that null temporal_alignment means 'could not compute' rather than 'aligned.' There is no contradiction with 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 long, but nearly every sentence carries unique safety or matching information that the schema and annotations do not provide. It is front-loaded with the core definition and modes before diving into code-level caveats; a bulleted layout might improve scannability, but the density is justified for a tool with this many edge cases.

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

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

There is no output schema, so the description must explain return values — and it does, covering venue leg prices, top_spreads_pp, compatibility_codes, temporal_alignment semantics, fees_note, skipped-unclassified legs, and low_confidence_pairs. It also tells the agent when to trust the result and when to manually check strike dates, which is exactly what a caller needs for correct interpretation.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful semantics beyond the schema: it enumerates the topic shortcuts, gives realistic examples for kalshi_event_ticker and polymarket_event_slug, and explains that explicit parameters override the topic-mapped side. That interaction behavior is not derivable from the schema alone.

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

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

The opening sentence states a precise deliverable — a cross-venue spread between Kalshi and Polymarket for the same resolving question — which distinguishes it from Polymarket-only siblings like polymarket_edges. It further clarifies the two modes (topic shortcuts vs explicit ticker/slug) and the output type, leaving no ambiguity about what the tool computes.

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 clear routing guidance between the two modes, explains when explicit parameters override topic-mapped tokens, and warns that most pre-mapped topics return compatibility_warning so pre-mapped should not be treated as tradeable. It does not explicitly contrast this tool with sibling alternatives like polymarket_arbitrage, so it stops short of full exclusion guidance.

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

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

Annotations already provide readOnlyHint, idempotentHint, destructiveHint false. The description adds context about scoping (to identifier) and the listing behavior when key omitted, which goes beyond annotations.

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

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

Two sentences with no filler. Front-loaded with primary action, followed by example use cases and relationships. Every sentence adds value.

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

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

Given the low complexity (one optional parameter, no output schema), the description fully explains the tool's behavior, scoping, and how it relates to sibling tools (remember, forget). 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 covers both usage cases with 100% coverage. Description reinforces and adds context: explains that omitting the key lists all saved keys, and that retrieval returns a specific value. This adds meaning beyond schema.

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

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

Clearly states the verb ('retrieve') and resource ('value previously saved via remember'), and distinguishes from siblings by mentioning pairing with remember and forget. Also explains the dual behavior when key is omitted.

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 describes when to use ('look up context stored earlier') and how to use (omit key to list all). Also mentions scoping and pairing. Does not explicitly state when not to use, but the context is clear enough.

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

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

Beyond annotations (readOnly, idempotent, non-destructive), the description adds behavioral details: each alert carries source, citation_uri, and raw payload; setting mark_read=true flags events as read for subsequent calls. This enriches 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 four sentences, each purposeful. It front-loads the core purpose, then layers details in a logical order. No redundant or extraneous content.

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 hints at return structure (source, citation_uri, payload). It covers all parameters implicitly or explicitly, and mentions polling suitability. Adequately complete for a read-only, non-destructive 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?

With 100% schema coverage baseline is 3. The description adds value by providing examples ('e.g. "sec_8k"') and clarifying the effect of mark_read ('so the next call only shows newer ones'), going beyond the schema descriptions.

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

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

The description clearly states the tool's purpose: 'Pull fired events from your subscription feed.' It specifies the resource (recent alerts from a persisted feed) and differentiates it from sibling tools like 'list_subscriptions' and 'subscribe' which manage subscriptions, not alerts.

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

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

The description provides context on when to use: 'Polls work fine' and offers an alternative (GET endpoint) for scripts/dashboards. It does not explicitly state when not to use this tool vs alternatives, but 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?

Annotations already indicate read-only, idempotent, and non-destructive. The description adds critical behavioral details: parallel call to three sources, fallback logic, return structure (changes[], total_changes, citation URIs), and parameter format examples. 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 front-loaded with example queries and efficiently covers sources, parameters, and sibling differentiation. Though a bit lengthy, every sentence adds value. Minor redundancy could be trimmed.

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

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

Given 3 params with 100% schema coverage, no output schema, and comprehensive annotations, the description fully explains the tool's behavior: sources, fallback, return structure, and parameter formats. It leaves no ambiguity for an AI agent to misuse 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%, so parameters are already documented. The description enhances this by providing practical usage examples for 'since' (ISO or relative, suggests '30d'/'1m'), clarifying 'value' accepts ticker or CIK, and noting 'type' only supports '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 uses specific verbs ('fans out to SEC EDGAR, GDELT→GNews, USPTO') and resources ('change feed for a company'), and clearly distinguishes from sibling tool 'entity_profile' by stating its alternative use case.

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

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

The description provides explicit query examples (e.g., 'What's new with X', 'latest on Y') and tells when to use 'entity_profile' instead. It also explains fallback behavior (GDELT→GNews) and limitations (USPTO soft-fail).

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

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

Description adds details about scope, persistence across sessions, and 24-hour retention for anonymous users, complementing annotations that indicate idempotency and non-destructiveness.

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

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

Single paragraph front-loads purpose, then usage, then behavioral details; slightly verbose but every sentence is useful.

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?

All necessary context provided for a simple store tool: purpose, usage, parameter hints, persistence behavior, and pairing with related tools. No output schema needed.

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

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

Schema coverage is 100% and parameters are self-explanatory; description provides examples but no additional semantics beyond schema.

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

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

Description clearly states 'Save data the agent will need to reuse later' with specific verb and resource, and distinguishes from sibling tools recall 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?

Explicitly describes when to use (discover worth carrying forward) and alternatives (pair with recall/forget).

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, safe behavior, and the description substantially supplements this with valuable behavioral detail: graceful degradation when GLEIF/OpenFIGI is unavailable, returning figi_candidates when no single instrument matches, asserting nothing on ambiguous matches, and explicitly listing unresolved identifiers rather than omitting 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 lengthy and densely packed, but it is front-loaded with purpose and each addition provides substantive operational detail. It is not elegantly structured, and the wall-of-text style could hamper quick scanning, but there is minimal wasted prose.

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

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

For a complex tool with no output schema, the description covers input semantics, supported entity types, resolution behavior, ambiguous-match handling, source labeling, unresolved results, and degradation cases. An agent has enough to select and invoke the tool correctly without needing an external schema.

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

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

Schema coverage is 100%, so the baseline is 3, but the description enriches both parameters beyond the schema: it details supported input formats (ticker, CIK, ISIN, name) and warns against passing full noun phrases for bonds, explaining that trailing security-class words will fail the FIGI lookup. This is meaningful added semantic guidance.

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, reinforcing this with concrete query patterns and supported types. It differentiates the tool from general lookup tools by emphasizing that it produces the identifiers other tools require as input.

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?

Usage guidance is explicit: 'Use FIRST whenever you have a name but need an ID' and examples of triggering queries are provided. It does not explicitly name sibling alternatives or state when not to use this tool, so it stops short of full when/when-not coverage.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds behavioral details: it probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, and signal density. No contradiction with annotations.

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

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

The description is three sentences with no wasted words. It front-loads the purpose, then details mechanism and output. Every sentence adds value.

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

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

Despite lacking an output schema, the description adequately describes the output format (ranked list with score, confidence, signal density) and the sub-tool used. For a tool with 4 parameters and moderate complexity, it is sufficiently 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?

Input schema has 100% coverage, so baseline is 3. The description adds semantic value beyond schema: it explains that the first entity in the array is treated as the 'subject' for narrative, and it clarifies the default model and requirement for 'anthropic' model.

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 ('Compare', 'probes', 'ranks') and names the resource ('AI visibility'). It clearly distinguishes from sibling tool 'ai_visibility_check' by indicating multiple entities and side-by-side comparison.

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

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

The description provides a concrete use case ('competitive AI-marketing audits') and implies when to use (comparing multiple entities) versus using 'ai_visibility_check' for a single entity. It does not explicitly state when not to use but gives sufficient context.

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

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

Annotations already provide readOnlyHint, idempotentHint, etc. Description adds critical details beyond: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed lists timeouts. No contradictions with annotations.

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

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

The description is a dense single paragraph but contains no filler. Every sentence adds value, though it could benefit from bullet points for readability. However, it remains clear and efficient.

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

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

For a composite tool with 2 parameters and no output schema, the description fully explains inputs, behavior (about alternatives and fallbacks), and output structure (summary block, per-advisory detail, links, alternatives). Partial failure handling is clearly described.

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% (both parameters described). Description adds value by explaining that 'version' defaults to latest and that scoped packages are accepted, providing extra context beyond the schema.

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

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

The description uses specific verbs ('composite check', 'fans out') and clearly states the resource (npm package) and the question the tool answers. It distinguishes from sibling tools by explicitly limiting ecosystem to NPM v1 and mentioning fallback for others.

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: 'whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. Also clearly excludes non-NPM ecosystems, directing to alternative tool deps.dev:version.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so the description does not need to restate safety. The description adds context about the quantum superposition response and cat mode, and the 'reopen' parameter description warns it will fail, which is a behavioral hint 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 and front-loaded: two sentences that cover the core purpose, special modes, and return content. Every sentence adds value without redundancy.

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

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

Given that an output schema exists and annotations are rich, the description is adequately complete. It explains the core functionality and special features. It could be more detailed about when to use 'observe' or 'interpret' parameters, but these are covered in the schema.

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

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

The input schema has 100% description coverage for all parameters, so the description does not need to add much. It mentions 'cat mode' but does not elaborate on parameter syntax or semantics beyond what the schema provides. 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 function: ask a yes/no question and receive a quantum superposition answer. It also highlights special features (cat mode, wave function interpretation). The tool's unique whimsical nature distinguishes it from sibling tools, which are more conventional research and prediction 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 implies usage for yes/no questions, but it does not provide explicit guidance on when to use this tool versus alternatives. There is no mention of when not to use it or prerequisites, though the sibling list lacks similar tools, reducing the need for differentiation.

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 technical details beyond annotations: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char limit with truncation flag, and that passages include character offsets for verification. There is no contradiction with annotations.

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

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

The description is front-loaded with the main purpose, then usage guidance, then technical details. Each sentence serves a purpose, though it could be slightly more concise. 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?

Even without an output schema, the description explains return format: top-N passages with character offsets and similarity scores. It also covers input constraints (200K chars), use cases, and behavior on truncation. This is complete for an agent.

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

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

Schema description coverage is 100%, so the description adds limited value. It restates the max char limit for 'text' and clarifies that 'query' should be a natural-language query. While helpful, this aligns with the baseline score for high coverage.

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

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

The description clearly states it performs semantic search inside a fetched record, specifying it's for large texts that can't fit in the prompt. It distinguishes from sibling tools like ask_pipeworx_grounded by noting they can be paired together.

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 the record is too big to cram into the prompt') and provides an alternative workflow: fetch with the gateway, then use ask_pipeworx_grounded over the passages. This clearly guides the agent on when to invoke this tool vs. alternatives.

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

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

Discloses that subscription persists, requires OAuth, and returns an id. Also notes webhook secret is returned once. Annotations already indicate idempotent and open world; description adds concrete behavioral details without contradiction.

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

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

Front-loaded with purpose and key requirements. While lengthy, every sentence provides useful context. Could be slightly more concise but structure is logical.

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

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

Given complexity (nested params, multiple types, no output schema), description covers authentication, type-specific params, delivery options, and limitations. Missing return format beyond 'id' but acceptable.

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

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

Schema coverage is 100%, but description adds value by providing concrete examples (e.g., items:['5.02']) and clarifying constraints (e.g., sponsor or condition required for clinical_trial). Exceeds baseline of 3.

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

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

Description clearly states the verb ('Create') and resource ('proactive monitoring subscription to a live-data event stream'), and distinguishes from sibling tools like list_subscriptions and unsubscribe.

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

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

Explicitly states requirement of Pipeworx OAuth account, and mentions limitations (e.g., SMS 10/day cap, phone verification). Implicitly clarifies when not to use (anonymous/BYO cannot persist). Strong guidance but no direct 'when not to use' for each alternative.

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, etc. Description adds that output includes 'exact tool + argument shape' from live catalog, and that tool is idempotent. 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?

Description is focused and front-loaded with purpose and synonyms. Slightly long but retains value in every sentence; well-structured with dashes for grouping.

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

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

For a tool with 1 optional parameter and no output schema, description fully explains output (category-bucketed example questions with tool+argument shape) and usage context. 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 covers the single optional topic parameter with description. Description adds value by listing example topics and explaining behavior of omitting vs. providing topic. Baseline 3 from 100% schema coverage, plus extra explanation.

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

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

Description clearly states the tool returns category-bucketed example questions with exact tool + argument shapes. Distinguishes itself as the onboarding entry point, contrasting with sibling tools like ask_pipeworx, entity_profile, etc.

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

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

Explicitly instructs to use this tool first when the agent doesn't know what Pipeworx can do. Provides guidance on arguments (omit for full spread, pass topic to focus) and mentions meta-tools to learn about.

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

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

Discloses that the row is deactivated (not deleted) and historical events remain via recent_alerts. Consistent with idempotentHint and adds 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?

Two front-loaded sentences convey purpose, constraint, and side-effect without 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?

No output schema, but description fully covers behavior and side effects for a simple tool. Enough 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 covers 100% of parameters. Description clarifies that 'id' is the subscription id returned by subscribe, adding 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?

Clear verb ('Cancel') and resource ('subscription') with specific identifier ('by id'). Distinct from sibling tools like subscribe and list_subscriptions.

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

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

Explicit ownership constraint ('you can only cancel your own subscriptions') guides proper usage, though no direct comparison to 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 goes well beyond the annotations by explaining the dual-path verification (SEC EDGAR vs. grounded pipeline), the meaning of all verdicts, and specifically clarifying that 'could_not_verify' is not evidence against a claim. It also mentions the replacement of 4-6 calls, which reveals the tool's aggregate behavior. This is exceptional behavioral disclosure.

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-organized, starting with trigger examples and then covering usage, paths, verdicts, and important caveats. Each sentence contributes unique value, though some repetition (e.g., listing example phrasings) could be trimmed without losing meaning.

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

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

Given the tool's complexity (two paths, multiple verdicts, error handling), the description fully covers the need-to-know aspects: return values, status semantics, and what 'could_not_verify' versus 'unsupported' mean. No output schema exists, so the description's thorough explanation of outputs and edge cases is critical and well-executed.

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

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

The input schema already provides 100% coverage with detailed descriptions for both parameters, including tolerance_pct's override and default behavior. The tool description adds only a brief mention of 'percent-delta math' and does not offer significant new parameter-level insight, so a baseline score of 3 is appropriate.

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

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

The description explicitly states the tool's purpose: natural-language claim verification against authoritative sources. It lists trigger phrases and clearly distinguishes this from sibling tools by explaining it replaces multiple sequential calls. The verb 'verify' and resource 'claims' make 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 provides clear when-to-use guidance ('Use whenever the agent needs to check whether something a user said is factually correct') and elaborates on the routing logic for financial vs. non-financial claims. It does not explicitly state when not to use an alternative, but the context is strong enough to infer appropriate usage.

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