Public Suffix List

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

Annotations (readOnlyHint, idempotentHint, destructiveHint false) already indicate a safe read operation. The description adds valuable behavioral context: it mentions the default free model, the need for a BYO API key for Anthropic (with direct payment), the per-model return structure including score, confidence, signals, and raw_response, and a combined view. No contradictions.

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

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

The description is concise (4 sentences), front-loaded with the primary purpose and output format. Every sentence adds value: purpose, model details, return structure, and use cases. No wasted words.

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

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

Given moderate complexity (4 params, no output schema), the description covers purpose, return structure, model options, and usage scenarios. It lacks error handling details (e.g., invalid API key) but the annotations cover safety and idempotency. Slightly incomplete but still strong.

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 meaning beyond the schema by explaining the 'context' parameter's role in disambiguation, the free default for 'models', and the 'apiKey' being optional and passed directly to Anthropic. This extra context justifies a 4.

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

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

The description uses a specific verb (probe, score) and resource (LLMs, visibility), clearly stating it scores visibility per model. It distinguishes from siblings like scan_competitor_ai_presence by focusing on probing multiple LLMs for a quantified visibility score.

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

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

The description explicitly lists use cases (Al-marketing audits, pre-launch brand checks, competitive monitoring) and explains model options and API key requirements. However, it does not contrast with sibling tools or state when not to use this tool versus alternatives.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. Description adds valuable context: it routes questions to the appropriate tool, fills arguments, and returns structured answers with citations. No contradictions. A small gap is not mentioning response format details, but output schema is absent.

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 front-loads the key message 'PREFER OVER WEB SEARCH' and then provides comprehensive guidance. Though lengthy, every sentence adds value—usage guidelines, examples, alternatives. Could be slightly tighter but is well-structured and informative.

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

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

Given the tool's complexity (many sources, many siblings), the description is thorough: explains the tool's role as a router, gives usage scenarios, lists example queries, and explicitly compares to siblings. It fully compensates for the lack of output schema by describing the return of structured answers with citations.

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

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

Schema coverage is 100% with 6 parameters all described (one required 'question' with aliases). Description simply says 'Your question or request in natural language' and shows examples in the schema, adding no meaning beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description clearly states the tool handles factual questions about current/historical data from 4,482 tools across 1129 sources, listing specific domains like SEC, FDA, FRED, etc. It provides concrete examples and distinguishes from siblings by positioning as the default entry point.

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 'PREFER OVER WEB SEARCH' and gives detailed guidance on when to use this tool vs. alternatives: ask_pipeworx_grounded for hallucination-resistant answers, deep_research for broad questions, and notes that breaking news is also covered. Examples clarify the intended use cases.

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

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

Adds significant context beyond annotations: describes routing, answer extraction, return structure with evidence/refusal reasons, and extra LLM call cost. 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?

Well-structured with clear sections for purpose, behavior, usage, and cost tradeoff. Slightly verbose but every sentence adds value.

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

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

Despite lack of output schema, description fully specifies return structure (answer, evidence, confidence, source, fetched_at, refusal_reason) and error cases. Sufficient for agent understanding.

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

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

Schema coverage is 100% with all parameters as aliases for 'question'. The description doesn't add extra semantics beyond explaining aliases, which is already clear in schema.

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

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

Clearly states the tool is a 'hallucination-resistant answer mode for high-stakes reads', explains it extracts answers only from tool results, and distinguishes from sibling 'ask_pipeworx'.

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

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

Explicitly states when to use (high-stakes, quoted/cited answers) and when not ('prefer ask_pipeworx for casual lookups'), with concrete examples (financial, legal, medical).

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 readOnly, openWorld, idempotent, non-destructive. The description adds extensive behavioral details: safety mechanisms (low-confidence short-circuit, closed market handling, wide spread warnings), resolver contract with match confidence, and resolution-rule risk analysis. 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 lengthy but well-organized, starting with the core purpose, then classifiers, fan-out examples, response shapes, and edge cases. Each section adds necessary detail without redundancy. While dense, it remains structured and informative, fitting the tool's complexity.

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

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

Given three parameters and no output schema, the description is remarkably complete. It covers response structure (market, analysis, evidence), resolver contract (confidence, alternatives), parent event extraction, news fields, safety behaviors, and resolution-rule risk. All likely agent questions are addressed.

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

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

Schema coverage is 100% with descriptions for each parameter. The description adds value by explaining the market parameter can be a slug, URL, or question text; providing examples in the schema; and detailing the depth and include_raw options. The fan-out examples indirectly clarify parameter usage.

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

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

The description clearly states the tool's function: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the inputs (market slug, URL, question text) and distinguishes itself from sibling tools like polymarket_edges and polymarket_arbitrage by focusing on data gathering for individual bets.

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

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

The description explicitly states when to use the tool: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also provides detailed fan-out examples for various bet types. However, it does not explicitly mention when not to use it or list alternative tools, though the context from siblings makes this 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 indicate readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. Description adds details: for company type it pulls revenue, net income, cash, debt from SEC EDGAR/XBRL with proper fiscal year handling; for drug type it pulls FAERS adverse events, FDA approvals, trial counts. It also mentions sorted results and 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?

Description is comprehensive but somewhat lengthy. It front-loads common query patterns and includes important details like data sources and edge cases. While very informative, it could be slightly more concise with bullet points, but the content earns its place.

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

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

No output schema exists, but description explains what is returned: paired data and pipeworx:// citation URIs per entity. For a tool handling comparisons of 2-5 entities with two types, the description covers all essential aspects: use cases, parameters, data sources, result ordering, and special handling (off-calendar fiscal years). It is fully self-contained.

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

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

Schema coverage is 100%, but description adds significant value beyond schema: explains that 'type=company' pulls financial data from SEC EDGAR/XBRL and handles off-calendar fiscal years, while 'type=drug' pulls adverse-event counts, FDA approval counts, and trial counts. For 'values', it provides concrete examples like tickers or drug names. This extra context exceeds baseline expectations.

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 performs side-by-side comparison of 2-5 companies or drugs in one call. It lists example queries like 'compare X and Y' and 'head to head'. It distinguishes from sibling tools like entity_profile which does single entity lookups.

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

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

Description explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It provides clear context on when to use (comparison scenarios) and what types of entities are supported (company or drug).

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, etc. The description adds crucial behavioral context: it is not open-web search, uses parallel tool routing, never invents answers, returns gaps[] for unanswered facets, and estimates 15-60s latency. 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 relatively long but well-structured: it starts with the critical account requirement, then explains the core functionality, and ends with comparisons to sibling tools. Every sentence adds value, though some minor redundancy could be trimmed. It is front-loaded with the most important 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?

Despite lacking an output schema, the description fully explains the return format (findings packet with evidence, confidence, source, citation, gaps[]). It covers expected latency, account requirements, alternative tools, and the tool's limitations (e.g., not for breaking news). This is comprehensive for a complex research 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?

Both parameters are fully described in the schema (100% coverage). The description adds meaningful context: the 'question' parameter is described as 'broad/multi-part is fine', and the 'depth' enum values are explained with concrete facet counts (quick=3, standard=5, thorough=8) and default behavior.

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

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

The description clearly states the tool performs 'grounded multi-source research' across structured data sources, decomposes questions into facets, and returns a findings packet. It explicitly distinguishes from siblings like ask_pipeworx by contrasting use cases (broad/multi-part vs single lookup).

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

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

The description provides explicit when-to-use and when-not-to-use guidance: 'For a single lookup use ask_pipeworx' and 'for BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. It also notes account requirements and paid plans for deeper depth.

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 confirm readOnly and idempotent. Description adds valuable context: returns top-N relevant tools with full input schemas and curated examples, ready to call directly without a second lookup. 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 somewhat long but efficiently front-loaded with purpose and usage. Every sentence adds value. Could be slightly tighter but overall well-structured.

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

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

Given 6 parameters (1 required), no output schema, and many siblings, the description adequately covers what the tool does, how to call it, and what to expect (top-N results with schemas). Missing detail on failure scenarios but acceptable for a discovery tool.

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

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

Schema coverage is 100% with all parameters described. The description goes beyond schema by explaining that 'query' accepts multiple aliases and provides natural language examples, adding practical guidance for formulation.

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

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

The description clearly states the tool finds tools by describing a task or data, and lists many specific domains (SEC filings, FDA drugs, etc.). It distinguishes itself from sibling tools by emphasizing it is the first call to explore available options.

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: browsing, searching, discovering tools. Also provides a strong usage hint: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This clearly differentiates from specific 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, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds significant behavioral context: it lists the exact outputs (CIK, company name, filings, fundamentals, patents, news, LEI), mentions that the patents source (USPTO PatentsView API) may soft-fail, and states that the call is parallel. No contradiction with annotations.

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

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

The description is front-loaded with example queries and is information-dense. While it is somewhat long, every sentence adds value. It could be slightly tightened (e.g., moving the patent soft-fail detail to a note), but overall it is efficient and well-structured.

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

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

Despite lacking an output schema, the description provides a thorough account of what the tool returns: CIK, company name, up to 5 recent filings with URIs, latest 10-K fundamentals, patents (with deprecation note), recent news, and LEI. It also mentions ordering (sorted by period_end DESC). This is sufficiently complete for a complex tool.

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

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

Schema coverage is 100% with both parameters described. The description adds meaning beyond the schema: it clarifies that 'value' can be a ticker like 'AAPL' or a zero-padded CIK like '0000320193', and reinforces that names are not supported. It also explains that 'type' only supports 'company' currently, with other types coming soon.

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: produce a full cross-source profile for a US public company. It provides multiple example queries ('Tell me about X', 'research Acme', etc.) and lists all data sources and outputs. It also distinguishes from sibling tools by advising to use resolve_entity if only a name is given and by preferring this tool over chaining individual lookups.

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

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

The description explicitly tells when to use this tool: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also gives a clear when-not-to-use: names are not supported, so use resolve_entity first if only a name is available. This provides clear context and alternatives.

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

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

Description reinforces the destructive nature indicated by annotations (destructiveHint=true) and adds context about clearing sensitive data. No contradictions.

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

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

Two sentences, front-loaded with the action, no extraneous words. Highly efficient.

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

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

For a simple single-parameter tool with no output schema, the description adequately covers purpose, usage, and pairing. Could mention response or permanence but not necessary.

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

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

Schema covers 100% of parameters with description 'Memory key to delete'. Description only echoes 'by key' without adding new semantics.

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

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

The description clearly states 'Delete a previously stored memory by key', specifying the verb (delete), resource (memory), and method (by key). It distinguishes from siblings like 'remember' and 'recall'.

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

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

Explicitly provides when-to-use scenarios: 'stale context, task done, clear sensitive data'. Mentions pairing with related tools, though it doesn't explicitly list when not to use.

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

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

Annotations already indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds that it fetches the page, extracts title/description/key links, and outputs standard llms.txt markdown, which goes beyond annotations.

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

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

The description is concise with a clear first sentence defining the core action, followed by a useful list of use cases. It is well-structured and front-loaded.

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

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

Given the tool's simplicity (2 params, no output schema), the description sufficiently covers behavior, output format, and use cases. It is complete enough for an agent to understand the tool's purpose and output.

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

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

Schema coverage is 100% with both parameters described. The description mentions fetching the page and extracting links, which aligns with 'url' and 'max_links', but adds no new semantics beyond the schema.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, specifying the verb 'generate' and resource 'llms.txt file'. It distinguishes from siblings by focusing on this unique functionality.

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

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

The description provides explicit use cases (getting a client's site indexed, drafting for own project, auditing competitor) but does not explicitly state when not to use or compare with alternatives.

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

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

Annotations already provide readOnlyHint, idempotentHint, etc. Description adds return field details and default behavior (active only). 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 sentences: first states purpose and return fields, second gives usage guidance. No wasted words.

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

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

No output schema, but description enumerates return fields. Lacks mention of pagination or limits, but acceptable for simple list tool with one optional param.

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 describes include_inactive. Description only indirectly references it (active subscriptions). No additional semantic value beyond schema.

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

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

Description clearly states verb 'list' and resource 'subscriptions' with scope 'caller's active' and lists return fields. Distinguishes from siblings like subscribe/unsubscribe by providing usage context.

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 (review before adding more, find id to cancel), implying alternatives. Could be more explicit about when not to use, but the context is sufficient.

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

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

The description adds minimal behavioral context beyond the annotations. Annotations already indicate read-only, idempotent, non-destructive, and open-world semantics. The description merely restates the output fields without disclosing additional traits like response structure or underlying dependencies.

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 extremely concise (three words) and front-loaded. Every word provides value; there is no redundancy or unnecessary information.

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

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

Given the tool has no parameters and an output schema exists, the description is minimally complete. However, it could benefit from a brief explanation of the tool's purpose (e.g., 'Status check for system metadata'). For a simple tool, it is adequate.

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

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

There are no parameters, so the description is not required to add parameter details. Baseline score is 4, and the description is adequate for a parameterless tool.

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 'Last refresh + rule count.' clearly states that the tool returns a last refresh timestamp and a rule count. It is specific about the output, though it could be more explicit about what 'last refresh' refers to (e.g., data freshness). No sibling tools with similar purpose, so differentiation is not needed.

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?

No guidance on when to use this tool versus alternatives. Sibling tools are diverse and not directly related, but the description does not provide any context about typical usage scenarios or prerequisites.

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

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

Annotations indicate read-only, open-world, idempotent, non-destructive behavior, so the description adds value by specifying the exact output components (subdomain, registrable_domain, public_suffix). 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?

Single sentence, front-loaded with the action, 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 parameter and an output schema, the description sufficiently covers the behavior and output. Annotations provide additional behavioral 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?

The sole parameter 'domain' is explained by the description 'Split a domain', but no additional semantic details beyond the schema name. Schema coverage is 0%, but the description and examples provide sufficient 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?

Description clearly states the verb 'split' and the resource 'domain', and lists the output components: subdomain, registrable_domain, public_suffix. This distinguishes it from sibling tools like 'public_suffix' or 'registrable_domain'.

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

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

The description implies the tool is used for decomposing a domain into parts, but does not explicitly state when to use this tool versus alternatives like 'public_suffix' or 'registrable_domain'.

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

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

The description discloses rate limits (5 per identifier per day), free usage, and quota-free nature. These details go beyond the annotations, which only indicate non-readonly, non-idempotent, etc. 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, starting with purpose, then usage guidelines, then additional notes (rate limits, quota). While slightly verbose, every sentence adds important 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 feedback tool with 3 parameters (2 required) and no output schema, the description covers input expectations, behavioral constraints, and operational details, making it complete.

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

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

Schema description coverage is 100%, but the description adds value by advising on message specifics (which tool, error, missing data) and length (1-2 sentences, 2000 chars). This helps the agent craft better inputs.

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

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

The description clearly states the tool's purpose: to send feedback about bugs, features/data gaps, or praise. It distinguishes itself from sibling tools by being the only feedback mechanism among a set of research and visibility tools.

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

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

The description explicitly lists when to use (bug, feature/data_gap, praise) and what not to do (don't paste end-user prompt). It also mentions rate limits and quota, providing comprehensive usage guidance.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive behavior. The description adds valuable context: data source (CF analytics-engine), no PII, cached 5min-1h, and output shape (top tools/packs, call volume). 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 concise (four sentences) and front-loaded with the core definition, then use cases, then data source/caching details. 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 no output schema, the description fully explains what the tool returns (top tools, packs, call volume), how it works (self-aggregating, no PII), and caching behavior. For a simple read-only tool, this is 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% with a descriptive parameter definition. The description reinforces the window options and adds behavioral implications ('Shorter windows surface what's hot right now; longer windows show steady-state demand'), which exceeds the schema's explanation.

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

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

The description clearly states the tool returns trending calls on Pipeworx, including top tools, top packs, and total call volume over selected time windows. It uses specific verbs and resources, and distinguishes from siblings like discover_tools by focusing on current activity rather than available tools.

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

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

The description lists three concrete use cases (discovering hot data sources, confirming popular tools, assessing alignment) that guide when to use the tool. While it does not explicitly exclude alternatives, the use cases provide clear context. Slight improvement possible with 'when not to use' guidance.

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

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

Annotations provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds rich behavioral context: explains internal checks (monotonicity, partition check, Jaccard similarity threshold, placeholder filter, fill check with realizable vs theoretical edge). No contradiction with annotations.

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

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

Description is detailed but well-structured with clear sections. Front-loaded with requirement. However, could be slightly more concise given the length.

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

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

Despite no output schema, description fully explains the response structure (opportunities array with fields, fill check, etc.). Covers all behavioral aspects and references sibling tools for further actions.

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 only two parameters. Description adds substantial meaning: explains event mode vs topic mode, provides examples of valid inputs, and details how each parameter is used internally. Goes far beyond what schema provides.

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

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

Clearly states it finds arbitrage opportunities on Polymarket using monotonicity violations and partition-sum checks. Distinguishes two modes (event vs topic) with specific use cases, making it highly specific about the verb and resource.

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

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

Explicitly states requirement: 'REQUIRES one of event or topic — call with no args fails.' Recommends event for specific markets and topic for cross-event scanning. Refers to sibling tool polymarket_fill_risk for custom sizing, providing clear when-to-use guidance.

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

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

The description is highly transparent, detailing model families, edge calculations, response structure, caching policy, and filter knobs. It goes well beyond the annotations (readOnlyHint, etc.) by explaining internal logic and caveats (e.g., Fed candidates excluded, partition_overround behavior). 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 long and dense, with detailed technical explanations that could be condensed. While it is well-structured with sections (SEGMENTS, EVERY OPPORTUNITY, etc.), its verbosity reduces conciseness. Every sentence provides information, but some could be streamlined.

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

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

Given the tool's complexity and absence of an output schema, the description thoroughly explains the response structure, including segments, diagnostics, and edge data. It covers caching, filters, and edge cases (e.g., Fed bets, partition_overround corner cases). The description is complete enough for an AI agent to use effectively.

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

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

The input schema provides 100% coverage with detailed descriptions for each of the 9 parameters. The tool description adds context by explaining how parameters interact (e.g., tradeable-edge knobs, min_partition_leg_kelly usage). This adds value beyond the schema, earning a score above the baseline of 3.

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

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

The description clearly states the tool's purpose: scanning top Polymarket markets to return opportunities where Pipeworx data disagrees with market price. It uses a specific verb-resource pair and provides enough detail to distinguish from sibling tools like polymarket_arbitrage, though not explicitly.

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

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

The description provides context on when to use the tool ('what should I bet on today') and explains the three response segments. However, it does not explicitly state when not to use it or compare with alternatives, such as polymarket_arbitrage or bet_research, limiting guidance for tool selection.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds extensive behavioral details: response structure with tracked[], expired[], snapshot_dates[], field semantics (trend, decay_pp_per_day, lifespan_days), and limitations (60-day TTL, history start, decay from daily closes not intraday). 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 dense but well-structured, starting with the core question, then detailing response fields and limits. It is front-loaded with purpose. While not extremely concise, every sentence conveys necessary information.

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

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

Given no output schema, the description provides a thorough explanation of the response structure (three arrays with fields and meanings) and limitations (TTL, data recency). It covers all necessary context for an agent to understand and use the tool correctly.

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

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

Schema description coverage is 100%, but the description adds value by listing allowed values for window (24hr, 1wk, 1mo) and clarifying defaults and max for days. This enhances understanding beyond the schema's own descriptions.

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

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

The description clearly states the tool provides edge persistence and decay telemetry, answering 'how long has this edge existed and is it shrinking?'. It specifies the resource (edge snapshots) and verb (track edges over time), and distinguishes from sibling 'polymarket_edges' which likely provides 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 implies when to use: when you need historical edge persistence and decay context. It contrasts a fresh edge with a 3-week-old edge, providing usage context. However, it does not explicitly state when not to use or list alternatives, though the sibling list implies differentiation.

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

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

Beyond annotations (readOnlyHint, idempotentHint, non-destructive), the description details operational behavior: walking the ladder, returning specific fields like toB, VWAP, slippage, shares filled, and for baskets per-leg fill details, thin legs, and directional risk. 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 moderately long but well-structured with sections for single-market and basket, using bold for key terms and front-loading the purpose and requirements. Slightly dense but earns its length given complexity.

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

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

Without an output schema, the description fully explains return values for both modes, including edge cases (thin legs, forced directional risk) and practical profit/loss implications. Complete for the tool's purpose.

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

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

Schema covers 100% of parameters, but description adds mode-dependent interpretations (e.g., size_usd as spend vs target proceeds, mutual exclusivity of market/event, auto side detection for baskets). This adds significant 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 performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes between single-market and basket modes. It explicitly differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by stating when to use it as a prerequisite.

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

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

Explicitly tells the agent to use this tool before acting on polymarket_arbitrage signals or polymarket_edges trades above ~$500. It warns about risks like partial basket fills converting arb into unhedged positions, providing clear when-to-use and why.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds extensive behavioral context: explains the two modes, safety fields (compatibility_warning, temporal_alignment, skipped_cross counters), and limitations (pre-mapped ≠ tradeable). 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 clear sections (TWO MODES, RESPONSE, SAFETY FIELDS) and uses bullet points for readability. Every sentence provides valuable information, and the core purpose is front-loaded. No wasted words.

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

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

Despite having no output schema, the description comprehensively explains the response structure (spread[], top_spreads_pp, compatibility_warning, temporal_alignment, skipped counters). It covers edge cases and limitations, making the tool's behavior fully understandable given its 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?

Input schema has 100% coverage with descriptions for each parameter. The description adds meaning beyond the schema by explaining the logic of topic shortcuts and how explicit tickers override, and the relationship between parameters (topic vs. explicit pairings).

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

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

The description clearly states the tool computes cross-venue spreads between Kalshi and Polymarket for the same resolving question. It explains the two modes (topic shortcuts and explicit tickers) and details the response fields, effectively distinguishing it from sibling tools like 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 provides clear guidance on when to use each mode (topic shortcuts for common topics, explicit tickers for custom pairings) and warns that most pre-mapped topics return compatibility warnings, implying not all shortcuts yield tradeable spreads. However, it does not explicitly contrast with sibling tools for arbitrage.

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

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

Annotations declare readOnly, idempotent, openWorld, but description adds no behavioral context such as edge cases or return details.

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

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

Extremely short but insufficient; lacks structure and fails to convey necessary information.

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

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

With low complexity but high parameter opacity and no description, tool is incomplete 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?

Only parameter 'domain' has no schema description (0% coverage) and description provides no info about its format or constraints.

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 'Just the public suffix.' is vague; does not specify action (extract? return?). Not differentiating from sibling 'registrable_domain'.

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?

No guidance on when to use this tool versus alternatives like 'registrable_domain' or 'parse'.

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, destructiveHint=false, idempotentHint=true. The description adds meaningful context: scoping to identifier, listing behavior when key omitted, and pairing with remember/forget. This goes beyond what annotations provide.

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

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

The description is concise (three sentences), front-loaded with the main purpose, and every sentence adds valuable information 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?

For a simple tool with one optional parameter and no output schema, the description covers key behavior, scoping, and pairing. It lacks explanation of return format (e.g., what the value looks like vs. list of keys), which would make it fully complete.

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

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

Schema coverage is 100% with a description for the single parameter. The description adds value by explaining the effect of omitting key (list all) and what kinds of values can be stored, which enriches schema info.

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

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

The description clearly states the tool retrieves a saved value or lists keys, with specific examples (ticker, address, research notes). It distinguishes from siblings 'remember' and 'forget', and uses specific verbs (retrieve, list).

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 (look up stored context) and its scoping. It implies when to omit the key (to list all) and mentions pairing with remember/forget. However, it does not explicitly say when not to use it or list alternatives beyond siblings.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint as false. The description adds behavioral details such as the return fields (source, citation_uri, raw payload) and the effect of mark_read on future calls. It does not contradict any annotation.

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

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

The description is a single paragraph that front-loads the main purpose, then details return values, filtering, mark_read behavior, and a polling note. Every sentence adds value without repetition or fluff.

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

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

Despite lacking an output schema, the description fully explains the return structure (source, citation_uri, raw event payload). It covers key behaviors like mark_read, polling, and an alternative access method, making the tool's use clear and 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 baseline is 3. The description adds context beyond schema by explaining the effect of mark_read and that filtering by type and since is optional. This provides meaningful additional guidance for parameter usage.

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

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

The description clearly states 'Pull fired events from your subscription feed' with a specific verb and resource. It explains what is returned and mentions filtering by type and timestamp, distinguishing it from sibling tools like list_subscriptions or subscribe.

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

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

The description provides usage guidance by mentioning that polling works fine and pointing to an alternative endpoint for scripts and dashboards. It also explains the mark_read parameter's effect. However, it does not explicitly state when not to use the tool or compare directly to siblings.

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

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

The description adds significant behavioral context beyond annotations: it discloses fan-out to multiple APIs, fallback mechanics, soft-failure for USPTO, and return structure (grouped changes, total count, citation URIs). No contradictions with annotations (readOnlyHint, idempotentHint, etc.).

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

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

The description is thorough yet efficient, front-loaded with example queries. Every sentence serves a purpose, though it could be slightly more concise without losing meaning.

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

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

Given the absence of an output schema, the description adequately explains the return structure. With three required parameters and comprehensive annotations, the description covers all necessary context: sources, fallbacks, parameter formats, and sibling differentiation.

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 useful context: type only supports 'company', since accepts ISO or relative shorthand with recommended values, value can be ticker or CIK. This elevates the score slightly above baseline.

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

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

The description clearly states the tool's purpose: providing a change feed for a company aggregated from multiple sources (SEC, GDELT/GNews, USPTO) over a recent window. It includes concrete example queries ('What's new with X') and explicitly differentiates itself from the sibling tool entity_profile for static profiles.

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

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

The description provides explicit guidance on when to use this tool versus entity_profile. It also details fallback behavior (GDELT preferred, GNews on rate limit), and explains the since parameter format with recommendations ('30d' or '1m').

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

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

Annotations already provide safety and idempotency hints. The description adds no behavioral context beyond annotations (e.g., handling of invalid domains, output format). For a tool with no parameter descriptions, this is insufficient.

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?

Extremely short (one phrase), but at the expense of clarity. It is under-specified rather than concise, providing no actionable 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?

Despite having an output schema, the description fails to explain tool purpose, parameter semantics, or usage context. It is incomplete for a tool with one parameter and no param docs.

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

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

Schema has 0% parameter description coverage. Description only says 'Domain + nearest suffix', adding minimal meaning to the 'domain' parameter. It does not clarify expected format, constraints, or examples beyond the schema's examples, which are unlabeled.

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 'Domain + nearest suffix (the "site").' is vague and cryptic. It doesn't clearly state that the tool extracts the registrable domain (e.g., example.com from subdomains) nor distinguishes from the sibling tool 'public_suffix', which likely does something similar.

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?

No guidance on when to use this tool versus alternatives. With sibling 'public_suffix' present, the description provides no context for choosing between them, leaving the agent with no selection basis.

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

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

Description discloses key-value scoping by identifier, persistence for authenticated users, and 24-hour retention for anonymous sessions. These go beyond the annotations (idempotentHint true, etc.) with no contradictions.

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

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

Four sentences, front-loaded with the main verb and subject, no redundant information. Every sentence adds value.

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

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

For a simple key-value memory tool with no output schema, the description covers purpose, usage, scope, lifetime, and companion tools. Fully complete.

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

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

Schema coverage is 100% with clear descriptions for key and value. The description adds high-level context but no additional parameter-level details beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states the tool saves data for later reuse, specifies examples like ticker, address, preference, and distinguishes from sibling tools recall and forget by explicitly naming them.

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

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

It says to use when discovering something worth carrying forward, and pairs with recall and forget. It doesn't strictly state when not to use but implies it through context. Clear enough for an agent.

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

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

The description discloses that each call cascades through several lookup endpoints internally, replacing 2-3 manual lookups. It also details return values per type (e.g., ticker, CIK, RxCUI) and citation URIs. This goes beyond the annotations (readOnlyHint, idempotentHint), which are consistent and add 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 a single paragraph that front-loads with example queries. It is clear and every sentence adds value, though it is slightly lengthy. Structuring into bullet points could improve scannability, but it remains efficient.

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

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

Given no output schema, the description covers return details for both entity types and the internal cascading behavior. It fully equips the agent to use the tool correctly without needing additional information.

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

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

Schema coverage is 100%, but the description adds significant meaning: for 'type', it explains the supported types and their returns; for 'value', it specifies accepted inputs per type and mentions auto-disambiguation. This enriches the parameter understanding beyond the schema.

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

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

The description clearly states that the tool resolves user-spoken names to canonical identifiers, with examples like 'What's the ticker for...' and 'find the CIK for...'. It distinguishes itself by saying 'Use FIRST whenever you have a name but need an ID', which sets it apart from sibling tools.

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

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

The description provides clear guidance on when to use the tool ('Use FIRST whenever you have a name but need an ID') and gives concrete examples for company and drug lookups. However, it does not explicitly state when not to use it or provide alternatives, though the context implies it is the primary tool for entity resolution.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds that it probes each entity with ai_visibility_check, ranks by score, and returns a ranked list. It also explains the batch behavior and output structure. 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 two sentences plus a final line, front-loaded with the main purpose and then details. Every sentence adds value with no redundancy. Highly efficient.

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

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

The description explains the return format (ranked list with score, confidence, signal density) despite the absence of an output schema. It covers all parameters and use cases. However, it could optionally include more detail on the exact data shape, but current level is sufficient for an agent to understand what the tool does.

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 critical semantics beyond the schema: the first entity is treated as the 'subject' for narrative, models default to workers-ai unless Anthropic is specified, and context disambiguates common names. These details help the agent correctly invoke the tool.

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

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

The description uses specific verbs: 'compare', 'probe', 'ranks', 'surfaces'. It clearly states it compares AI visibility across multiple entities and provides a concrete example ('does Claude know about us as well as our competitors?'). This distinguishes it from sibling tools like ai_visibility_check (single entity) and compare_entities.

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

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

The description provides a clear use case: 'competitive AI-marketing audits' and an example query. While it doesn't explicitly contrast with sibling tools, the context makes it clear when to use this tool for multi-entity comparisons vs. single-entity checks. There's no mention of when not to use, but the purpose is well-defined.

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. Description adds partial failures graceful degradation, bundlephobia latency, and that sources_failed lists timeouts. Provides 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?

Well-structured with front-loaded purpose, then details on what, returns, limitations, and graceful degradation. Slightly long but each sentence adds value.

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

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

Given no output schema, description thoroughly explains return fields (summary block, advisories, links, alternatives), limitations (NPM only, latency), and error handling. Covers all key aspects for a composite tool.

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

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

Schema coverage 100% so baseline 3. Description adds that scoped packages are accepted and version defaults to latest, but does not elaborate beyond schema.

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

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

Clearly states it is a composite 'should I add this npm package' check combining deps.dev and bundlephobia. Distinguishes from sibling tools by focusing on npm packages and composite analysis.

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

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

Explicitly says use when agent asks about safety/popularity/size or cost of adding a package. Also clarifies NPM only in v1, pointing to deps.dev:version for other ecosystems.

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 reveals BGE-base-en embeddings, cosine similarity, 500-char windows, 200K char cap with truncation flag, and return format (offsets, scores). 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?

Concise, front-loaded single paragraph. Every sentence serves a purpose: use case, benefit, pairing, technical specs. No fluff.

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

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

Despite no output schema, the description fully explains return values (passages, offsets, scores) and technical constraints (embedding model, window size, char limit). Sufficient for an agent to invoke correctly.

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

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

Schema coverage is 100% (all parameters described), but description adds value with example queries for the query parameter and context for text ('the text you already pulled'). Extra detail justifies above baseline.

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

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

The description clearly states 'Semantic search INSIDE a fetched record' and specifies the use case of handling oversized records, distinguishing it from siblings like ask_pipeworx_grounded.

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

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

Explicitly tells when to use ('Use when the record is too big to cram into the prompt') and how it pairs with ask_pipeworx_grounded, providing clear guidance for tool selection.

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

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

Annotations provide idempotentHint=true, but the description adds critical behavioral context: authentication prerequisites, SMS rate limits, webhook signing secret (one-time return), and auto-disable after 10 failures. These go beyond annotations.

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

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

The description is dense but well-structured with bullet points and examples. It's longer than ideal but organized efficiently. Each sentence earns its place.

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

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

Given the complexity (multiple types, delivery channels, authentication) and absence of output schema, the description covers all essential aspects: authentication, type parameters, delivery options, constraints, and return value (subscription id). No gaps.

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

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

Schema coverage is 100%, but the description adds extensive meaning: detailed type-specific parameters with examples (e.g., for 'sec_8k': 'items:["5.02"]'), delivery channel formats, and validation rules. This adds significant value beyond the schema.

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

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

The statement 'Create a proactive monitoring subscription to a live-data event stream' clearly specifies the action and resource. It distinguishes from sibling tools like 'list_subscriptions' (listing) and 'unsubscribe' (cancellation), 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 authentication requirement ('Requires a Pipeworx OAuth account'), provides type-specific examples, and explains delivery channels with constraints (e.g., phone verification, SMS cap). While it doesn't explicitly say when not to use, the context is clear enough for an agent to decide.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the safety profile is clear. The description adds value by explaining the tool returns example questions with tool shapes, but does not disclose any additional behavioral traits beyond what annotations imply.

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

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

The description is informative and well-structured, listing example queries and use cases. While it is longer than necessary, every sentence adds value and it is front-loaded with the primary purpose.

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

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

Given the tool's role as an onboarding entry point, the description fully explains what it does, when to use it, and what it returns. No output schema is needed because the description clarifies the return format.

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

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

Schema description coverage is 100% for the single optional parameter. The description adds context that omitting topic gives a full spread, and passing a topic focuses the results, which goes beyond the schema's terse 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 explicitly states it is the onboarding entry point, returning category-bucketed example questions with exact tool+argument shapes. It distinguishes itself from siblings like ask_pipeworx by being the FIRST tool to use when exploring capabilities.

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 clearly says 'Use this FIRST when you do not yet know what Pipeworx can do' and mentions learning how to call meta-tools. However, it does not explicitly state when NOT to use this tool or list alternatives for specific scenarios.

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

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

Discloses key behavioral traits: ownership enforcement, deactivation (not deletion), and retention of historical events. Adds context beyond annotations, which already indicate non-destructive and idempotent. No contradictions.

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

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

Two concise sentences with no waste. Action is front-loaded, each sentence adds distinct value: action, ownership, and behavior.

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

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

For a simple tool with one parameter, no output schema, and clear annotations, the description fully covers usage, side effects, and parameter origin. No gaps.

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

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

Schema provides full coverage (100%) of the single parameter 'id'. Description adds meaningful context ('Subscription id (uuid) returned by subscribe'), linking to sibling tool and clarifying origin.

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

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

Description clearly states action ('cancel a subscription by id'), specific verb+resource, and distinguishes from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

Explicitly states ownership enforcement ('you can only cancel your own subscriptions'), indicating when to use. Provides context on deactivation vs deletion. Could be improved by explicitly stating when not to use, but sufficient.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and no destructiveness. The description adds valuable behavioral context: it uses SEC EDGAR + XBRL, returns a verdict with specific categories (confirmed, refuted, etc.), structured form, actual value with pipeworx:// citation, and percent delta. 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 moderately sized but every sentence adds value: examples, domain, return types, and efficiency gains. It front-loads the purpose with common query phrases. Minor redundancy but overall efficient.

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

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

For a tool with one parameter and no output schema, the description is thorough: it explains the domain, return values, and value proposition. It could mention error handling or edge cases, but given the simplicity, it is sufficiently complete.

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

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

Schema coverage is 100% with a description for the 'claim' parameter. The description reinforces the parameter meaning with examples like 'Apple's FY2024 revenue was $400 billion', but does not add new semantics beyond the schema. Baseline of 3 is appropriate.

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

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

The description clearly states the tool performs natural-language claim verification using phrases like 'fact check' and 'verify the claim that...'. It specifies the domain (company-financial claims for US public companies) and distinguishes itself by noting it replaces multiple sequential calls, effectively differentiating from siblings like ask_pipeworx_grounded.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and limits scope to 'v1 supports company-financial claims'. This gives clear when-to-use and implied when-not-to-use guidance, with no ambiguity.

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