Emoji Oracle

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds key behaviors: default free model, BYO Anthropic key with direct payment, per-model response structure.

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

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

Concise, single paragraph with clear front-loading of purpose, followed by detail and use cases. Every sentence adds value, no wasted words.

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

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

Comprehensively covers inputs, optional parameters, and return format (per-model scores, confidence, signals, raw_response, combined view). Lacks output schema but description suffices.

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 meaning beyond schema: explains default model, purpose of _apiKey (BYO key, direct payment), and context disambiguation role.

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

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

The description uses specific verbs (probe, score) and resources (LLMs, visibility) and clearly distinguishes from siblings like ask_pipeworx or bet_research by focusing on AI visibility scoring.

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

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

Explicitly mentions use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring). Does not explicitly state when not to use or alternatives, 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?

Annotations already declare the tool read-only, open-world, idempotent, and non-destructive. The description goes beyond this by explaining the routing behavior, argument filling, structured-answer output, and stable pipeworx:// citation URIs. It does not cover every edge case like rate limits or error behavior, but it provides meaningful behavioral context 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 long but information-dense: it front-loads the crucial preference directive, supports with concrete examples, and closes with routing guidance for related tools. Some redundancy exists around routing and the broad source list, but each sentence generally 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?

The description fully covers what the tool does, when to use it, what kind of input it accepts, what output to expect, and when to choose sibling tools instead. Given the lack of an output schema, the mention of structured answers with citation URIs is especially valuable. Nothing essential is missing.

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

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

The input schema already covers all six parameters at 100%, including aliases and a clear description for the question field. The tool description adds useful examples but no new parameter-level semantics beyond what the schema already states. Baseline 3 is appropriate here.

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 immediately says this should be preferred over web search for factual questions and explains that it routes queries to a large set of tools and returns structured answers with citations. It clearly distinguishes itself from siblings like ask_pipeworx_grounded and deep_research by naming them as alternatives. This is a specific, actionable statement of purpose, not a tautology.

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, use for 'what is', 'look up', 'find', 'get the latest', and any factual question about real-world entities or numbers. It also provides clear alternatives for focused single-answer questions and broad multi-part questions, so an agent can route correctly.

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

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

The annotations declare readOnly, openWorld, idempotent, and non-destructive behavior, but the description adds valuable context beyond that: it is an experimental edge, candidates may be live or retired, a specific retirement date is given, and it falls back to nothing—it is still a full working router. No contradiction with annotations 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?

Four sentences, each earning its place: what the beta is, current candidate state, usage instruction, and no-fallback clarification. The core fact is front-loaded and the rest is tightly 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?

The description covers the operational essentials: identical behavior to ask_pipeworx, same response shape, no fallback, and current status. It does not spell out the response shape in detail, but references the stable sibling's identical contract, which is reasonable for a router tool with a single required question parameter.

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 'question' and its aliases at 100% coverage, so the schema carries the parameter documentation burden. The description adds only that arguments are the same as ask_pipeworx, which is useful but not necessary for invoking the tool correctly.

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 beta version of ask_pipeworx: a universal router with the same 5,798 tools, arguments, and response shape. It differentiates itself from the stable ask_pipeworx by noting experimental routing improvements, 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 to use it exactly like ask_pipeworx when the newest routing is desired, and explains that results are compared against the stable router. It also clarifies the current state: no candidate is active, so it currently matches ask_pipeworx exactly. This gives clear conditional guidance and identifies the stable sibling as the comparison point.

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

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

The description adds substantial behavioral context beyond the readOnly/idempotent annotations: it details the operational flow (routing across many tools, fetching, then extracting only from the result), documents both success and refusal return shapes, and enumerates refusal reasons. This is exactly the kind of transparency that helps an agent know what to expect.

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 phrase earns its place: purpose, mechanism, return format, usage context, and cost tradeoff are compactly organized. The critical differentiator (grounded extraction) is front-loaded, and the guidance ends with a clear preference directive.

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 there is no output schema, the description fully explains return values and failure modes. It also covers the tool's scope (5,798 tools across 1517 sources), its higher cost, and how it relates to the sibling tool. Nothing essential for an agent to invoke it correctly is missing.

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

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

Schema coverage for the only substantive parameter (question plus aliases) is 100%, so the schema already explains the argument. The description does not add meaningful parameter-level details, and per the baseline rule, a 3 is appropriate when structured schema carries the 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 opens with 'Hallucination-resistant answer mode' and clearly states it extracts answers using only tool results, distinguishing it from the sibling ask_pipeworx. It names the exact action, resource scope, and the return contract, leaving no ambiguity about what the tool does.

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

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

Provides explicit when-to-use guidance: 'whenever an answer will be quoted, cited, or acted on' with examples including financial verdicts and legal claims. It also states the tradeoff (extra LLM call) and directs casual lookups to ask_pipeworx, giving agents a clear decision rule.

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

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

Annotations already mark the tool as read-only and idempotent. The description adds extensive behavioral details: market resolution, classification, parallel fan-out, return structure, edge cases (low confidence, closed, illiquid), resolution-rule risk, and parent event extraction. 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?

Front-loaded with a clear purpose statement. The description is lengthy but necessary given the tool's complexity and lack of output schema. Each section (response shapes, resolver contract, safety) earns its place. Could be slightly trimmed but is 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?

With no output schema, the description fully documents the return structure (market, analysis, evidence, match confidence, parent event, news fields) and all edge cases (low confidence, closed markets, illiquid spreads, cancellation rules). Adequate for an AI agent to use the tool correctly.

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

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

Schema coverage is 100% with clear parameter descriptions. The description enriches this by explaining how the 'market' parameter is resolved (via slug, URL, or question text), how 'depth' affects fan-out, and that 'include_raw' controls summary vs full payload. Examples further clarify usage.

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

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

Begins with a clear verb+resource statement ('Research a Polymarket bet') and specifies input types (slug, URL, question). The examples and sibling context show it is specialized for Polymarket betting, distinguishing it from other Pipeworx research tools.

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

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

Explicitly says 'Use for...' with three common betting queries. Describes when the tool short-circuits (low confidence, closed markets) and when to inspect fields (market_match_confidence). Lacks explicit 'do not use' scenarios but provides ample context.

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

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

Annotations already indicate read-only, open-world, idempotent, and non-destructive. The description adds key behavioral details: data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), off-calendar fiscal year handling, sorted results, and citation URIs. 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 front-loaded with common queries and is concise at 4-5 sentences. It efficiently conveys purpose, usage, and behavior 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 return format (paired data + citation URIs) and sorting behavior. It covers the tool's key aspects for effective use.

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

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

Schema coverage is 100%. The description adds context for values (tickers/CIKs for company, names for drug) and explains what data each type retrieves, enhancing the schema's minimal descriptions.

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

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

The description clearly states it performs side-by-side comparison of 2-5 companies or drugs in one parallel call, listing common query phrases (e.g., 'which is bigger') and distinguishing from sibling tools like entity_profile.

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

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

The description explicitly says to prefer this over sequential single-pack lookups and explains when to use company vs drug type. It lacks explicit exclusions but provides clear guidance.

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

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

Annotations already signal readOnly/openWorld/idempotent, and the description adds substantial behavioral context: account requirements, paid tier, gap handling ('never invented'), contradiction reporting, resolvable citation_uri, semantic excerpting, and latency expectations. No contradiction with annotations.

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

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

The description is long but dense and well-organized: caveats and alternatives are front-loaded, followed by mechanics, output shape, and latency. Every sentence earns its place; there is no filler or repetition of schema boilerplate.

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 must explain the return shape, and it does: findings packet, evidence, confidence, source, fetched_at, gaps[], contradictions[], hop, and citation_uri. It also covers prerequisites, depth behavior, timing, and sibling routing, making it complete for 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 coverage is 100%, so the schema already documents both parameters. The description still adds value by explaining what the depth levels actually do (hop/gap-recovery/contradictions) and by clarifying that the question can be broad/multi-part, though some of this reinforces the schema rather than adding new syntax.

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

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

The description states a specific action and resource: grounded multi-source research over Pipeworx's structured data sources. It clearly distinguishes itself from open-web search and from sibling ask_pipeworx, with concrete examples that signal the intended question type.

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 this tool ('best for broad/multi-part questions over structured data') and when not to ('for a single lookup use ask_pipeworx instead'). It also handles the signed-out fallback, routing agents to ask_pipeworx if no account is available.

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

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

The annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds that results include 'full input schemas (with curated examples)' and that each result is 'ready to call directly.' It does not contradict annotations but adds useful context about the return format. No additional behavioral details (e.g., rate limits, pagination) are provided.

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

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

The description is concise, front-loaded with the main purpose, and structured logically: what it does, when to use, what it returns, and a call-to-action ('Call this FIRST'). Every sentence adds value with no redundancy.

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

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

Given the tool's complexity (meta-tool, 6 parameters, no output schema), the description provides sufficient context: purpose, usage scenario, return format (names, descriptions, schemas with examples). It could be enhanced by noting that discovery is limited to the tool provider's registry or by explaining the search mechanism, but it is largely complete for an agent.

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

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

With 100% schema description coverage, the schema already documents all parameters (including aliases and limit). The description adds value by providing natural language examples ('look up FDA drug approvals', 'analyze housing market trends') and clarifies that the query accepts natural language. However, the incremental meaning beyond the schema is modest.

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 specific domains (SEC filings, FDA drugs, etc.) and distinguishes itself from siblings by noting it returns top-N ready-to-call tools. The phrase 'Call this FIRST when you have many tools' further clarifies its role as a discovery tool.

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

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

The description explicitly states when to use this tool: 'Use when you need to browse, search, look up, or discover what tools exist for...' and advises to 'Call this FIRST when you have many tools.' It implies that for specific known tasks, one might use sibling tools directly, but does not name alternatives or explicitly state when not to use it.

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

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

Annotations indicate a safe, idempotent, read-only operation. The description adds behavioral context by stating the output includes 'cryptic emoji prophecy', 'vibe rating (1-10)', and optional 'text explanation'. This goes beyond the annotations to describe the informal, amusing nature of the response. 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 two sentences, with the first sentence front-loading the purpose. Every word is meaningful; no fluff. It efficiently communicates what the tool does and what it returns.

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

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

The description covers the key outputs (emoji sequence, vibe rating, optional interpretation) and parameters. An output schema exists, so details on return format are not required. For a simple, playful tool this is complete. Minor omission: no error handling or edge cases, but acceptable for this 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%, so the description's addition is moderate. It reiterates the role of 'question' and adds context about 'interpret' (optional interpretation) and 'emoji_count' (number of emojis). It also mentions 'vibe rating' which is not in the schema. This adds value beyond the schema, justifying a 4.

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

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

The description clearly states the tool's purpose: asking a question to the Emoji Oracle and receiving a prophetic emoji response with a vibe rating. It specifies the verb 'Ask', resource 'Emoji Oracle', and outputs (emoji sequence, vibe rating, optional interpretation). This distinguishes it from sibling tools like 'ask_pipeworx' which are for different purposes.

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 'Ask the Emoji Oracle a question', which provides clear usage context for light-hearted, mystical queries. It does not provide explicit when-not-to-use or alternative tools, but the nature of the tool (cryptic emoji prophecy) naturally distinguishes it from more serious siblings like 'deep_research' or 'entity_profile'.

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

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

Annotations declare read-only/idempotent behavior, and the description goes much further: it lists upstream sources, discloses the USPTO API sunset soft-fail, explains that empty sections are real 'no data', and states private companies return resolved:false with a notes line. This provides honest failure semantics beyond what annotations offer.

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

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

The description is long but well organized: query examples, preference rule, source fan-out, return-section details, input formats, and edge cases. Some redundancy exists with the schema and the repeated example phrasings, but nearly every segment carries behavior an agent needs.

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 inventories every returned section, upstream source, and failure mode such as sources_failed, empty sections, resolved:false, and patent soft-fails. For a high-complexity multi-source tool, this is enough for an agent to call it correctly without further inference.

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 type/value 100%, including that both type values behave identically. The description adds concrete accepted forms (ticker, zero-padded CIK, company name) and notes SEC EDGAR name resolution, but this mostly restates schema content with only marginal additional 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 leads with concrete user phrasings and states the exact function: a full cross-source profile of a US public company in one parallel call. It differentiates from chaining single-pack SEC/XBRL/news lookups and enumerates the returned sections, so an agent can tell exactly what this tool delivers.

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

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

Explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' and ties usage to holistic-view requests. However, it does not name overlapping siblings like resolve_entity or compare_entities or state exclusions, leaving some routing 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 destructiveHint=true; description adds 'clear sensitive data' context but 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?

Two sentences with no waste; purpose and usage front-loaded.

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

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

Description covers purpose, usage, and pairing with siblings; sufficient for a simple tool with full schema and annotations.

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

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

Schema coverage is 100%, so baseline is 3; description adds little beyond schema's description of 'key'.

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 states 'Delete a previously stored memory by key' clearly specifying verb and resource, and distinguishes itself from siblings 'remember' and 'recall' referenced in the description.

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

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

Explicitly provides when to use: 'when context is stale, the task is done, or you want to clear sensitive data', and suggests pairing with related tools.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds process details (fetch, extract, emit) and output format, but does not contradict annotations. Additional behavioral context beyond annotations is minimal.

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

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

Description is a few sentences, front-loaded with purpose, followed by details. No superfluous text. Could be slightly tighter but is 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 explains the output format. Both parameters are well covered. Annotations provide safety profile. Use cases are given. Complete for a simple read-only generation 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?

Input schema covers both parameters with descriptions. The description adds an example for 'url' and restates default for 'max_links', but provides no new semantic meaning beyond the schema.

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

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

The description clearly states it generates an llms.txt file, specifying the resource (site URL) and the action (fetch, extract, emit). It distinguishes 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?

Explicit use cases are given (client indexing, own project, competitor audit), but no direct when-not-to-use or alternatives compared to siblings. The context is clear but lacks exclusion criteria.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive. The description adds that it returns specific fields and is scoped to the caller's subscriptions, providing useful behavioral 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?

Two concise sentences: first states purpose and output, second provides usage guidance. No extraneous information.

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

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

For a simple read-only tool with one optional parameter and no output schema, the description covers purpose, return fields, and usage context comprehensively. Annotations handle safety profile.

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 single parameter (include_inactive) is fully described in the schema (100% coverage). The description does not add additional meaning, so baseline score applies.

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

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

The description clearly states the tool lists the caller's active subscriptions and specifies the returned fields. It distinguishes from siblings like subscribe/unsubscribe by framing it as a lookup tool for review and cancellation.

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

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

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

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

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

Annotations are all false and thus provide little behavioral insight. The description compensates by disclosing rate limits ('5 per identifier per day'), cost ('Free; doesn't count against your tool-call quota'), and the claim_token workflow for anonymous filing and later retrieval. This adds significant behavioral context 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 front-loaded with a clear purpose and then delivers dense, non-redundant guidance. Every sentence earns its place—usage triggers, exclusions, token mechanics, rate limit, and cost. Despite its length, no word is wasted.

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

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

Even though there is no output schema, the description explains the key return behavior: 'Filing without an account returns a claim_token' and how to later use it to read the fix status and changes. It also covers rate limiting, quota, content guidance, and exclusion rules, making it fully complete for a feedback tool.

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

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

The schema already describes all parameters (100% coverage), so baseline is 3. The description adds extra meaning for the message parameter ('describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt') and operational semantics for claim_token (how to use the returned token to read status), elevating it above 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 opens with a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' This clearly distinguishes the tool from siblings like ask_pipeworx or discover_tools, which are query/research tools, by focusing on sending feedback about the Pipeworx toolset itself.

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 conditions are given: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also provides a clear exclusion when the tool belongs to a different MCP server, directing users to file elsewhere, and advises on what to include ('describe in terms of Pipeworx tools/packs').

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 valuable context: self-aggregating, derived from CF analytics-engine, no PII, cached 5min-1h. No contradictions.

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

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

Description is concise and well-structured: first sentence states core functionality, then bullets use cases, then technical notes. Every sentence adds value without repetition.

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

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

Given annotations and rich schema, the description is complete. No output schema, but return values (top tools, packs, volume) are clearly implied. Caching behavior is useful additional detail.

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

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

Only one parameter (window) with enum and description in schema. Description adds clarifying context about shorter vs longer windows, which provides additional meaning beyond the schema.

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

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

Description clearly states the tool returns top tools, top packs, and total call volume over recent windows. It distinguishes itself from sibling tools like discover_tools or ai_visibility_check by focusing on trending usage data.

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

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

Explicitly lists three use cases: discovering hot data sources, confirming canonical tool, and checking alignment. Notes that shorter windows surface hotness while longer show steady-state demand. Could be improved by mentioning 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?

Discloses threshold (3pp), similarity filter (0.30 Jaccard), partition filter (placeholder >20%), fill check behavior, and realizable edge condition. Annotations already declare read-only, idempotent, non-destructive, so 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?

Front-loaded with purpose and modes, but the lengthy detail (Jaccard threshold, partition filter, fill check) could be slightly trimmed without losing value. Still, every sentence contributes.

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

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

No output schema, but description explains response fields (opportunities[], partition_check, fill_check) and edge cases thoroughly.

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

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

Schema covers both parameters with basic descriptions; the tool's description adds rich context: examples, internal mechanics, and use-case recommendations, far exceeding 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?

Clearly states it finds arbitrage on Polymarket via monotonicity violations and partition-sum checks. Differentiates from sibling tools like polymarket_fill_risk.

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

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

Explicitly tells when to use each mode (event vs. topic), when to call with no args for trending scan, 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?

Beyond annotations (readOnlyHint, etc.), the description details caching (1h), computation logic for each model family, response structure, edge cases like Fed bets, and effect of knobs. No contradictions with annotations.

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

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

The description is very detailed but excessively long for an AI agent. While well-structured with sections, it could be more concise by summarizing core behavior and deferring details to schema.

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

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

Given the tool's complexity (9 params, multiple segments, diagnostics), the description covers return values, caching, and empty-segment diagnostics comprehensively. No output schema, so description compensates well.

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

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

All 9 parameters have descriptions in the schema (100% coverage), and the description adds extra context like default values, meaningful explanations (e.g., partition arbs always return kelly_fraction_half=0), and practical usage tips.

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

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

The description clearly states the tool scans Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. It distinguishes itself from siblings like polymarket_arbitrage by focusing on disagreement-based edges and providing a specific use case.

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

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

The description gives strong usage guidance with 'what should I bet on today' and explains when to use different segments. It notes when not to rely on certain signals (e.g., Fed bets) but does not directly compare 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 safe, read-only behavior. The description adds significant behavioral detail: response structure (tracked, expired, snapshot_dates), field semantics (trend classification, decay calculation from daily closes), and data source constraints. 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 well-structured with front-loaded purpose, clear response format explanation, and a limitations section. It is fairly dense but every sentence adds value; could be slightly more concise 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?

Despite lacking an output schema, the description thoroughly documents all response fields (tracked with time-series, trend, decay; expired with lifespan_days; snapshot_dates) and explains data caveats (TTL, snapshot gaps, decay method). The agent has sufficient information to use and interpret the tool correctly.

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

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

Schema coverage is 100% and the description largely repeats schema info (defaults, ranges, allowed values). It adds minimal extra meaning beyond what the schema already provides, meeting the baseline but not exceeding it.

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

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

The description clearly states the tool's purpose: telemetry on edge persistence and decay using daily snapshots. It distinguishes itself from sibling tools like polymarket_edges by focusing on historical trend analysis, not just current edges.

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

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

The description explains when to use the tool (to check edge age and decay) and provides context on data limitations (60-day TTL, snapshot gaps). It implicitly guides the agent away from using it for real-time edge data, but does not explicitly list alternatives or exclusions.

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

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

Beyond annotations (readOnly, idempotent, etc.), the description explains that the tool walks the CLOB ladder, calculates fills, and returns verdicts like 'clean/degraded/cannot_fill'. It details basket mode risks, such as stranded directional positions, which adds significant behavioral context.

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

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

The description is front-loaded with a summary sentence and then expands into details. While lengthy, each sentence serves a purpose—explaining modes, parameters, return fields, and usage warnings. No redundancy, but could be slightly more compact for very rapid scanning.

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

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

Given the tool's complexity (two modes, no output schema), the description thoroughly lists return fields (top_of_book, vwap_fill_price, slippage_pp, capture_ratio, profit_usd, thin_legs, etc.) and explains the verdict system. It completely covers the expected outputs and edge-case behaviors.

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

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

Schema coverage is 100%, but the description adds value by explaining parameter interactions (e.g., side default differs by mode, size_usd interpretation varies). It clarifies the dual use of market/event parameters and the auto-detection for basket side.

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 checks 'realizable-vs-theoretical edge' against live order book depth. It distinguishes between two modes (single-market and basket/partition) and explicitly contrasts with sibling tools like polymarket_arbitrage and polymarket_edges, indicating it is a pre-trade verification tool.

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

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

The description explicitly states when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It warns about risks of partial basket fills and unhedged directional positions, providing clear guidance on usage 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?

Beyond the readOnly/idempotent annotations, the description openly discloses major behavioral caveats: pairs are matched by keyword overlap rather than a shared resolution source, Kalshi fees are not modeled so spreads are gross, temporal_alignment null means unknown rather than aligned, unclassified legs are never paired, and safety codes can be non-empty even when pairs exist. This is far more disclosure than typical tools 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 long and dense, but it is well-organized around labeled sections like TWO MODES, RESPONSE, SAFETY FIELDS, and Codes, and it front-loads the core purpose. Some redundancy exists around temporal mismatch flags and alignment semantics, making it slightly longer than strictly necessary while still earning its place overall.

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

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

There is no output schema, so the description takes on the full burden of explaining the response contract. It covers top_spreads_pp, compatibility codes, per-entry flags, skipped_unclassified, low_confidence_pairs, temporal_alignment, fees_note, and skipped counters. For a complex cross-venue tool, this is unusually complete.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds genuine semantic value by defining the two mutually-exclusive modes, the override behavior of explicit parameters over topic-mapped ones, and the fact that both modes run the identical matcher. The exhaustive topic list is already in the schema, so it does not reach 5.

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

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

The opening sentence is explicit: "Cross-venue spread between Kalshi and Polymarket for the same resolving question." It identifies a specific verb, resources, and scope, and the two modes clarify exactly what can be requested. This clearly distinguishes it from single-venue siblings like polymarket_edges and polymarket_arbitrage.

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

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

The description gives clear mode-selection guidance: topic shortcuts vs. explicit kalshi_event_ticker/polymarket_event_slug, and notes that both modes run the same matcher. It also warns that "most pre-mapped topics return compatibility_warning today; pre-mapped ≠ tradeable." It stops short of explicitly naming sibling alternatives or when-not-to-use conditions, so it does not earn 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 provide safety hints. Description adds scoping detail (anonymous IP, BYO key hash, account ID), which is beyond annotations. No contradictions.

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

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

Three concise sentences front-loading purpose, then usage, then scope. No wasted words.

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

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

For a simple tool with one optional param and no output schema, the description covers purpose, usage, scoping, and sibling pairing completely.

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 100%. Description adds meaning: omitting key lists all keys, and gives concrete use-case examples (ticker, address, notes).

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+resource: 'Retrieve a value' or 'list all saved keys'. 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?

States when to use: look up stored context without re-deriving. No explicit exclusions, 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?

Describes side effects of mark_read parameter (flagging events as read), which contradicts the readOnlyHint annotation. Adds critical behavioral context about state modification and that it is idempotent for read operations but not fully read-only.

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

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

Three sentences effectively cover main action, return fields, filtering, and an alternative access method. Could be slightly more structured (e.g., bullet points) but remains clear and efficient.

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

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

Despite no output schema, description explains return fields (source, citation_uri, raw payload) and covers all parameters including state management (mark_read/unread_only). Includes practical polling advice and alternative endpoint for scripts.

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

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

Adds meaning beyond schema descriptions: explains type filters by subscription type, since as ISO timestamp, mark_read to avoid duplicates, unread_only for fresh events, and limit as max. Enhances understanding of each parameter's purpose.

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

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

Clearly states it pulls fired events from subscription feed, specifies return fields (source, citation_uri, raw payload), and mentions filtering by type and ISO timestamp. Distinguishes from sibling tools like list_subscriptions.

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

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

Provides usage context: polls work fine and mentions alternative API endpoint for scripts/dashboards. Implicitly suggests when to use the direct API vs this tool, but does not explicitly list when not to use or compare to other similar 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?

The description goes beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint false) by detailing the fan-out to multiple sources, fallback logic, USPTO patent note, and return structure (grouped changes, total count, citation URIs). No contradiction with annotations.

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

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

The description is well-structured with query examples at the start and technical details following. Every sentence adds value, though it is somewhat lengthy. Slight room for conciseness but overall effective.

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

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

Given the tool's complexity (multiple data sources, fallback, parameter flexibility, and no output schema), the description is highly complete. It explains all sources, fallback logic, return format, and parameter usage. The explicit mention of return structure 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 description coverage is 100%, so baseline is 3. The description adds value by explaining the 'since' parameter's dual format (ISO date and relative shorthand with examples), clarifying 'type' is limited to company, and specifying 'value' can be ticker or CIK. This extra context raises the score to 4.

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

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

The description clearly states the tool provides a change feed combining SEC filings, news, and patents for a company. It gives example queries like 'What's new with X' and distinguishes itself from the sibling tool 'entity_profile', which provides a static profile regardless of window.

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

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

The description explicitly says when to use this tool (for recent changes over a window) and when not to (use entity_profile for static profile). It provides guidance on the 'since' parameter format (ISO date or relative shorthand) and explains fallback behavior between GDELT and GNews.

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=false, idempotentHint=true, destructiveHint=false. The description adds valuable context beyond annotations: key-value scoping by identifier, persistence differences (authenticated vs anonymous), and the fact that it's a write operation. No contradictions.

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

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

The description is three sentences, each serving a distinct purpose: purpose, usage guidance, behavioral context. Every sentence is informative, no fluff, and the most critical info is front-loaded.

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

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

Given that there is no output schema, the description adequately explains the storage mechanism, scoping, and retrieval pairing. Combined with rich annotations and clear parameter schema, the tool's behavior is fully specified for effective agent use.

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

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

Schema coverage is 100% with descriptions for both 'key' and 'value'. The description adds naming convention examples for keys and specifies that values can be any text, which slightly enhances meaning beyond the schema. A higher score would require more detailed format specifications.

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

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

The description uses a specific verb 'Save data the agent will need to reuse later' and clearly indicates the resource (key-value memory). It distinguishes from sibling tools 'recall' and 'forget', making the purpose unambiguous.

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

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

The description explicitly states when to use: 'when you discover something worth carrying forward' and provides examples. It also mentions pairing with 'recall' and 'forget' for completeness and gives storage scoping details, leaving no ambiguity about alternatives.

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

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

The description goes far beyond the readOnly/idempotent annotations by disclosing internal cascading lookups, graceful degradation when GLEIF/OpenFIGI are unavailable, unambiguous behavior returning figi_candidates, explicit unresolved identifiers, and the ISIN-to-LEI mapping behavior. This is rich, non-redundant behavioral context.

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

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

The description is long and dense, but the complexity of the tool justifies much of the detail. It is front-loaded with examples and a usage directive, then organized by entity type. Some parentheticals are heavy and could be tightened, but every major section contributes useful call-time knowledge.

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 tells the agent what identifiers come back (CIK, ticker, company_name, LEI, FIGI, RxCUI, ingredient, brand), how ambiguity is handled, what happens on enrichment failure, and what input forms are accepted. This is sufficient for an agent to select and invoke the tool correctly.

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

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

Input schema coverage is 100%, so the baseline is a 3, but the description adds meaningful semantics: it documents ISIN as an input format, explains that drug accepts brand or generic names, and warns that bond resolution requires the exact issuer name rather than the full noun phrase. This elevates it above 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 opens with concrete user-intent examples and then states the core job: resolving a spoken name to canonical/official identifiers that other tools require as input. It clearly distinguishes itself from sibling lookups by framing itself as the identity-resolution entry point and enumerating supported entity types.

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 explicit directive "Use FIRST whenever you have a name but need an ID" gives clear when-to-use guidance, and the supported-type breakdown further clarifies applicability. It does not name specific sibling tools or state exclusion conditions, so it falls slightly short of fully explicit alternatives guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. Description adds behavior: probes each entity, ranks by score, returns metrics (score, confidence, signal density). No contradictions.

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

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

Three sentences, front-loaded with purpose, no wasted words. Efficiently covers usage, mechanism, and output.

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 explains return structure (ranked list with score, confidence, signal density). Parameters are fully covered by schema. Context is complete for this level of 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%. Description adds value by clarifying that the first entity is the 'subject' for narrative, beyond what schema's descriptions provide.

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, probes each with ai_visibility_check, and ranks them. It distinguishes from siblings like ai_visibility_check (single entity) and compare_entities (general comparison).

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

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

Explicitly states use case: 'competitive AI-marketing audits' and provides an example question. Lacks explicit when-not-to-use or direct alternatives, but context hints at distinction from single-entity probe.

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

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

Annotations already indicate readOnly, idempotent, non-destructive. Description adds crucial behavioral details: partial failures degrade gracefully, bundlephobia first measurement can take 5-30s, and sources_failed will list if it times out. No contradiction with annotations.

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

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

The description is informative but slightly lengthy. It is well-structured: front-loads purpose, then usage, then return summary, then limitations. Every sentence adds value, though some detail could be more concise.

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

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

Given no output schema, the description fully details the return structure: summary block with specific fields, per-advisory detail, links, and alternative versions. Parameter coverage is complete. The description leaves no ambiguity about what the tool returns.

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

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

Schema coverage is 100% with clear descriptions for both parameters. Description adds value by explaining the default behavior for version (latest) and accepting scoped packages (e.g., '@types/node'), which goes beyond the schema.

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

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

The description clearly states the tool's purpose: a composite check for npm packages using deps.dev and bundlephobia, answering safety, popularity, and size questions. It distinguishes from siblings by noting it covers multiple checks in one call, while other tools like deps.dev:version handle other ecosystems.

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

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

Explicitly states when to use: when agent asks about safety, popularity, size, or cost of adding an npm package. Also specifies when not to use: only npm ecosystem in v1; other ecosystems (PyPI, Maven, etc.) fall under 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 declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds significant behavioral detail: embedding model (BGE-base-en), window size (500-char overlapping), character cap (200K with truncation flag), and return format (passages with offsets and similarity scores). No contradictions.

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

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

The description is well-structured: opens with bolded core action, then usage guidance, technical details, and pairing. Every sentence adds value without redundancy.

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

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

Despite lacking an output schema, the description explains what is returned (passages with offsets and scores), covers limits and truncation, and suggests a workflow with ask_pipeworx_grounded. Complete for an AI 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%, so description adds value beyond schema. It explains text as the document to search, provides query examples (e.g., 'supply-chain risk'), and notes the max chars and default limit. This adds practical guidance.

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

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

The description clearly states it performs semantic search inside a fetched record, with concrete examples (SEC 10-K body, article). It distinguishes itself from siblings like ask_pipeworx_grounded by noting it saves context and provides offsets for verification.

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

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

Explicitly states when to use: 'when the record is too big to cram into the prompt'. Mentions alternative sibling ask_pipeworx_grounded. Provides clear context for choosing this tool over others.

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 non-obvious traits: account requirement, type-specific parameters, delivery channels with limitations (SMS cap, webhook auto-disable, signing). No contradiction with annotations.

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

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

Well-structured, front-loaded with purpose, then details. Every sentence adds value, though slightly verbose with repeated examples. 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?

Given complexity (multiple types, nested params, delivery) and no output schema, description covers all critical aspects: input, behavior, constraints, and return value.

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 significant value with concrete examples for each subscription type's params and delivery format, 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?

States clearly 'Create a proactive monitoring subscription' and distinguishes from siblings like list_subscriptions and unsubscribe by focusing on creation. Returns subscription id.

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

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

Provides prerequisites (Pipeworx OAuth account), supported types with examples, and delivery options. Lacks explicit contrast with alternative tools, 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?

Annotations already signal readOnly, openWorld, idempotent, non-destructive. The description adds that the tool returns example questions and does not perform mutations, and indicates it can be called without arguments.

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

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

The description is detailed but somewhat lengthy; however, each sentence adds value. It starts with example queries and then explains output and usage, making it easy to scan.

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

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

For a simple tool with one optional parameter and no output schema, the description covers purpose, usage, parameter behavior, and return value shape completely.

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 parameter description in schema already explains the topic field. The description's mention of valid topics ('finance', 'pharma', etc.) aligns with the schema but adds no new information beyond the schema's own description.

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

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

The description clearly states the tool returns category-bucketed example questions with tool and argument shapes, and positions it as the onboarding entry point. It distinguishes from siblings like ask_pipeworx and entity_profile.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. Also guides on argument usage: 'Call with no arguments for the full spread, or pass topic to focus'.

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?

Extra detail beyond annotations: row is deactivated, not deleted, preserving history via recent_alerts. 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?

Two efficient sentences, essential info front-loaded.

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

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

Covers purpose, constraint, behavior (deactivate), and historical context. Complete for tool 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 covers param fully; description adds source ('returned by subscribe') for context.

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 action 'Cancel' and resource 'subscription by id'. Distinguishes from sibling 'subscribe' as its inverse.

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 ownership enforcement (only own subscriptions). Missing explicit when-not-to-use but strongly implied.

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

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

Annotations already declare read-only/idempotent/open-world, but the description adds substantial behavioral context: the two processing paths (structured vs grounded), the precise meaning of 'could_not_verify' as a failed check with no evidential value, the meaning of 'unsupported', and the inclusion of citations and reasoning. This goes far beyond the annotations and prevents misuse.

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 dense with actionable information. The opening trigger phrases and 'Use whenever' are immediately useful, and the rest covers return types and error semantics. The closing note about replacing sequential calls is a minor efficiency hint, not padding. No part feels redundant.

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 enumerates all six verdicts and carefully explains the ambiguous ones (could_not_verify and unsupported). It covers both input parameters, routing logic, and output structure (verdict, value, citation, reasoning). This gives an agent all the context needed to invoke and interpret the tool correctly.

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

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

Schema coverage is 100% (both parameters are described). The description adds extra context by explaining the percent-delta math for financial claims and the default tolerance cap of 5%, complementing the schema's description of tolerance_pct. It doesn't fully explain the 'claim' format beyond examples, but the schema already covers it well.

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 natural-language trigger phrases and explicitly states 'natural-language claim verification against authoritative sources.' It clearly distinguishes between company-financial claims (via SEC EDGAR/XBRL) and other factual claims (grounded pipeline), and enumerates the verdict categories. This makes the tool's purpose unmistakable and sets it apart from siblings like deep_research or entity_profile.

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

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

The description says 'Use whenever the agent needs to check whether something a user said is factually correct' and provides concrete triggers. It also gives a routing rule for claim types. However, it does not explicitly name alternative tools or state when *not* to use this tool, so it lacks the explicit exclusions needed for a 5.

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