Imei

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

Annotations (readOnlyHint, idempotentHint, destructiveHint=false) are consistent. The description adds value by detailing return structure (per-model {score, confidence, signals, raw_response} + combined view) and the cost/authentication nuance for Anthropic. No annotation 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?

Two sentences with no filler. The first sentence defines purpose and output, the second adds usage nuance. All information is essential 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?

For a tool with 4 parameters and no output schema, the description covers all necessary aspects: input semantics, defaults, return format, and use cases. No gaps identified.

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

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

Schema coverage is 100%, so baseline is 3. The description enhances each parameter: entity with concrete examples, models with default and supported values, _apiKey with purpose and note on direct payment, context with disambiguation example. This exceeds the baseline.

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

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

The description clearly states the tool's verb (probe) and resource (LLMs for entity visibility), with specificity on scoring (0-100) and use cases (AI-marketing audits, pre-launch brand checks). It distinguishes itself from sibling tools like ask_pipeworx and deep_research by focusing on visibility measurement rather than general Q&A.

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

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

The description provides explicit use cases and explains how to invoke additional models (with _apiKey for Anthropic). It does not explicitly state when not to use or compare to alternatives, but the context is clear enough for appropriate 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 already establish read-only, idempotent, non-destructive behavior. The description adds useful behavioral context: it routes across 5,743 tools, fills arguments automatically, and returns stable citation URIs. This goes beyond the annotations without contradicting them, although it does not detail failure modes or what happens when no source matches.

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 informative and front-loaded with the most important guidance, but it contains redundancy: 'START HERE for most questions' appears twice in slightly different forms. Some sentences could be tightened without losing meaning, though the structure is otherwise logical.

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

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

Given the single required parameter, rich annotations, and explicit usage/exclusion guidance, the description provides enough context for an agent to select and invoke the tool correctly. It states the output characteristic (structured answer with citations) despite lacking an output schema. Minor ambiguity remains about how the tool handles ambiguous or unsupported questions, but this does not block correct 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 description coverage is 100%, and all six parameters are documented as aliases or the primary 'question' field. The description adds example questions but no additional parameter-specific guidance beyond what the schema already provides, 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 clearly states a specific function: routing a factual question to the right sub-tool and returning a structured answer with pipeworx:// citations. It is explicit about the resource domain (SEC filings, FDA data, FRED/BLS, patents, real estate, news, stocks, etc.) and distinguishes itself from alternative tools like deep_research, recall, and search_within.

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

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

The description gives explicit when-to-use guidance: 'PREFER OVER WEB SEARCH for questions about current or historical data' and 'Use whenever the user asks "what is", "look up", "find"...'. It also provides concrete examples and names alternatives, instructing to use deep_research for broad multi-part research and recall/search_within for stored notes.

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 convey read-only, open-world, idempotent, non-destructive behavior. The description adds significant context beyond that: beta status, live candidate-routing trials, current absence of an active candidate, and the fact that it falls back to nothing because it is a full working router.

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 earns its place, covering current status, usage, comparison behavior, and operational guarantees. It is front-loaded with the most important identity information and contains no filler.

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

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

Given the rich annotations and full schema coverage, the description is complete for an agent to select and invoke this tool. It even addresses the response shape by noting it matches ask_pipeworx, which compensates for the lack of an output schema.

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

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

Schema coverage is 100% and the schema already explains the question parameter and its aliases clearly. The description adds no parameter-specific meaning, which is acceptable because the schema carries the full burden.

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

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

The description clearly identifies this as a beta variant of ask_pipeworx and calls it a 'universal router' with the same tools, arguments, and response shape. It also distinguishes it from sibling tools by framing it as the experimental edge where routing improvements are tested.

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

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

It explicitly says to use it exactly like ask_pipeworx when you want the newest routing, and explains that results are compared against the stable router. This gives the agent a concrete selection criterion and implies the stable ask_pipeworx is the alternative for non-experimental use.

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

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

Annotations already mark read-only/idempotent, and the description goes well beyond them: it discloses refusal behavior with the exact refusal_reason enum, the evidence/verbatim quote mechanism, the success payload, and the extra LLM call cost. 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 information-dense but every sentence earns its place: purpose, mechanism, return contract, refusal semantics, use cases, and cost tradeoff. It front-loads the most important distinction (grounded, high-stakes) before details.

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

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

With no output schema, the description fully specifies success and refusal payloads, including refusal reason values, evidence, source, and fetched_at. It also covers the cost tradeoff and sibling differentiation, leaving nothing an agent needs in order to select and invoke this tool correctly.

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

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

Schema description coverage is 100% and the schema already documents question plus all aliases. The description adds no new parameter semantics; the only relevant addition is the routing behavior, not what the parameters mean. 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 names a specific mode ('hallucination-resistant answer mode for high-stakes reads') and the core verb ('EXTRACTS the answer using ONLY what the tool result contains'). It distinguishes itself from ask_pipeworx by describing the same routing but grounded extraction, so an agent can tell them apart.

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

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

It explicitly says when to use ('whenever an answer will be quoted, cited, or acted on...') and gives a direct exclusion ('prefer ask_pipeworx for casual lookups') with a cost rationale. This is the clearest possible routing guidance to a sibling tool.

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

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

The description goes far beyond the annotations (readOnlyHint, etc.) by detailing resolution logic, fan-out behavior, response shapes, safety mechanisms (low-confidence short-circuit, closed markets), and resolution-rule risk. It even warns about inspecting market_match fields before trusting analysis. This fully discloses all behavioral traits an agent needs.

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

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

The description is excessively long (over 400 words) and includes many detailed examples and edge cases. While it is well-structured with sections and bullet points, it is not concise. An AI agent would benefit from a shorter, more focused description that quickly conveys the essential behavior.

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 (resolution, classification, fan-out, response shapes, safety, resolution-rule risk), the description covers every aspect thoroughly. It explains the resolver contract, parent event extractor, news fields, and blocking conditions. There is no output schema, but the description compensates by detailing response shapes.

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 three parameters (market, depth, include_raw) are fully described in the input schema with descriptions and examples. The tool description adds no additional semantic information about parameters beyond what the schema provides. With 100% schema coverage, a baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the verb (research), resource (Polymarket bet), and scope (pulling data in one call). This distinguishes it from sibling tools like polymarket_arbitrage or polymarket_edges, which focus on different aspects.

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

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

The description provides explicit usage examples: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also details how the tool resolves markets and classifies bets, giving context on when to use it. However, it does not explicitly state when not to use it or mention alternatives from siblings, so it is not a perfect 5.

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

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

Annotations already indicate read-only, open-world, and idempotent behavior. The description adds valuable context: data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of off-calendar fiscal years, sorted results, citation URIs, and efficiency claims—all 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 front-loaded with example queries and is well-structured. It is longer than minimal but every sentence adds value. Minor redundancy exists (e.g., 'replaces 8-15 sequential lookups' restates efficiency), but overall it is concise and informative.

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

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

Given that there is no output schema, the description adequately describes return data: paired results with sorted primary metric and citation URIs. It covers the main expectations for a comparison tool. However, it could be more explicit about the structure of the returned data.

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

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

Schema coverage is 100% with brief descriptions. The description enriches both parameters: explains type enum values with concrete data pulled (revenue, net income for company; adverse events for drug), clarifies values array constraints (2-5, tickers vs names), and adds nuance like fiscal-year handling for companies.

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

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

The description clearly states the tool performs side-by-side comparisons of 2-5 companies or drugs, with specific example queries. It distinguishes itself from single-entity tools like entity_profile and from sequential lookups, making its purpose unambiguous.

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

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

The description explicitly advises to prefer this tool over sequential single-pack lookups when comparing entities, and provides examples of when to use it. However, it does not include explicit exclusions or alternative tools for non-comparison tasks.

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, paid depth tiers, parallel decomposition behavior, gap reporting, contradiction detection, citation semantics, semantic excerpting, and expected latency. This is thorough behavioral disclosure for a complex tool.

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

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

The description is long but every section earns its place: account constraints, alternative routing, core purpose, output format, depth semantics, and latency. It is organized with clear signposts and front-loads the critical access constraint before usage details.

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

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

Despite having no output schema, the description fully explains what the agent will receive: findings with evidence, confidence, source, fetched_at, citations, gaps, contradictions, and hop metadata. It also covers auth, alternatives, depth choices, and timing, making it complete 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?

The input schema already covers both parameters well, but the description adds meaningful context about how depth controls hop behavior, how the paid tier unlocks thorough, and that questions are intended to be broad/multi-part natural language. It slightly expands on the schema without needing to compensate for gaps.

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

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

The description clearly defines the tool as grounded multi-source research across 1,500 structured data sources, with decomposition, parallel routing, and a findings packet as the output. It explicitly contrasts itself with open-web search and names ask_pipeworx for simpler lookups, giving strong sibling differentiation.

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

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

The description gives explicit when-to-use guidance: use it for broad/multi-part structured-data questions, use ask_pipeworx for single lookups, for breaking/current topics, or when not signed in. It also explains depth-tier choices and paid requirements, leaving no ambiguity about 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 already mark readOnlyHint, idempotentHint, and destructiveHint. The description adds that it returns top-N most relevant tools with names, descriptions, and full input schemas ready to call directly, providing useful context beyond annotations.

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

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

The description is clear and front-loaded with the core purpose. However, it includes a long list of example domains that could be more concise. Overall, every sentence earns its place.

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

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

Given no output schema, the description explains the return format (tools with names, descriptions, schemas) and usage context. It could mention pagination or error handling, but for a discovery tool 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?

Schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description provides example queries (e.g., 'look up FDA drug approvals') but does not add significant new meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists many example domains, and its role of discovering other tools distinguishes it from the sibling tools which are specific utilities.

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 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear context for when to use it, though it does not explicitly mention when not to use it.

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

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

Annotations already establish readOnly, openWorld, idempotent, and non-destructive, so the burden is lower. The description adds substantial behavioral detail: it fans out across multiple sources, returns 'sources_used'/'sources_failed', soft-fails on the patents source, treats empty sections as real no-data, and returns 'resolved:false' with an explicit notes line for private companies. This goes well beyond the annotations and is highly valuable to an agent.

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 and dense, but nearly every clause earns its place, covering examples, usage preference, source fan-out, return fields, edge cases, and parameter behavior. It is front-loaded with user intents and a routing directive. It could be slightly improved with bullet formatting or shorter sentences, but it is not padded or irrelevant.

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 present, the description carries the full burden of explaining what the tool returns, and it delivers: it enumerates recent_filings, fundamentals, patents, federal_contracts, fda_products, h1b, news, LEI, and sources_used/failed. It also explains fallback behavior and the expected result for private companies. An agent has enough information to call this tool correctly and interpret unusual outcomes.

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 documents both parameters with descriptions, so the baseline is 3. The description adds meaningful semantic nuance: 'type' accepts 'company' or 'ticker' interchangeably, 'value' can be a ticker, zero-padded CIK, or company name, names resolve via SEC EDGAR, and a private company is handled gracefully. These details significantly reduce the chance of misusing the parameters.

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

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

The description clearly identifies the tool as a holistic, cross-source profile builder for US public companies, with concrete example prompts to anchor the intent. It differentiates itself from single-pack SEC/XBRL/news lookups and implies it is distinct from siblings like compare_entities or resolve_entity. The resource, verb, and scope are all explicit.

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

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

The description is unusually explicit: 'ALWAYS PREFER over chaining single-pack SEC/XBRML/news lookups when the user asks for a holistic view.' It also states what input forms are accepted, what happens for private companies, and when an empty section is expected rather than an error. This effectively routes an agent toward the correct tool and sets expectations around fallback behavior.

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 destructiveHint=true and idempotentHint=true. Description adds context about clearing sensitive data but does not go beyond what annotations imply.

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 two sentences with clear front-loading of the primary action. No unnecessary words.

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

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

Given low complexity, description covers purpose, usage, and pairing. Missing mention of idempotency or return value, but annotations cover the former.

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

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

Schema already covers the only parameter 'key' with a description. Description merely restates 'by key', adding no extra meaning.

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

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

Description clearly states the verb 'Delete' and resource 'memory by key'. It also distinguishes from siblings by mentioning pairing with 'remember' and 'recall'.

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

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

Explicitly states when to use (context stale, task done, clear sensitive data) and suggests pairing with alternatives (remember, recall). Lacks explicit 'when not to use' but is still very 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 read-only, idempotent, non-destructive behavior. The description adds that it fetches a page, extracts title/description/key links, and outputs standard markdown. 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, front-loaded with the main purpose, followed by process details and use cases. Every sentence adds value with no redundant 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?

Given no output schema, the description explains the output format (single text blob) and the process. It covers the tool's functionality adequately, though error handling is not mentioned but annotations cover safety.

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

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

Schema coverage is 100% with both parameters fully described. The description does not add new semantic details beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, using specific verbs and resources. It distinguishes itself from sibling tools like scan_competitor_ai_presence by focusing on llms.txt generation.

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

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

The description includes explicit use cases (e.g., indexing client sites, drafting for own project, auditing competitors). It lacks explicit when-not-to-use or alternative suggestions, but the context is clear enough.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, fully covering safety. The description adds the precise computation behavior (Luhn check digit) and input constraints (first 14 digits). No contradictions. With high annotation coverage, the description adds useful but not critical context.

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

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

A single sentence contains all essential information: action, input scope, algorithm, and use case. No filler or redundancy. Excellent 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?

For a simple, single-parameter tool with no output schema, the description is fully complete. It explains what the tool does, when to use it, and what input is expected. The output (a single check digit) is implicit and does not require further explanation.

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

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

Schema coverage is 100% with a clear description of the 'digits' parameter ('The first 14 digits (no check digit).'). The tool description reinforces this but does not add new semantic info beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the action ('Compute'), the algorithm ('Luhn check digit'), the input scope ('first 14 digits of an IMEI'), and the use case ('complete or repair an IMEI'). It effectively distinguishes from sibling validate_imei.

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

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

The description explicitly states the use case ('use to complete or repair an IMEI'). While it does not explicitly contrast with validate_imei or other alternatives, the context of sibling tools makes the differentiation clear. A slightly more explicit alternative mention would elevate to a 5.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds value by detailing the return fields (id, type, params, created_at, last_fired_at, fire_count) and the default scope (active subscriptions). It does not contradict annotations.

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

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

The description is two sentences long, front-loaded with the purpose, and every sentence adds value. No unnecessary words.

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

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

The tool has low complexity with 1 optional parameter. The description covers purpose, return fields, and usage guidance. It lacks mention of pagination or ordering, but for a standard list tool this is acceptable. Output schema is absent but return fields are 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?

The input schema has 1 parameter (include_inactive) with a full description. Schema coverage is 100%. The tool description does not add additional 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?

The description clearly states 'List the caller's active subscriptions.' It uses a specific verb and resource, and distinguishes from sibling tools like subscribe and unsubscribe by being a read-only list operation.

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

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

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

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

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

With annotations all false, the description carries the full behavioral burden and delivers thoroughly: it explains the claim_token workflow for tracking feedback, discloses the 5-per-identifier-per-day rate limit, states it's free/no quota, and warns against pasting end-user prompts. No annotation contradiction exists.

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

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

The description is long but every sentence earns its place: purpose, when-to-use, exclusions, workflow, rate limit, and cost. It is front-loaded with the core purpose sentence and follows a logical sequence without redundancy.

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

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

Given no output schema, the description explains the return behavior (claim_token, later status retrieval) adequately. It also covers rate limits, scope boundaries, and reporting etiquette, making it complete for a feedback tool of this complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful behavior beyond the schema by clarifying that filing without an account returns a claim_token and that later calls should pass it back as pipeworx_feedback({claim_token:...}). It also instructs users to describe issues in terms of Pipeworx tools/packs, guiding the message and context parameters, though not drastically.

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

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

The description opens with a specific verb and resource ('Tell the Pipeworx team something is broken, missing, or needs to exist'), clearly distinguishing it from sibling tools. It further enumerates concrete use cases (bug, feature/data_gap, praise), making the purpose unmistakable.

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

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

Explicit when-to-use guidance is provided for each feedback type, and equally explicit when-not-to-use guidance ('ONLY for tools served by this Pipeworx connection', 'file it with that server instead' for other MCP servers). This is exemplary alternatives handling.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. Description adds non-redundant context: self-aggregating from CF analytics-engine, no PII, caching behavior (5min-1h), and output structure (pack, tool, count). 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?

Description is four sentences with a bullet list. Every sentence is meaningful, no waste, front-loaded with the core behavior.

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 fully covers purpose, usage, behavior, and parameter semantics.

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 an enum for window. Description adds guidance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This adds usage context beyond the schema.

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

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

The description clearly states 'Returns the top tools, top packs, and total call volume' with specific verb and resource. It distinguishes from sibling tools like 'discover_tools' by focusing on trending usage rather than available 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 provides three specific use cases (discovering hot data sources, confirming canonical tool, seeing alignment) but does not explicitly mention when not to use it or compare 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?

Discloses behavioral traits beyond annotations, including Jaccard similarity threshold, partition filter for placeholders, fill check with realizable edge, and conditions for not trading. No contradiction with annotations (readOnlyHint, etc.).

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 lengthy but well-structured: uses clear paragraphs for each mode and key concepts (semantic anchor, partition filter, response, fill check). Some redundancy could be trimmed, but overall organization aids comprehension.

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, describes response fields (opportunities[], partition_check details, fill check results). Covers all modes, edge cases (low similarity, placeholders), and refers to related tool. Complete for an agent to use correctly.

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

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

Schema coverage is 100% but description adds substantial meaning: explains expected input formats (slugs/URLs for event, seed question for topic), describes what each mode does, and clarifies behavior like cross-event scanning and similarity checks.

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 explicitly states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks. It clearly distinguishes three modes (no args, event, topic) and differentiates from sibling tools like polymarket_edges and polymarket_fill_risk by specifying unique functionality and use cases.

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

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

Provides explicit guidance on when to use each mode: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', 'topic (for cross-event scanning)'. Also advises against trading when fill check fails and directs to polymarket_fill_risk for custom sizing.

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

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

Annotations (readOnlyHint, idempotentHint) are consistent. The description adds extensive behavioral details: model families, caching, diagnostics, Fed exclusion reasons, and edge computations, all beyond what annotations provide.

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

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

The description is informative and front-loaded with purpose, but is verbose. Every sentence adds value, but structure could be more organized (e.g., sections).

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 parameters, no output schema, and complex response structure, the description thoroughly explains segments, edge metrics, diagnostics, and caching, leaving 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 coverage is 100%, providing baseline 3. The description adds context (e.g., 'tradeable-edge filter' for max_spread_pp) and explains how parameters interact, adding marginal value.

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

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

The description clearly states it scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, distinguishing it from siblings like polymarket_arbitrage and polymarket_edge_tracker through specific model families.

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 clear context for use ('what should I bet on today') and describes knobs for filtering, but lacks explicit when-not-to-use guidance or direct comparison to sibling tools.

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

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

Annotations already indicate read-only and idempotent; the description adds critical behavioral details: snapshots on cache-miss, gaps meaning no scan, decay computation from daily closes, and lifespan median as competition clock. 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 detailed but efficiently structured: purpose first, then response fields, then limits. Each sentence adds value; no redundancy. Slightly long but justified by complexity.

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

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

Despite no output schema, the description fully explains all three response arrays (tracked, expired, snapshot_dates) with edge cases and limits. Complete for a read-only analytics tool.

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

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

Schema covers both parameters fully; description reinforces defaults (14 days, '1wk') and adds context by tying them to the response structure (e.g., window affects snapshot family). Adds meaningful context beyond schema.

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

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

The description clearly states it provides edge persistence and decay telemetry from daily snapshots, and contrasts with the sibling 'polymarket_edges' by focusing on historical tracking. The verb 'answers' and specific output fields make the purpose obvious.

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 what the tool returns and highlights limits (e.g., 60-day TTL, snapshot gaps). It implies use when needing edge persistence history but lacks explicit when-not or alternative tool comparisons.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. Description adds behavioral context: walks the ladder, returns fill details and verdicts (clean|degraded|cannot_fill), and warns about forced directional risk. No contradictions. Since annotations do heavy lifting, description supplements well.

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

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

Well-structured with clear sections (REQUIRES, SINGLE-MARKET, BASKET) and front-loaded key purpose. Each sentence adds value, though slightly lengthy; could be tightened without losing clarity.

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, yet description comprehensively lists return fields (top_of_book, vwap_fill_price, slippage_pp, etc.) and verdicts. Covers thin legs, directional risk, and profit calculations for both modes. Complete for a complex tool.

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

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

Schema coverage is 100%, but description adds substantial meaning: explains mutual exclusivity of market vs event, default side behavior in basket mode, size interpretation for buys vs sells and basket notional. Adds format details (slug/URL) and default values, going well 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 it's a 'Realizable-vs-theoretical edge check' against order-book depth, distinguishing single-market and basket modes. It explicitly differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by stating 'USE THIS before acting on' those signals.

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

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

Explicit usage 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 and theoretical overround, providing clear when-to-use and when-not-to-use 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?

The description is exceptionally transparent about internal behavior, including compatibility_warning and compatibility_codes semantics, flag meanings, unknown legs never being paired, skipped_cross_type/subtype counters, gross-vs-net fees, and the fact that temporal_alignment null means 'could not compute.' This goes far beyond the readOnlyHint and idempotentHint annotations, which already cover safety.

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

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

The description is long but densely structured, with front-loaded purpose, then mode selection, response behavior, safety fields, flag codes, and caveats. It repeats some enum values from the schema, but this repetition serves quick comprehension. Every section earns its place, though it could be tightened slightly by reducing the inline code enumeration.

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 orients the agent to every important response facet: leg-by-leg prices, top_spreads_pp with per-entry flags, skipped_unclassified, low_confidence_pairs, temporal_alignment, fees_note, and counters. It also warns about the rarity of real tradeable cross-venue spreads, ensuring the agent sets correct expectations.

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 all three parameters at 100% coverage, so the baseline is 3. The description adds meaningful extra semantics by explaining that both modes run the identical token-overlap matcher, that explicit parameters override the topic-mapped side, and that safety fields apply equally in both modes—information 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 description opens with a precise resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' which clearly identifies the tool's domain and differentiates it immediately from single-venue tools like polymarket_edges or polymarket_arbitrage. It further distinguishes the tool by explaining that it handles non-equivalent bet shapes and applies the same matcher in both 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?

The description provides clear context through TWO MODES: pre-mapped topic shortcuts versus explicit kalshi_event_ticker + polymarket_event_slug pairings. It also warns that pre-mapped topics are not necessarily tradeable, which advises against over-trusting results. However, it does not name alternative sibling tools or explicitly state when to prefer a different tool such as polymarket_arbitrage.

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

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

Annotations already declare readOnly and idempotent. Description adds scoping to identifier and behavior of omitting key (list all). No contradictions.

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

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

Three well-structured sentences. Front-loads core action and purpose. No unnecessary words.

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

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

No output schema, and description does not specify return format (e.g., string value or list). Could be more complete about response structure.

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

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

Schema coverage is 100% with description per parameter. Description adds examples but no new semantic detail beyond schema.

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

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

The description clearly states the tool retrieves a value by key or lists all keys if omitted, with concrete examples (ticker, address, research notes). It distinguishes from sibling tools 'remember' and 'forget'.

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

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

Explicitly says when to use: to look up previously stored context without re-deriving. Mentions pairing with remember/forget. Could be more explicit about when not to use, but context is clear.

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

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

Description adds value beyond annotations by explaining the mark_read parameter which modifies read state. Despite readOnlyHint annotation claiming no side effects, the description honestly discloses this behavioral trait, making it transparent.

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

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

Four sentences with no wasted words. Each sentence adds essential information: core purpose, return contents, filtering options, mark_read behavior, and alternative access.

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

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

Despite no output schema, description enumerates return fields (source, citation_uri, raw payload). Parameters are well-documented, alternative access is provided, and annotations cover safety. Complete for a read-focused paginated 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%, so baseline is 3. Description adds context: example filter type 'sec_8k', ISO timestamp for since, limit range 1-200, and behavior of mark_read, going beyond schema descriptions.

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

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

Description clearly states 'Pull fired events from your subscription feed,' specifying the verb and resource. It distinguishes from sibling tools like list_subscriptions (which lists subscriptions, not events) by focusing on retrieving alert events from the feed.

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?

Explanation of filtering by type and/or since provides usage context. Mention of polling and alternative direct URL access gives guidance on when to use this tool versus scripts/dashboards, but doesn't explicitly exclude 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?

Although annotations declare readOnly, idempotent, etc., description adds crucial behavior: parallel call, fan-out to three sources, error handling (GNews fallback, patent soft-fail), and return format (grouped changes, 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?

Description is long but justified by complexity. Front-loaded with query examples, but some details (e.g., patent API sunset) could be compressed. No wasted sentences.

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

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

Without output schema, description adequately explains return: structured changes grouped by source, total_changes count, pipeworx:// citation URIs. Covers all necessary aspects for correct agent invocation.

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

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

Schema has 100% coverage, but description enriches each parameter: 'since' accepts ISO dates and relative shorthand with examples; 'value' can be ticker or CIK; 'type' only 'company' today. Provides guidance like 'Use "30d" for typical monitoring'.

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 (change feed), concrete resource (company), and actionable query examples: "What's new with X". Explicitly distinguishes from sibling 'entity_profile' by stating use case difference.

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

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

Provides explicit when-to-use patterns and when-not-to (static profile via entity_profile). Details fallback behavior (GDELT→GNews), soft-fail for patents, and typical 'since' values ('30d', '1m').

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

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

The description adds behavioral details beyond annotations: scoping by identifier, persistence differences between authenticated users (persistent) and anonymous (24 hours). No contradictions with annotations (idempotentHint=true, etc.).

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

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

The description is concise (4 sentences) and well-structured: starts with purpose, then usage guidelines, then behavioral details, all 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 simplicity (2 string params, no output schema), the description covers purpose, usage, parameter semantics, and behavioral aspects comprehensively.

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

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

Schema coverage is 100% with descriptions, but the description adds value by providing concrete usage examples for key (e.g., 'subject_property') and value ('findings, addresses, notes'), enhancing the schema.

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

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

The description clearly states the verb 'save' and the resource 'data' (key-value pair). It defines the tool's purpose as storing information for reuse, distinguishing it from siblings like 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?

The description explicitly says 'Use when you discover something worth carrying forward' and mentions pairing with recall and forget. This provides clear context and alternatives.

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

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

Annotations already include readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context: graceful degradation of enrichment if GLEIF/OpenFIGI unavailable, EDGAR identifiers still return, cascading internal lookups, and how unresolvable identifiers are handled. Minor gap: it doesn't disclose rate limits or failure response format, but the description 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?

The description is dense and information-rich but somewhat rambling. It packs many examples and caveats into long sentences, and the opening list of user phrasings is useful but could be trimmed. It is front-loaded with purpose, but the structure is somewhat stream-of-consciousness.

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 no output schema, the description is thorough: it explains return types (CIK, ticker, LEI, FIGI, RxCUI), behavior on partial resolution, and input conventions. It doesn't fully specify all return fields or error cases, but given the tool's complexity and the annotations, it is quite 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 description coverage is 100%, so the baseline is 3. The description reinforces the 'type' parameter with supported types and enriches the 'value' parameter with detailed examples and a negative example. It adds meaningful nuance for drug names and bond issuer names.

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: resolving user-spoken names to canonical/official identifiers. It gives a specific verb ('resolve'), resource ('entity names to identifiers'), and differentiates from siblings by naming the input types and the identifier outputs.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID.' It also provides rich usage guidance: supported types, what inputs are accepted, when to use it instead of manual lookups, and how it replaces multiple lookups. It also includes a caveat about what to pass for bonds.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds value by explaining the tool makes multiple probes (behavioral context) and returns a ranked list with score, confidence, and signal density, going beyond the annotations.

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

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

The description is three concise sentences, front-loaded with purpose, mechanism, and use case. Every sentence adds value with no fluff, making it 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?

With no output schema, the description specifies the output format (ranked list with score, confidence, signal density per entity). It explains input parameters, the underlying ai_visibility_check, and provides a usage example. For a tool with 4 params and no nested objects, this is fully complete.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds nuance: explains the first entity is treated as the 'subject' for narrative, and clarifies model usage (omit for just workers-ai). This additional context raises the score.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, using ai_visibility_check, and ranks results. It provides a concrete example question and distinguishes from sibling tools by focusing on batch comparison for competitive audits.

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 a clear use case ('competitive AI-marketing audits') and an illustrative question, but does not explicitly state when not to use this tool or compare it to alternatives like compare_entities or individual ai_visibility_check calls.

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

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

The description adds rich behavioral context beyond annotations: partial failures, bundlephobia first-measure delay of 5-30 seconds, sources_failed list, and graceful degradation. Annotations indicate readOnly, openWorld, idempotent, non-destructive, and 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 packed with information, well-organized, and front-loads the main purpose. While slightly long, every sentence serves a purpose, making it efficient for an AI agent.

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

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

Despite no output schema, the description details the return structure: summary block fields, per-advisory detail, links, and alternative versions. This is thorough for a composite tool with two services, covering all necessary context.

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

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

Schema coverage is 100% with both parameters described. The description does not add significant value beyond the schema; it essentially restates the parameter descriptions. 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 it's a composite check for npm packages combining deps.dev and bundlephobia, with specific verb 'check' and resource 'npm package'. It distinguishes itself from siblings by focusing on npm dependency analysis, unlike other tools like bet_research or compare_entities.

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

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

The description explicitly says 'Use whenever an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me'. It also specifies the NPM ecosystem only and mentions partial fallback and alternatives for other ecosystems (deps.dev:version directly).

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

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

Annotations already provide readOnlyHint, idempotentHint, etc. Description adds value by disclosing chunking strategy (500-char overlapping windows), embedding model (BGE-base-en), truncation at 200K chars with flagging, and inclusion of character offsets. This goes beyond annotations, though response structure is not detailed.

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 concise (~120 words) with front-loaded purpose, followed by usage guidance, examples, and technical details. No redundant or unnecessary sentences.

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

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

Covers all key aspects: what it does, when to use, pairing with sibling, input schema with examples, technical details (chunking, truncation, offsets), and output description (top-N passages with offsets and scores). No output schema, but description adequately explains return values.

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

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

Schema coverage is 100% with good descriptions. Description adds concrete examples (e.g., SEC 10-K body, 'supply-chain risk') and clarifies the role of query as a natural-language request, making parameters more actionable.

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 performs semantic search inside a fetched record, with specific verb 'search' and resource 'inside a fetched record'. It distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded and contrasting usage scenario 'when the record is too big to cram into the prompt'.

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 (record too big for prompt) and pairs with sibling ask_pipeworx_grounded. It also implies when not to use (if record fits in prompt). Provides clear context for decision-making.

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

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

Annotations show readOnlyHint=false, destructiveHint=false, idempotentHint=true. The description confirms it creates a subscription, adding many behavioral details: requires OAuth, delivery channel specifics, phone verification, 10/day SMS cap, webhook signing secret returned once, auto-disable after 10 failures. This is rich context beyond annotations.

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

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

The description is thorough but somewhat lengthy. It front-loads the purpose and then systematically covers types and delivery. Every sentence adds value, but the level of detail could be trimmed slightly for agents needing quick comprehension. Still well-organized.

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

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

Despite no output schema, the description states 'Returns the new subscription id.', which is sufficient. It covers prerequisites, all supported types, delivery options, and limitations (phone verification, SMS cap, webhook auto-disable). For a subscription creation tool, it is highly complete.

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

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

With 100% schema coverage, the description provides detailed examples for each type (e.g., sec_8k: {ticker:"AAPL", items?:["5.02","1.01"]}) and explains delivery object fields in depth. This adds significant meaning beyond the schema's terse property 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: 'Create a proactive monitoring subscription to a live-data event stream.' It specifies the action (subscribe), the resource (alerts), and distinguishes from siblings like list_subscriptions and unsubscribe. The supported types are listed, providing concrete examples.

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 usage context: requires Pipeworx OAuth, can't be used with anonymous/BYO accounts. It implies when to use alternative tools like recent_alerts for pulling the always-on feed. However, it doesn't explicitly state when not to use this tool vs. others, leaving room for slight ambiguity.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds value by explaining the output structure (category-bucketed examples with exact tool+argument shapes) and that it draws from a live catalog, which the annotations don't cover.

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 slightly long but front-loaded with the most important information: the onboarding purpose and when to use it. Every sentence contributes to the agent's understanding, but it could be slightly more concise 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 simplicity (one optional parameter, no output schema), the description is thorough. It covers the purpose, usage context, parameter behavior, and output format, leaving no ambiguity. Combined with strong annotations, the tool definition is fully self-contained.

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

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

Schema coverage is 100% for the single optional parameter. The description enhances understanding by explaining that omitting topic gives the full spread while providing a specific topic focuses the results, and lists example values (finance, pharma, etc.).

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

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

The description clearly states the tool is the onboarding entry point for an agent to learn about Pipeworx's capabilities. It uses specific verbs ('returns category-bucketed example questions') and distinguishes it from siblings like ask_pipeworx and entity_profile by positioning it as the first tool to call when unsure of what to ask.

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 the agent to 'Use this FIRST when you do not yet know what Pipeworx can do for you' and explains when to omit or specify the topic parameter. While it doesn't explicitly list when not to use it, the context is clear and it provides good guidance on invocation timing.

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

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

Beyond annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true), the description adds that rows are deactivated not deleted, preserving historical events, and clarifies ownership enforcement.

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

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

Two concise sentences with no wasted words, front-loaded key action and constraints.

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

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

Given the tool's simplicity (1 param, no output schema, clear annotations), the description fully covers side effects, ownership, and alternative tool usage, leaving no gaps.

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

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

Schema coverage is 100% with a clear 'id' description. The description adds 'by id' but no additional meaning beyond the schema, so baseline 3 is appropriate.

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

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

Description clearly states 'Cancel a subscription by id.' with a specific verb and resource, distinguishing it 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?

Explicitly mentions ownership enforcement ('you can only cancel your own subscriptions') and explains the deactivation behavior, providing guidance on when to use and alternatives like 'recent_alerts'.

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

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

Annotations already declare the tool as read-only, open-world, idempotent, and non-destructive. Beyond that, the description discloses critical behavioral details: the dual-path routing logic, the specific verdict types, the meaning of 'could_not_verify' with verification_error field, and a warning not to interpret it as evidence. It also notes the tool aggregates 4-6 calls, which is a useful execution insight for the agent.

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 information-dense, with every sentence contributing: example queries, path routing, verdict list, caller warning, and a benefit statement. It is front-loaded with the core purpose in the first sentence. While not as terse as a two-line description, the length is justified by the tool's complexity and the need to explain error semantics.

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 burden of explaining return values, and it does thoroughly: verdict types, the actual value with citation, reasoning, and the special meaning of could_not_verify vs unsupported. It covers the main scenarios (company-financial and generic claims), error handling, and the replacement-of-multiple-calls benefit. This is complete for an agent to invoke and interpret results 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?

Input schema covers both parameters with clear descriptions (100% coverage), so baseline is 3. The description adds extra meaning by explaining how tolerance_pct overrides the implied tolerance and how to use it for hallucination detection (set 1-2). It also provides examples for the claim parameter, reinforcing the schema. This goes beyond the schema's literal field 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 function: natural-language claim verification against authoritative sources. It provides a specific verb ('validate', 'verify'), the resource (claims), and distinguishes itself from siblings by framing it as a consolidated verification tool that replaces multiple sequential calls. The examples ('Is it true that…', 'fact check') make the purpose instantly recognizable.

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

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

It explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct,' which is strong when-to-use guidance. It also differentiates between company-financial claims (SEC EDGAR fast path) and other claims (grounded pipeline), giving routing context. However, it doesn't mention when not to use it or provide alternative tools for general fact lookup, though the routing logic implies alternatives exist.

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

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

Annotations already declare readOnly, idempotent, non-destructive. The description adds key context: 'Keyless/offline' (no side effects), 'Spaces/dashes ignored' (input processing), and 'Validates the number, not the device' (scope limitation).

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

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

The description is two efficient sentences, front-loaded with the core purpose. Every sentence adds value: validation method, input handling, output details, and scope clarification.

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 validation tool with one parameter and no output schema, the description fully explains input handling, validation logic, and the components of the result (validity, TAC, serial, check digit). It also clarifies what the tool does not do.

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

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

Schema coverage is 100% for the single parameter, but the description adds useful detail: allowed formats (15/16 digits), that spaces/dashes are ignored, and what the validation checks (Luhn). This goes beyond the schema's basic description.

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

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

The description clearly states it validates IMEI/IMEISV with specific validation rules (Luhn check for IMEI) and explains what it returns (validity, TAC, serial, check digit). It distinguishes from device validation by explicitly saying 'Validates the number, not the device.'

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

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

The description includes 'Keyless/offline' indicating no authentication needed, and clarifies it does not validate the device. However, it does not explicitly differentiate from sibling tool 'imei_check_digit', though the purpose is distinct enough.

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