Singstat Sg

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds behavioral context: it mentions the default model (Workers AI Llama-3.3-70b) and cost implications for Anthropic (BYO key, pay directly). It also outlines the return structure (per-model score, confidence, signals, raw_response + combined view).

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

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

The description is concise (4 sentences) and well-structured. It front-loads the main action ('Probe one or more LLMs') and efficiently covers key details without 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?

The tool has 4 parameters, moderate complexity, and no output schema. The description explains the return format (per-model {score, confidence, signals, raw_response} + combined view), which compensates for the missing output schema. It also covers the optional API key and model selection.

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 elaborates on each parameter (entity as 'the thing to ask about', models with supported values, _apiKey usage, context for disambiguation) but does not add critical meaning 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's function: probing LLMs for knowledge about an entity and scoring visibility (0-100) per model. It specifies the resources (business/brand/product/topic) and distinguishes from siblings like 'ask_pipeworx' and 'scan_competitor_ai_presence' by focusing on visibility scoring.

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

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

The description provides explicit use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains when to use the _apiKey for Anthropic. However, it does not contrast with similar siblings like 'scan_competitor_ai_presence' or give when-not-to-use 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?

Annotations already indicate read-only, open-world, idempotent, non-destructive. Description adds value by detailing routing to 4,482 tools across 1,129 sources, returning structured answers with citation URIs, and noting speed and tier-friendliness. 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 well-structured with front-loaded key message. It is slightly lengthy but every sentence serves a purpose. Could be trimmed slightly, but still effective.

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

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

Given complexity (many sources, sibling tools), the description covers when to use, examples, return format, performance, and tier compatibility. Completeness is high despite no output schema.

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

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

Schema coverage is 100%, with all six parameters documented. Description provides examples and context on question formulation, adding marginal value beyond schema. Baseline 3 due to high coverage, but examples and usage context raise to 4.

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

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

The description clearly states it answers factual questions by routing to authoritative sources. It distinguishes from siblings like ask_pipeworx_grounded and deep_research, and provides many specific examples.

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

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

Explicitly says 'PREFER OVER WEB SEARCH' and gives detailed guidance on when to use this tool versus grounded or deep_research. Also mentions that it already routes to live news for breaking-news queries.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds significant behavioral context: it explains the extraction process, the exact return fields (answer, evidence, confidence, source, fetched_at, refusal_reason) with explicit refusal reasons (not_in_source, no_tool_match, etc.), and the cost implication. No contradiction with annotations.

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

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

The description is well-structured and front-loaded with the core purpose. It is detailed but each sentence adds value. Slightly more compact could be possible, but it remains efficient and informative.

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

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

Given the complexity of this tool (6 parameter aliases, no output schema, high-stakes use case), the description is remarkably complete. It explains the return format, error handling, and usage context. The absence of an output schema is compensated by the explicit description of the return object. For a tool of this nature, the description covers all necessary aspects.

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 of the 6 parameter aliases. The description merely restates that aliases are accepted ('Accepts query, q, prompt, text, input as aliases'). Since the schema already provides this, the description adds little beyond baseline. No additional semantic nuance or example is given.

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: 'Hallucination-resistant answer mode for high-stakes reads.' It specifies the verb 'ask', the resource 'Pipeworx' with grounded mode, and distinguishes it from the sibling 'ask_pipeworx' by emphasizing extraction from tool results only, not synthesis.

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

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

The description explicitly states when to use this tool: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' It also provides a clear alternative: 'prefer ask_pipeworx for casual lookups' due to an extra LLM call cost. This direct comparison with its sibling is excellent 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 far exceeds the annotations by detailing resolution contracts, parent event extraction, news fallbacks, safety short-circuits (low-confidence match, market closed), wide-spread tradeability, and cancellation rule parsing. There is no contradiction with annotations (readOnly, idempotent, non-destructive).

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

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

The description is long but well-structured: starts with core purpose, then covers classifiers, fan-out examples, response shapes, and edge cases. Every sentence adds value, but it could be more concise for a tool this complex. Still, it avoids redundancy and is logically organized.

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

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

Given the tool's complexity and absence of output schema, the description comprehensively covers input formats, processing logic, response structure (market, analysis, evidence), and edge cases (low confidence, closed markets, wide spreads, cancellation rules). It also advises inspecting market_match_confidence before using analysis.

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

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

Schema coverage is 100%, and the description adds significant context: market parameter supports slug/URL/question text; depth enum explained with default; include_raw parameter detailed with response size implications. Examples and explanations enhance understanding beyond schema.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input formats (slug, URL, question text) and output (evidence packet + market-vs-model comparison), distinguishing it from sibling tools by focusing specifically on Polymarket 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 says 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It provides detailed behavior for various scenarios (low confidence, closed markets, wide spreads) but does not explicitly state when NOT to use it or compare with sibling tools.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. Description adds specific data sources (SEC EDGAR for companies, FAERS for drugs), explains sorting by primary metric, and mentions return format with citation URIs. No contradictions.

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

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

The description is dense with information. While somewhat lengthy (a paragraph), it is front-loaded with example queries and each sentence adds value. Could be slightly more concise but effective.

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

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

No output schema, but description fully explains the returned data: for companies (revenue, net income, cash, debt) and for drugs (adverse events, approvals, trials). Also mentions paired data and citation URIs. Complete for the use case.

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 provides additional meaning: explains what each 'type' enum value retrieves and gives concrete examples for 'values' (tickers/CIKs for company, drug names). 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?

Description uses specific verbs like 'compare' and 'side-by-side comparison', clearly states it operates on 2-5 companies or drugs in one parallel call, and distinguishes from sequential lookups. Example queries are provided.

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

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

Explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing clear guidance on when to use this tool. Does not discuss when not to use it, but the preference is unambiguous.

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

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

Beyond annotations, discloses account requirement, parallel execution, return format (verbatim evidence, confidence, source, citation, gaps[]), expected latency (15-60s), and that it never invents. No contradiction with annotations.

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

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

The description is comprehensive but front-loads critical info (account, alternative) and is well-structured; every sentence adds value, though it is somewhat lengthy.

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 research tool with no output schema, the description covers purpose, usage, behavior, parameters, return format, limitations, and alternatives, making it fully actionable.

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

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

Schema coverage is 100% but the description adds value by mapping depth enum values to facet counts (quick=3, standard=5, thorough=8) and specifying payment requirement for thorough, which goes beyond the schema's enum labels.

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 multi-source research across Pipeworx's structured data sources, contrasting with open-web search and explicitly distinguishing from siblings like ask_pipeworx for single lookups or current news.

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 and when-not-to-use guidance: recommends ask_pipeworx for users not signed in, for single lookups, and for breaking/news topics; also notes paid plan requirements for 'thorough' 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 already declare readOnlyHint=true and idempotentHint=true. Description adds that it returns top-N relevant tools with full schemas and examples, ready to call directly, without contradicting annotations.

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

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

Description is somewhat long but front-loaded with purpose, and every sentence adds value; could be slightly tightened but remains clear.

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 specifies return content (names, descriptions, schemas with examples) sufficiently 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 covers 100% of parameters with descriptions, and the description summarizes aliases and provides example queries, adding context beyond the schema.

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

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

The description states 'Find tools by describing the data or task' and lists specific domains, clearly distinguishing from sibling tools by advising 'Call this FIRST when you have many tools available and want to see the option set'.

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 you need to browse, search, look up, or discover what tools exist for:' and provides a list of domains, plus a clear directive to call this first to explore options.

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 significant context: it is a parallel call that fans out across multiple sources, returns specific fields (with numbers like 'up to 5' filings), and explicitly notes the patent sunset (soft-fail until reactivated). 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 with information but lacks structural elements like bullet points to improve scannability. It front-loads with example queries, which is good. Every sentence adds value, but some agents might benefit from clearer separation of return fields. Still quite concise and efficient.

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

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

Despite having no output schema, the description thoroughly explains all return components: cik, company_name, recent_filings (with URIs), fundamentals with explicit fields and sorting, patents (with sunset note), news via GDELT→GNews, and LEI. It also covers input limitations and a fallback strategy for patents, making it complete for agent use.

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

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

Schema coverage is 100% with both parameters described. The description adds extra context: 'value' can be ticker or zero-padded CIK, and explicitly states that names are not supported (reinforcing the use of resolve_entity). This goes beyond the schema's minimal 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 opens with concrete query examples ('Tell me about X', 'research Acme', etc.) that instantly convey the tool's purpose. It explicitly states 'full cross-source profile of a US public company in ONE parallel call' and distinguishes from siblings by recommending preference over chaining single-pack 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?

Explicitly states when to use: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' Also clarifies that names are not supported and directs to 'use resolve_entity first' if only a name is available. Mentions the patent sunset limitation, providing clear context for usage boundaries.

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

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

Description adds context beyond annotations: it mentions clearing sensitive data and stale context, which are behavioral insights not captured by destructiveHint or idempotentHint.

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

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

Two sentences with no wasted words. The first sentence states the action, the second provides usage context. Very concise and well-structured.

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

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

The tool is simple with one parameter. The description covers purpose and usage well. However, it does not mention return value or behavior when the key does not exist, which could be useful for an agent.

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

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

Schema coverage is 100% and the schema already describes the 'key' parameter as 'Memory key to delete'. The description does not add additional parameter semantics beyond what the schema provides.

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

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

The description clearly states the tool's action: 'Delete a previously stored memory by key.' It distinguishes from sibling tools like 'remember' and 'recall' by being the deletion operation.

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

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

Explicitly states when to use: 'when context is stale, the task is done, or you want to clear sensitive data.' Also suggests pairing with 'remember' and 'recall', providing clear guidance.

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

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

Annotations already provide readOnlyHint and idempotentHint. Description adds that it fetches page, extracts key info, and outputs markdown. No contradictions.

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

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

Three sentences, front-loaded with purpose, no wasted words.

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 two params and no output schema, the description fully covers input, process, output, and use cases. 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 has 100% coverage; description reinforces with examples and default values (max_links default 25, max 50). Adds meaning beyond schema.

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

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

Clearly states it generates a production-ready llms.txt file for any URL, with specific verb and resource. Distinguishes from siblings like scan_competitor_ai_presence.

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

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

Lists specific use cases: getting client's site indexed, drafting for own project, auditing competitor. Does not explicitly state when not to use, but context is clear.

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

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

Annotations already indicate readOnly, idempotent, and non-destructive. The description adds context about the scope ('caller's') and the optional include_inactive parameter, enhancing beyond annotations.

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

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

Two sentences: first states purpose and return fields, second gives usage guidance. No unnecessary words, 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?

For a simple read-only list tool with full schema coverage and no output schema, the description adequately covers purpose, return fields, and usage context.

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

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

Schema coverage is 100%, and the single parameter include_inactive is already described in the schema. The description adds no additional meaning beyond what the schema provides.

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

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

The description explicitly states 'List the caller's active subscriptions' with a clear verb and resource, and lists returned fields, distinguishing it from sibling tools like subscribe and unsubscribe.

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

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

It provides explicit scenarios: 'review what you're monitoring before adding more or to find an id to cancel.' While it doesn't say when not to use, the guidance is clear and context-aware.

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 only declare non-destructive and non-readOnly (all false). The description adds critical behavioral traits: rate-limited to 5 per identifier per day, free, and does not count against tool-call quota. 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 purpose in the first sentence, then usage, then constraints. Each sentence earns its place without redundancy. No filler or vague language.

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 (3 params, one enum, nested context object, no output schema), the description covers all necessary aspects: when to use, what to include, limitations, and cost. 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%, so baseline is 3. The description adds meaning by explaining each enum value for 'type' in plain language, and guides how to fill 'context' (which tool, pack, vertical). It also imposes a 2000 char limit on 'message' and advises 1-2 sentences. This exceeds 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 starts with a clear verb-resource pair ('Tell the Pipeworx team something is broken, missing, or needs to exist') and immediately enumerates specific use cases (bug, feature/data_gap, praise). This uniquely identifies the tool's purpose among 27 siblings, especially since none of the other tools serve a feedback function.

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 for each feedback type: 'when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also instructs what not to do ('don't paste the end-user's prompt') and mentions rate limits and cost, providing complete guidance.

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

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

Annotations already declare readOnlyHint, destructiveHint, idempotentHint. Description adds valuable context: data source (CF analytics-engine), no PII, caching behavior (5min-1h). No contradictions with annotations.

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

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

Description is concise with no fluff, front-loaded with main result and use cases. Each sentence adds value, covering result, use cases, data source, caching.

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 sufficiently explains return values (top tools, top packs, total call volume). Annotations cover safety. Completeness is high for a simple read-only 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% and parameter 'window' has an enum. Description adds semantic meaning: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This provides deeper guidance beyond the schema.

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

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

Description clearly states it returns top tools, top packs, and total call volume over a window, with a specific verb 'returns' and resource 'trending calls'. It distinguishes itself from sibling tools like 'discover_tools' by focusing on what other AI agents are calling, providing a unique purpose.

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

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

Three explicit use cases are given: discovering hot data sources, confirming popular tool, and seeing alignment with use case. This provides clear guidance on when to use the tool. No explicit '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?

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds extensive behavioral context: monotonicity check details, partition check threshold (3pp), Jaccard similarity threshold (0.30), placeholder filter (20%), fill check against CLOB depth, and response structure. 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 with clear sections (event mode, topic mode, semantic anchor, partition filter, response, fill check). It front-loads the requirement and uses punctuation effectively. Could potentially be slightly more concise, but given complexity, it earns a 4.

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 2 parameters and no output schema, the description thoroughly explains the response fields (opportunities[], partition_check, fill_check) and edge cases (skipped_low_similarity, placeholders_filtered). It covers all necessary context for an AI agent to understand and invoke the tool correctly.

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

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

Both parameters are described in the schema with descriptions, and the description adds examples and behavioral differences between event and topic modes. Schema coverage is 100%, so baseline is 3; the description adds significant context (e.g., event slug examples, topic seed questions, and modes of operation), justifying a 4.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks. It distinguishes between event mode and topic mode with specific examples. The verb 'Find' and resource 'arbitrage opportunities' are precise and differentiate from siblings like polymarket_edges or polymarket_fill_risk.

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

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

Explicitly states REQUIRES one of `event` or `topic`, explains when to use each mode (single-event vs cross-event), and provides an alternative: 'For custom sizing use polymarket_fill_risk.' No contradictory 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 goes far beyond annotations (readOnlyHint, idempotentHint, etc.), detailing the model families, edge calculation, Kelly fractions, slippage, caching (1h at KV level), and diagnostic info. 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 long but well-structured with sections for each model family and response. It is front-loaded with the main purpose. Some details could be condensed, but the structure earns a 4.

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

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

Given complexity (9 parameters, no output schema), the description covers all aspects: model segments, edge metrics, diagnostics, caching, and filters. It even explains why segments might be empty via diagnostics.

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

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

All 9 parameters have detailed schema descriptions (100% coverage), so the baseline is 3. The description adds some context (e.g., tradeable-edge knobs, caching) but does not significantly enhance parameter meaning beyond the schema's detailed 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 verb 'Scan', the resource 'Polymarket markets', and the purpose 'return opportunities where Pipeworx data disagrees with market price'. It distinguishes from siblings like polymarket_arbitrage by focusing on Pipeworx data disagreement.

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 usage context: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It also explains tradeable-edge knobs. However, it does not explicitly state when NOT to use this tool versus alternatives like polymarket_arbitrage or other 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint flags, so safety is clear. The description adds behavioral details: it reads snapshots, uses daily closes not intraday, computes decay on edge_pp_net magnitude, and explains data gaps. 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 fairly long but every sentence adds value: purpose, input details, output structure, limitations, and behavioral quirks. It is front-loaded with core purpose. Minor verbosity could be trimmed, but overall efficient for the 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 the complexity of tracking edges over time with snapshots, the description fully covers input, output fields, limits, and behavioral traits (gaps, TTL, decay computation). Without an output schema, the description compensates by detailing the response structure completely.

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

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

Schema description coverage is 100%. The description adds default values for days (14, max 30) and window (1wk), explains 'window' as snapshot family, and details the response structure (tracked, expired, snapshot_dates) which compensates for no output 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 provides 'Edge persistence and decay telemetry' from daily snapshots, answering specific questions about edge duration and trend. It uses specific verb+resource and distinguishes from sibling tools like polymarket_edges.

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

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

The description explains when to use the tool ('how long has this edge existed and is it shrinking?') and contrasts with a fresh vs old edge concept. It mentions limits like the 60-day snapshot TTL and gaps due to missing scans, providing clear context without explicitly naming 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?

Adds rich behavioral context beyond annotations: describes walking the order ladder, returns like top_of_book, vwap_fill_price, slippage_pp, and in basket mode per-leg fill details, thin_legs, and forced_directional_risk. Does not contradict annotations.

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

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

Well-structured with mode sections and usage guidance, but somewhat verbose due to inline details about return fields that could be in an output schema. Minor redundancy, but overall efficient for the 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 no output schema and high complexity with two modes, the description is thorough: covers all parameters, returns, and usage rationale. Provides complete context for an AI agent to decide and 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%, so baseline 3. The description adds substantial meaning: differentiates between single-market and basket modes, explains default side selection for basket, and clarifies size_usd interpretation. Slightly redundant with schema but adds 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?

The description clearly states the tool performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth', with specific modes (single-market and basket). It distinguishes from sibling tools like polymarket_arbitrage and polymarket_edges by being a pre-trade risk check.

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

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

Explicitly advises 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500', and explains the risks of partial basket fills, providing clear when-to and why-to 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 declare readOnlyHint, openWorldHint, idempotentHint. The description adds substantial behavioral context: response includes leg-by-leg prices, top spreads, compatibility_warning (two cases), temporal_alignment, and skipped counters. It fully discloses warning conditions and limitations, far exceeding 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 well-structured with bold key terms, clear sections, and front-loaded purpose. However, it is somewhat verbose; some sentences could be streamlined without losing detail. Still, the length is warranted given the tool's complexity.

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

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

Despite no output schema, the description thoroughly explains the response structure, including safety fields and edge cases. It covers temporal alignment, skipped counters, and both warning scenarios. No gaps remain for the agent to infer.

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

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

Schema coverage is 100% with descriptions for all parameters. The description adds meaning: defines the 10 topic shortcuts, explains that explicit tickers override topic mappings, and gives examples. This enriches the schema significantly.

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 spread between Kalshi and Polymarket for the same resolving question. It distinguishes two modes (topic shortcuts vs explicit tickers) and explains that it compares equivalent bet shapes. This differentiates 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 explicit when-to-use guidance: to compare prices across venues with equivalent bet shapes. It warns that most pre-mapped topics return compatibility_warning and that aligned:false temporal mismatch makes spreads meaningless. It contrasts the two modes and explains when arb may or may not exist.

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

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

Annotations already provide readOnly, idempotent, and non-destructive hints. Description adds scoping to identifier and pairing with remember/forget, enhancing transparency.

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

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

Three concise sentences: purpose, usage, scoping. Front-loaded and no redundant information.

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

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

For a simple read tool with one optional parameter and strong annotations, description covers retrieval behavior, listing, scoping, and pairing, 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?

Only one parameter (key) with schema coverage 100%. Description repeats 'omit to list all keys' from schema, adding no new semantic value 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 retrieves saved values or lists keys, uses specific verb+resource, and distinguishes from sibling tools (remember, forget).

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

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

Describes when to use (look up stored context) and how to list all keys by omitting argument. Lacks explicit when-not-to-use but provides sufficient context.

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

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

Annotations already provide read-only, idempotent, non-destructive traits. Description adds valuable context: mark_read flag affects state (next call shows newer), data persistence, and safety for polling. Well above baseline, though lacks details on rate limits or pagination.

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 purpose, no wasted words. Covers all key aspects efficiently.

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 read-only tool with 5 optional parameters and no output schema, the description covers return fields, filtering, state behavior, and external access. Minor gap: no mention of field structure, but sufficient for typical use.

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

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

Schema coverage is 100% with good descriptions. The description adds a few examples (e.g., 'sec_8k' for type, ISO timestamp for since) but does not significantly enhance meaning 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?

Description clearly states the tool pulls fired events from a subscription feed, specifies return fields (source, citation_uri, payload), and mentions filtering options. This is a specific verb+resource with high clarity.

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

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

The description gives context for usage ('Polls work fine' and external alternative) but does not explicitly differentiate from sibling tools like 'recent_changes' or 'list_subscriptions'. Usage guidance is implied but not comprehensive.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds behavioral details: fan-out across sources, fallback behavior, PatentsView sunset, and return structure (changes[], total_changes, citation URIs). No contradiction.

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

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

Description is concise yet comprehensive, front-loaded with example queries. Every sentence serves a purpose, no redundancy. Efficient use of space.

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 rich description, comprehensive annotations, and no output schema, the description is fully complete. It explains sources, fallback, parameter formats, and output structure.

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

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

Input schema has 100% coverage. Description adds context: since accepts ISO or relative with examples, value can be ticker or CIK, type is only company. This adds meaning beyond schema.

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

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

Description clearly states the tool provides a change feed for a company in a specified window, fanning out to SEC EDGAR, GDELT/GNews, and USPTO. It includes example queries ('What's new with X') and distinguishes from sibling tool entity_profile.

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

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

Explicitly describes when to use the tool with example queries, and advises using entity_profile for static profile instead. Also explains the fan-out and fallback logic (GDELT preferred, GNews when rate-limited, PatentsView soft-fails).

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 idempotentHint=true and destructiveHint=false. The description adds valuable context: key-value pairs are scoped by identifier, authenticated users have persistent memory, anonymous sessions retain memory for 24 hours. This goes beyond annotations and clarifies behavior.

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

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

The description is concise (4 sentences) and well-structured: first sentence states purpose, second provides usage guidance, third adds technical details (scoping, persistence), fourth mentions complementary tools. No unnecessary words.

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

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

Given the tool has only 2 simple parameters and no output schema, the description covers all necessary context: what it does, when to use it, how data is stored, persistence rules, and relationship to sibling tools. It is complete 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?

Input schema covers 100% of parameters with descriptions for 'key' and 'value'. The description provides naming examples for keys (e.g., 'subject_property', 'target_ticker'), which are already in the schema. With high schema coverage, the description adds minimal extra meaning, thus baseline 3.

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

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

The description clearly states the tool's purpose: 'Save data the agent will need to reuse later' with concrete examples (resolved ticker, target address, etc.). It distinguishes from siblings like 'recall' and 'forget' by mentioning them as complementary 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 states when to use the tool: 'when you discover something worth carrying forward' so you don't have to look it up again. It also provides guidance on pairing with 'recall' and 'forget', though it could be more explicit about when not to use it (e.g., for transient data).

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, destructiveHint=false, covering safety and idempotency. The description adds valuable behavioral context: 'Each call cascades through several lookup endpoints internally — using resolve_entity replaces 2-3 manual lookups.' This explains the internal complexity without contradicting annotations.

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

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

The description is relatively lengthy but well-structured, starting with examples and then detailing supported types. Every sentence provides useful information. It could be slightly more concise by removing some repetition, but the structure is logical 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 has no output schema, the description adequately explains return values and input variations. It covers two entity types, multiple input formats, and mentions that it replaces multiple lookups. The description is comprehensive for the tool's complexity.

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

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

Schema coverage is 100%, so baseline is 3. However, the description adds significant meaning beyond the schema: it details return values for each type (e.g., for 'company' returns ticker + CIK + company_name + citation URI) and clarifies that 'value' accepts multiple formats (ticker, CIK, or name). This enriches the agent's understanding.

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

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

The description clearly defines the tool's purpose with specific verbs and resources: 'resolve a user-spoken NAME to the canonical/official identifier'. It provides concrete examples like ticker, CIK, RxCUI, and distinguishes itself from sibling tools (e.g., compare_entities, entity_profile) by focusing on resolution of names to IDs.

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 recommends using this tool 'FIRST whenever you have a name but need an ID', which is clear guidance. It also lists supported entity types. While it doesn't explicitly state when not to use, the clear purpose and examples imply usage context. No alternative tools are mentioned, but the sibling list shows other tools that could be misused.

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

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

Annotations indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description does not contradict these and adds context: it probes entities with ai_visibility_check, ranks by score, and surfaces most/least recognized. It describes the output format (ranked list with score, confidence, signal density per entity).

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, each carrying essential information. The first sentence encapsulates the core function; the second provides a practical use case and expected output. No filler or repetition.

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

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

With no output schema, the description adequately describes the return value (ranked list with score, confidence, signal density). It clarifies the number of entities (2-8) and the role of the first entity. It also mentions optional parameters like models, _apiKey, and context. While it could include more detail on error handling or exact output structure, it is sufficient for most use cases.

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

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

Schema description coverage is 100%, so the parameters are already well-documented. The description mentions that 'entities' first entry is treated as subject, which is also in the schema. It adds no new meaning beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: comparing AI visibility across multiple entities side-by-side. It uses specific verbs like 'compare', 'probe', 'rank', and identifies the resource as AI visibility of entities. It distinguishes from sibling tool 'ai_visibility_check' by emphasizing multiple entities.

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

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

The description explicitly states a use case ('competitive AI-marketing audits') and gives an example question. It implicitly suggests that for a single entity check, one should use 'ai_visibility_check' instead. However, it does not explicitly list when not to use this tool or other 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, openWorldHint, idempotentHint, and destructiveHint. The description adds significant behavioral context beyond annotations: it explains the composite fan-out, the 5-30 second delay for bundlephobia's first measurement, and graceful degradation with sources_failed. No contradictions with annotations.

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

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

The description is front-loaded with the core purpose and contains multiple sentences, each adding value. While slightly long, it is well-structured with important details (composite nature, returns, alternatives, failure behavior). Could be slightly more concise but effective.

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

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

With no output schema, the description fully covers return values (summary block fields, per-advisory details, links, alternative versions). It also mentions partial failures and the sources_failed field. Given the tool's complexity (composite, two params), the description is complete and answers potential agent questions.

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

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

Schema description coverage is 100%, so the description needs to add minimal parameter-specific info. The description does not add meaning beyond what the schema already provides (scoped packages accepted, default version behavior). 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 is a composite check for npm packages, aggregating data from deps.dev and bundlephobia. It uses specific verbs like 'fans out' and 'returns a summary block', and distinguishes from siblings by explicitly noting the npm-only scope and alternative for other ecosystems.

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

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

The description explicitly says 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' It also provides exclusion guidance: 'PyPI / Maven / Cargo / Go fall under deps.dev:version directly.' This helps the agent decide when 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, idempotentHint=true, destructiveHint=false. The description adds value by specifying the output structure (returns resource ids and titles) and the purpose of the id. No contradictions and no missing critical behaviors for a search tool.

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

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

Extremely concise two-sentence description. First sentence covers purpose and output, second sentence adds crucial cross-reference to sibling tools. 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?

The description is complete for a search tool: it explains what it does, what it returns, and how the output connects to other tools. The schema covers parameter details. Minor omission: does not explain what happens with the default searchOption value, but that is in schema.

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

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

Schema coverage is 100%, so the parameters are already documented. The description does not add new meaning beyond the schema, except for the example id 'M810001' which is output context rather than parameter semantics. 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?

Clearly states the action ('Search Singapore official statistics tables...by keyword'), the specific resource (Department of Statistics Singapore tables), and the return values (resource ids and titles). Differentiates from sibling tools by explaining that the returned id is the resourceId used by table_data and table_metadata.

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

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

Provides clear context for when to use the tool (to find table ids via keyword search), and explicitly links the output to sibling tools table_data and table_metadata. However, it does not explicitly state when not to use it or mention alternatives beyond that linkage.

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

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

The description adds behavioral details beyond annotations: embedding model (BGE-base-en), similarity metric (cosine), chunking (500-char overlapping windows), and character limit (200K chars with truncation flagging). Annotations indicate readOnly, idempotent, and non-destructive, which are consistent. 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 compact (3-4 sentences) and front-loaded with the core action. Every sentence contributes meaningful information: purpose, use case, behavioral details, and pairing advice. No redundant or wasted words.

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

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

Given the tool has only 3 parameters, no output schema, and no nested objects, the description covers all essential aspects: input semantics, use case, technical implementation, limits, and return value features (offsets, similarity scores). It is fully complete.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by explaining how to use text ('e.g. a SEC 10-K body, an article') and query ('natural-language query') with examples, and mentions limit default (5) and range (1-20). This goes slightly beyond schema.

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

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

The description states 'Semantic search INSIDE a fetched record' with a specific verb and resource. It distinguishes itself from siblings by explaining its unique role: 'Use when the record is too big to cram into the prompt' and pairs with ask_pipeworx_grounded, clearly differentiating from other search or data tools.

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

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

Explicitly states when to use: 'Use when the record is too big to cram into the prompt.' Provides a specific alternative: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.' No missing 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?

Adds significant behavioral detail beyond annotations: returns subscription ID, requires OAuth, delivery channel constraints, webhook auto-disable after 10 failures. Annotations already indicate idempotent and non-destructive, but description complements well without contradiction.

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

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

Description is dense with information but efficiently structured: purpose first, then requirements, then type-specific details, then delivery. Could be slightly more concise, but every sentence serves a 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 no output schema, description mentions 'Returns the new subscription id', which is minimal but acceptable for a simple return. Covers all 3 parameters, nested objects, and behavioral specifics. Some might expect more on return format, but it's sufficient.

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

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

Schema coverage is 100%, and the description adds extensive meaning: explains params object per subscription type, delivery options with format and constraints (e.g., SMS phone must match verified account). Adds valuable context beyond schema definitions.

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

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

The description clearly states 'Create a proactive monitoring subscription to a live-data event stream', specifying verb (create) and resource (subscription). It distinguishes from siblings like 'list_subscriptions' and 'unsubscribe' by focusing on creation.

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

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

Provides clear usage context: requires Pipeworx OAuth account, lists supported types with examples, and outlines delivery channels with constraints (e.g., SMS verification and daily cap). Does not explicitly state when not to use, but purpose is distinct enough.

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

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 returns category-bucketed example questions from the live catalog, which is useful but does not reveal any new behavioral traits beyond what annotations cover.

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

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

The description is front-loaded with key queries and provides a structured list of categories. While it is somewhat long, every sentence earns its place by adding useful context. Could be slightly more terse but remains clear.

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

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

Given the tool's simplicity (one optional param, no output schema), the description is complete. It explains the purpose, return structure, usage, and where it fits among sibling tools.

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 single optional parameter. The description reinforces the parameter by listing example values and explaining the effect of omitting it. This adds meaning beyond the schema's description.

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

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

The description clearly states the tool returns example questions for Pipeworx, categorized by topic, and positions it as the onboarding entry point. It uses specific verbs like 'returns' and distinguishes from sibling tools by noting it should be used first.

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 the tool ('FIRST when you do not yet know what Pipeworx can do') and provides alternatives (ask_pipeworx, entity_profile, etc.). Also gives guidance on arguments: call with no args for full spread, or pass topic to focus.

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

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

Annotations already cover safety (readOnlyHint, etc.). Description adds useful context on response structure (under 'Data' with 'row' array) and filtering behavior, 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?

Two sentences: first sentence covers main function and prerequisite, second details filtering and pagination. Every sentence earns its place, none wasted.

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

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

Despite lacking output schema, description covers response structure, filtering, and pagination. For 7-param tool with 1 required, it provides enough context for use. Minor omission: no mention of error conditions.

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

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

Schema covers all 7 parameters (100%). Description adds value with examples for timeFilter and between (e.g., comma-separated periods, range format), clarifying their usage 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?

Describes fetching time-series data rows for a Singapore statistics table by resourceId, with clear reference to sibling search_tables for ID retrieval. No ambiguity.

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

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

States prerequisite (get IDs from search_tables) and filter/pagination options. Lacks explicit when-to-use vs. alternatives like table_metadata, but functional context is clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering key behavioral traits. The description adds that results are under 'Data.records', which is useful but not essential 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 two sentences: first explains the action and input, second specifies output location. It is concise, front-loaded, and contains no unnecessary text.

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 one parameter, full annotations, and no output schema, the description covers what the tool returns (theme, subject, frequency, etc.) and where to find it. It could detail the variables/series format, but overall it is complete for the tool's simplicity.

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 resourceId as 'Table id from search_tables, e.g. "M810001".' The description repeats this context but adds no new parameter meaning 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 retrieves structure/metadata for a Singapore statistics table by resourceId, listing specific metadata fields (theme, subject, frequency, etc.). It distinguishes itself from sibling tools like search_tables (which provides IDs) and table_data (which provides actual data).

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

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

The description explicitly tells the agent to get resourceIds from search_tables, implying a prerequisite. It implicitly differentiates from table_data for data retrieval. However, it does not explicitly state when not to use the tool.

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

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

The description adds significant behavioral context beyond annotations: it explains that the row is deactivated (not deleted) so historical events remain, aligning with destructiveHint=false. It also discloses ownership enforcement, which annotations do not capture.

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

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

Two concise sentences: first states the core action, second adds ownership and side effect. No redundant words, all information earned its place.

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

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

Given the tool's simplicity (one parameter, no output schema), the description fully covers purpose, usage constraints, and behavioral side effects. It is complete for the tool's complexity.

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

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

Schema covers 100% of parameters. The description adds value by specifying that 'id' is the subscription uuid returned by 'subscribe', providing useful origin context beyond the schema's type description.

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

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

The description clearly states the action 'Cancel a subscription by id' with a specific verb and resource. It distinguishes from sibling tools like 'subscribe' and 'list_subscriptions' by specifying ownership enforcement and deactivation behavior.

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 implicitly guides usage by noting ownership enforcement ('you can only cancel your own subscriptions') and ties to the 'subscribe' tool via the id. It could be more explicit about when to use, but it provides clear context.

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

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

Annotations already provide readOnlyHint=true, idempotentHint=true, and openWorldHint=true, which cover safety and idempotency. The description adds value by detailing the exact response format (verdict, structured form, citation, delta) and the scope (SEC EDGAR + XBRL). No contradiction with annotations.

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

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

The description is a single coherent paragraph with a clear structure: examples, usage, scope, output. It is reasonably concise but could be trimmed slightly. Front-loaded with key purpose, earning a 4.

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 a single parameter, no output schema, but strong annotations, the description fully covers what the agent needs: purpose, usage, domain, output format, and citation details. It is complete for effective invocation.

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

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

Schema description coverage is 100% with one parameter 'claim' described as 'Natural-language factual claim'. The description goes beyond by providing multiple example claim formats and clarifying the expected natural language input, adding practical context for the agent.

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

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

The description begins with natural-language examples like 'Is it true that…' and explicitly states 'natural-language claim verification against authoritative sources', providing a specific verb (verify) and resource (claims). It distinguishes itself from sibling tools by noting it replaces 4-6 sequential calls, making its unique value clear.

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 whenever the agent needs to check whether something a user said is factually correct.' It also scopes the domain to company-financial claims. While it doesn't list alternatives or when not to use, the context is sufficiently clear.

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