Startup Oracle

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

The description adds behavioral context beyond annotations: it explains the default model, the need for an API key for Anthropic, and the return structure (per-model fields + combined view). Since annotations already declare readOnlyHint and idempotentHint, the description enriches transparency 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?

The description is two sentences with front-loaded action and key details. Every sentence earns its place: the first covers core functionality and output, the second explains defaults, optional key, and return structure. No wasted words.

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

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

Despite no output schema, the description specifies the exact return structure ('per-model {score, confidence, signals, raw_response} + a combined view'). All four parameters are explained with clear usage. The tool's complexity is low-moderate, and the description covers all necessary information for an agent to use it 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 is 3. The description adds value by explaining default model behavior, the optional API key requirement, and the purpose of the 'context' parameter for disambiguation. This goes beyond the basic schema descriptions, though 'signals' in the return is not elaborated.

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

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

The description uses a specific verb ('probe') and resource ('LLMs for what they know about a business / brand / product / topic') and clearly states the output ('score visibility (0-100) per model'). It distinguishes the tool from siblings by focusing on AI visibility scoring, which is not covered by other sibling tools like scan_competitor_ai_presence or validate_claim.

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

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

The description explicitly lists use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It implies when to use but does not explicitly state when not to use or name alternative tools. However, the context is sufficiently clear for an agent to decide.

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

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

The description goes beyond the read-only and idempotent annotations by revealing that the tool is a router: it 'routes the question to the right one of 5,798 tools... fills arguments, returns the structured answer with stable pipeworx:// citation URIs.' This is valuable behavioral context. There is no contradiction with annotations; in fact, the routing behavior aligns with openWorldHint. It could mention more about latency or potential source failures, but the disclosure is strong.

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 severely bloated by a repetitive loop: the 'Examples:' list and 'START HERE for most questions' phrase are repeated many times verbatim. The initial portion is well-structured and front-loaded, but the redundancy makes the description much longer than necessary. This is not concise and does not earn every sentence.

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

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

For a complex router tool with no output schema, the description covers the key contextual needs: what it does, when to prefer it, what kinds of questions it handles, concrete examples, and the return format (structured answer with citation URIs). It does not clarify how to distinguish between ask_pipeworx and its sibling beta/grounded variants, which is a gap, but overall the description is nearly complete for an agent to invoke it 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?

The input schema is fully described (100% coverage), with the main 'question' parameter and five aliases all documented. The tool description does not add parameter-level semantics beyond the schema, but its examples—like 'current US unemployment rate' or 'Apple's latest 10-K'—illustrate expected phrasing. Since the schema already handles the heavy lifting, a 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: it answers factual questions about current or historical data by routing to thousands of sources, returning structured answers with citations. It uses a specific verb ('routes') and resource ('5,798 tools across 1517 verified sources'), and explicitly contrasts itself with web search. However, it does not distinguish itself from sibling tools like ask_pipeworx_beta or ask_pipeworx_grounded, so it falls short of a 5.

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

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

The description is explicit about when to use the tool: 'PREFER OVER WEB SEARCH' for a long enumerated list of data categories, and 'Use whenever the user asks...' with common query phrasings. It also states 'START HERE for most questions' and even covers the case where web search could answer. However, it provides no exclusions or guidance on when to choose sibling tools, so it lacks full when-not/alternatives coverage.

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

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

The description reveals important behavioral details beyond the read-only/idempotent annotations: no candidate is currently active, the last candidate was retired on a specific date, the tool is a full working router with no fallback, and behavior may change when a candidate is under test. This gives the agent a realistic picture of what invoking it means.

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

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

The description is front-loaded with the most important fact, 'Beta version of ask_pipeworx,' and each sentence adds useful context: identical shape, current candidate state, usage instruction, and no-fallback clarification. There is no filler or repeated schema 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 tool with read-only annotations, simple alias-only parameters, and no output schema, the description is complete. It explains current behavior, exact equivalence to ask_pipeworx, how to use it, and what makes it distinct. Nothing essential for correct invocation is missing.

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

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

Schema description coverage is 100% and every parameter is already documented as an alias for question. The description adds no new parameter-level meaning, only saying arguments match ask_pipeworx. Baseline 3 is appropriate because the schema fully carries the parameter documentation burden.

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

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

The description states a specific verb and resource: it is the beta version of ask_pipeworx, an identical universal router with the same 5,798 tools, arguments, and response shape. It clearly differentiates itself from the stable ask_pipeworx sibling by mentioning candidate routing improvements and the current experimental edge.

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

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

It explicitly says to use it exactly like ask_pipeworx when the newest routing is desired and notes that results are compared against the stable router. It does not provide a hard 'don't use when' rule, but the beta versus stable distinction and current no-candidate-active state make the usage context 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, and the description adds substantial context on top: the exact success object {answer, evidence, confidence, source, fetched_at, refusal_reason}, the five enumerated refusal reasons, the guarantee that extraction uses only the tool result, and the extra-LLM-call cost. This is precisely the behavioral depth an agent needs beyond the safety flags, and nothing contradicts the annotations.

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

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

The description is dense but every sentence earns its place: purpose, mechanism, success/refusal formats, use cases, and cost tradeoff against the sibling. It is front-loaded with the core value proposition ('Hallucination-resistant answer mode'). It runs slightly long due to the enumerated refusal reasons and return object, but that detail is load-bearing for a high-stakes tool with no output schema, so the length is justified.

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

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

For a tool with no output schema, the description carries the full burden of explaining return values — and it does, covering both the success object and the refusal object with specific reason strings. It also covers cost, sibling differentiation, and when refusal occurs. Combined with a trivial one-question input schema and safety-bearing annotations, nothing an agent needs to invoke this correctly is missing.

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

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

Schema description coverage is 100% — all six parameters are aliases for 'question' and are well documented in the schema itself. The description references routing and argument-filling at the tool level but adds no parameter-level meaning beyond what the schema already provides, so the baseline 3 for high coverage applies.

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

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

Opens with a specific, high-value framing — 'Hallucination-resistant answer mode for high-stakes reads' — and states exactly what the tool does: route like ask_pipeworx, fetch data, then extract the answer using only the tool result. It enumerates the success and refusal return shapes, and explicitly contrasts itself with the sibling ask_pipeworx ('Same routing as ask_pipeworx... then EXTRACTS'), so an agent can distinguish them without opening the schema.

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

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

Provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts,' with concrete domains listed (financial verdicts, legal claims, medical lookups, public statements). It also gives a when-not-to-use rule with a cost rationale: 'Costs one extra LLM call vs ask_pipeworx — prefer ask_pipeworx for casual lookups.' This fully routes an agent between the two 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?

The description thoroughly explains behavior beyond annotations: low-confidence short-circuiting, closed market handling, resolution-rule risk, response shapes, and even internal caching/fallback mechanisms. This far exceeds annotation hints.

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

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

The description is lengthy but well-structured with sections (RESOLVER CONTRACT, PARENT_EVENT EXTRACTOR, etc.) and front-loaded with the core purpose. Every sentence adds value, though it could be slightly more concise.

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

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

With no output schema, the description fully documents response shape, statuses, edge cases, and error handling. It covers everything an agent needs to correctly interpret results and handle failures.

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 meaning to each parameter: market (formats), depth (quick vs thorough), include_raw (when to use true). It also includes examples and recommended defaults.

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

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

The description explicitly states the tool researches a Polymarket bet by pulling Pipeworx data, and gives clear examples of inputs (slug, URL, question text). It also states usage scenarios like 'should I bet on X', making the purpose highly specific and unambiguous.

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

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

The description provides explicit use cases ('Use for...') and detailed fan-out examples, but does not explicitly contrast with sibling tools like polymarket_edges or polymarket_arbitrage, leaving some room for ambiguity.

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

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

The description adds substantial behavioral context beyond annotations: explains data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), off-calendar fiscal year handling, result sorting by primary metric, and citation URIs. 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 highly efficient: front-loaded with common query patterns, then concise details. Every sentence adds value without redundancy.

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

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

For a tool with 2 parameters and no output schema, the description fully covers input semantics, data sources, result format (paired data + citations), and even performance claim (replaces 8-15 lookups). Nothing essential is missing.

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

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

Schema coverage is 100%, and the description adds significant meaning: explains the enum values for 'type' with what data each pulls, and clarifies the format for 'values' (tickers/CIKs for company, drug names; constraints 2-5 items). This goes beyond the schema's basic 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 does side-by-side comparison of 2–5 companies or drugs in one parallel call, with specific data sources for each type. It distinguishes from sequential single-pack lookups and provides example queries that map to the tool's 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?

Explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' providing clear when-to-use guidance. Also gives concrete query examples that help the agent recognize appropriate invocation patterns.

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

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

Annotations (readOnlyHint=true, idempotentHint=true) cover safety, and the description goes far beyond: account requirements, paid tier for thorough, parallel decomposition through 5,798 tools, findings packet structure (verbatim evidence, confidence, source, fetched_at, citation), gaps[] never invented, contradictions[] in standard/thorough, semantic excerpting, and expected latency. No contradiction with annotations.

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

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

The description is long but densely packed with operational essentials (auth, alternatives, output format, gaps, contradictions, latency). It is front-loaded with the most critical constraint (account required). Some redundancy exists between the depth explanation here and the schema enum description, and a minor repetition of the citation URI point, so it is not maximally tight.

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

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

For a complex research tool with no output schema, the description covers everything an agent needs: prerequisites, depth tiers, data source types, output packet fields, gap and contradiction handling, citation resolvability, record excerpting, and timing. There are no significant gaps in this context.

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

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

Schema description coverage is 100%, including a detailed enum description for depth and clear guidance for question. The tool description mostly restates the same depth semantics (quick=3, standard=3 with gap-recovery, thorough=6 paid) rather than adding new parameter-specific meaning. This meets the baseline but does not exceed it.

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

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

The description uses a specific verb+resource: 'Grounded multi-source research across Pipeworx's 1517 STRUCTURED data sources ... in ONE call.' It explicitly distinguishes itself from open-web search and names its sibling alternative (ask_pipeworx), making its purpose unmistakable.

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

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

Provides explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data' with concrete examples, and clear exclusions: 'If you are not signed in, use ask_pipeworx instead' and 'For a single lookup use ask_pipeworx instead.' This is exemplary routing behavior.

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

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

Annotations already provide readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the description is not burdened with those. It adds context by stating that results include full input schemas with curated examples (ready to call) and that it returns the top-N most relevant tools. This goes beyond the annotations and helps the agent understand the tool's 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 three sentences long with no wasted words. It front-loads the purpose and usage, then adds behavioral context and a clear directive ('Call this FIRST'). Every sentence earns its place.

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

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

Given the low complexity (2 distinct parameters, no output schema), the description is largely complete. It explains the return format (top-N tools with names, descriptions, and schemas) and provides usage advice. Minor gaps include the default limit (20) and max limit (50), but these are in the schema. Overall, sufficient for an agent.

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

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

Schema description coverage is 100% (all parameters have descriptions). The description does not add new meaning beyond what the schema already provides regarding the 'query' parameter and its aliases. The examples in the schema are helpful, but the tool description itself does not augment parameter semantics. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It provides a long list of example domains (SEC filings, financials, FDA drugs, etc.) and explains that it returns top-N relevant tools with full input schemas ready to call. This distinguishes it from sibling tools that are more specific (e.g., deep_research, compare_entities).

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

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

The description explicitly advises: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This gives clear when-to-use guidance and implies when not to use (if the agent already knows which tool to call). No exclusions are needed; 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 already declare read-only, open-world, idempotent, and non-destructive behavior. The description adds substantial context beyond that: parallel fan-out, soft-fail on the USPTO PatentsView API sunset, expected empty sections, GDELT→GNews fallback, and resolved:false plus a notes line for private companies. This is far more than annotations alone provide.

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

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

The description is long, but the tool is genuinely complex with many return sections and edge cases. It is dense and organized, though the 'ALWAYS PREFER' usage guidance could be front-loaded more aggressively, and a few phrases repeat information already present in the schema.

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

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

With no output schema, the description fully carries the burden of explaining the return structure, and it does so in detail: cik, recent_filings, fundamentals, patents, federal_contracts, fda_products, hiring, news, LEI, and sources_used/sources_failed. It also covers edge cases like API sunset soft-fails, empty sections, private companies, and expected absence of FDA biologics.

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 goes further by giving concrete examples ('AAPL', '0000320193', 'Moderna'), explaining that type is effectively interchangeable, and clarifying name resolution via SEC EDGAR. It slightly restates schema content, but the examples and edge-case notes add real value beyond the schema.

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

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

The description states exactly what the tool does: builds a full cross-source profile of a US public company in one parallel call, with a concrete list of sources and return sections. Query examples make the trigger intent unmistakable, and the 'ALWAYS PREFER over chaining single-pack' phrasing distinguishes it from narrower lookups.

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

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

Explicitly tells the agent when to prefer this tool ('holistic view') and when not to rely on it (private companies return resolved:false; drug-only companies are expected to show no fda_products). The description also explains the accepted input shapes and what sources_failed/sources_used mean, leaving little to inference.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. The description adds useful context by mentioning 'clear sensitive data' and that the memory was saved by the agent earlier, enhancing transparency 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, front-loaded with purpose. Every sentence adds value: first states function, second provides usage context and tool pairing. No wasted words.

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

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

Given a single parameter and no output schema, the description adequately covers purpose, usage, and pairing. Minor gap: does not specify behavior if the key does not exist, but annotations and simplicity compensate.

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 the parameter 'key' described as 'Memory key to delete'. The description adds no additional semantics beyond confirming it is a memory key, 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 states 'Delete a previously stored memory by key', providing a specific verb and resource. It distinguishes from sibling tools like remember and recall by explicitly pairing with them.

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

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

The description specifies when to use the tool: 'when context is stale, the task is done, or you want to clear sensitive data'. It also advises to pair with remember and recall, but does not include explicit exclusions.

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

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

Annotations already indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds that it fetches the page, extracts title/description/key links, and emits standard markdown, providing useful behavioral context beyond annotations.

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

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

The description is concise and well-structured: opening sentence states purpose, then clarifies output, then lists use cases. Every sentence adds value without redundancy.

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

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

Given the tool's simplicity (2 params, no output schema), the description and annotations together provide enough information for correct invocation and understanding of results. Minor gap: no mention of error handling or URL validation.

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. The description adds context like default and max for max_links, but does not significantly extend schema info. Baseline 3 is appropriate.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL. It specifies the action, resource, format, and use cases, making the purpose unmistakable.

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

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

The description lists specific use cases (client site indexing, personal project drafting, competitor auditing) and implies when to use. It lacks explicit when-not-to-use but provides sufficient context for selection.

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

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

Annotations already indicate readOnly, idempotent, and non-destructive behavior. The description adds value by specifying the scope (caller's subscriptions), default filtering (active only), and return fields (id, type, params, etc.), which goes beyond the annotations.

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

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

The description is three sentences long, front-loaded with the core purpose, and every sentence contributes value. There is no redundancy or fluff.

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

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

Given the tool's simplicity (one optional parameter, no output schema), the description covers all essential aspects: what it lists, returned fields, default behavior, and usage context. It effectively differentiates from siblings and provides sufficient information for an agent to use it 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% for the single parameter 'include_inactive', which already includes a clear description. The tool description does not add further meaning beyond what the schema provides, so it meets the baseline of 3.

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

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

The description opens with a specific verb+resource: 'List the caller's active subscriptions.' It clearly distinguishes from sibling tools like subscribe and unsubscribe by focusing on reading existing subscriptions.

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

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

The description explicitly advises using it 'to review what you're monitoring before adding more or to find an id to cancel,' providing clear when-to-use context. However, it does not explicitly state when not to use it or name alternatives, so it falls short of a 5.

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

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

Beyond the annotations (readOnlyHint=false, etc.), the description discloses significant behavioral traits: the claim_token mechanism for following up on reports, rate limiting (5 per identifier per day), that it's free and doesn't consume quota, and that the team reads digests daily. These are critical operational details that annotations alone don't convey.

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

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

The description is dense but every sentence carries essential information: purpose, usage criteria, exclusions, token behavior, rate limits. It is front-loaded with the core purpose and flows logically into constraints. No filler or redundancy.

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

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

For a tool with no output schema, the description does an excellent job explaining the return value (claim_token, status updates) and follow-up mechanism. It also covers practical constraints (rate limits, quota) and explicitly clarifies the tool's scope (only Pipeworx connection tools). The nested context parameter is adequately described in the schema, and the description fills the remaining 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?

Although schema coverage is 100%, the description adds value by explaining the claim_token usage in context ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})') and by giving guidance on message content ('don't paste the end-user's prompt'). It doesn't fully compensate for the nested context object, but the schema already covers that well, so the added semantics are a bonus.

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

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

The description uses a specific verb ('Tell') and resource ('Pipeworx team'), and clearly states the tool's scope: collecting feedback about broken, missing, or desired functionality. It naturally distinguishes itself from sibling tools like ask_pipeworx (which answers questions) and discover_tools (which lists tools), leaving no ambiguity about its 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?

Provides explicit when-to-use guidance: for bugs, feature requests, data gaps, or praise. Critically, it also states when NOT to use it (for tools from other MCP servers) and directs users to the appropriate alternative (file with that server instead). This is strong usage differentiation beyond mere 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 indicate read-only, idempotent, and safe. Description adds valuable behavioral context: source (CF analytics-engine), no PII, caching (5min-1h), and the nature of data (pack, tool, count). 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?

Five concise sentences with front-loaded main purpose. Every sentence adds value: returns data, use cases, data source, caching, privacy. 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 only one optional parameter and no output schema, the description covers all aspects: what is returned, how to use (window selection), data provenance, privacy, and caching. Fully sufficient for an agent to invoke correctly.

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

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

Schema has 100% coverage for the single parameter. Description adds semantic guidance beyond the schema by explaining the trade-off between windows: 'shorter windows surface what's hot right now; longer windows show steady-state demand', which aids selection.

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

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

Description specifies exactly what the tool returns: top tools, packs, and call volume by window. It uses a specific verb ('Returns') and resource ('trending data'), and effectively distinguishes itself from sibling tools like discover_tools by focusing on aggregated usage statistics rather than discovery.

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 concrete use cases are listed (discovering hot data sources, confirming canonical choice, aligning use case). While no explicit 'when not to use' or alternatives are given, the use cases provide clear context for when this tool is appropriate.

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

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

Annotations indicate read-only, open-world, idempotent, non-destructive behavior. The description goes beyond by detailing fill check against CLOB depth, realizable edge conditions, semantic anchor (Jaccard similarity), and partition filter logic. 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 thorough and well-structured, starting with purpose, then modes, then deep details. While slightly lengthy, every sentence carries useful information and the front-loading of key guidance makes it 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?

Despite no output schema, the description explains the response structure (opportunities[], partition_check, fill_check) and references the related tool polymarket_fill_risk. It covers all necessary aspects for an agent to use the tool correctly.

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

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

Schema description coverage is 100%, and the description adds significant context: event as slug or URL, topic as seed question, and explains the mode each parameter triggers. The additional details elevate it above 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: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes three modes (no args, event, topic) and provides specific verbs and resources, making it distinct 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?

Explicit guidance is given for each invocation mode: 'Call with NO args for a trending_scan of the top ~200 markets', 'event (recommended for a specific market)', and 'topic for cross-event scanning'. It also explains when cross-event is beneficial and includes semantic anchor and partition filter details.

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 extensively details behavioral traits beyond annotations: it explains caching (1h at KV level), three model families with mathematical formulas, opportunity fields, and diagnostics for empty segments. Annotations indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, and the description adds rich context about mutation, state, and side effects, with no contradictions.

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

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

The description is long but well-structured with clear sections for model families, opportunity fields, knobs, and response format. It is front-loaded with the core purpose. While every sentence adds value, it could be slightly more concise without losing important detail.

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 (9 parameters, three model families, no output schema), the description is remarkably complete. It explains all three response segments in detail, tradeable-edge filters, diagnostics for empty segments, and caching behavior. The lack of an output schema is compensated by explicit description of response fields and structure.

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

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

Schema coverage is 100% (baseline 3), but the description adds significant meaning for each parameter. For example, it explains min_kelly as 'Minimum half-Kelly fraction... skip opportunities too small to bet sensibly', slipage_pp with context about Polymarket's zero fees and typical thin depth, and categorical details for category_filter and min_partition_leg_kelly. This goes well beyond the schema descriptions.

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

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

The description clearly states: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price. Built for "what should I bet on today"'. It uses a specific verb (scan, return) and resource (Polymarket markets), and the core concept of disagreement is distinct. Sibling tools like polymarket_arbitrage and polymarket_edge_tracker are implicitly differentiated by focusing on opportunity discovery rather than tracking or arbitrage execution.

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

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

The description gives a clear use case: 'agents discover opportunities without paging hundreds of markets'. It explains how to use the tradeable-edge knobs to filter opportunities. However, it does not explicitly state when not to use this tool or compare it to alternatives like polymarket_arbitrage or polymarket_edge_tracker, leaving room for slight ambiguity.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds rich behavioral context: data from daily snapshots with 60-day TTL, decay computed from daily closes (not intraday), and handling of missing snapshots (gaps mean no scan). 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. It starts with a concise purpose statement, then details the response fields and limits. The information is front-loaded with the key question it answers. Could be slightly tighter, but every sentence adds value without redundancy.

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

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

Given that there is no output schema, the description thoroughly explains the three response arrays (tracked[], expired[], snapshot_dates[]) and their fields. It also covers edge cases like gaps in snapshots and TTL limits. The description is complete enough for an agent to understand the tool's full behavior.

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

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

Schema coverage is 100%, with descriptions for both 'days' and 'window'. The description adds value by clarifying defaults (14 days, '1wk'), constraints (max 30 days), and the meaning of the 'window' parameter. It also explains the response structure, which aids understanding of parameter effects.

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: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It directly answers the question 'how long has this edge existed and is it shrinking?' and distinguishes itself from sibling tool polymarket_edges by focusing on historical time-series and decay trends.

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

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

The description implies when to use by contrasting a fresh wide edge versus a 3-week-old one, and notes that gaps in snapshots mean no scan occurred. It does not explicitly state alternatives (e.g., 'use polymarket_edges for current edges'), but the context makes it clear. Slightly less explicit guidance on when not to use.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. Description adds operational details: walks the ladder, returns specific fields, defaults, and critical warning about partial basket fills causing unhedged directional positions. This goes well beyond annotation information.

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

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

Well-structured with front-loaded purpose and clear mode separation. Slightly verbose, but every sentence adds essential information. Could be tightened slightly without losing clarity.

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

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

Despite no output schema, description thoroughly explains return values for both modes (top_of_book, vwap_fill_price, verdict, etc.). Covers parameter details, usage warnings, and edge cases (thin books, forced directional risk). Complete for a risk-check tool.

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

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

Schema coverage is 100%, but description adds significant meaning: explains side auto-detection for basket, interprets size_usd differently for basket (settlement notional), and clarifies market vs event exclusivity. Adds value beyond schema descriptions.

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

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

Description clearly states 'Realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes two modes (single-market and basket). It explicitly contrasts with sibling tools polymarket_arbitrage and polymarket_edges by specifying when to use this tool before acting on their signals.

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

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

Explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. Provides clear context for when to use and implies when not to (small trades). No confusion about alternatives.

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

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

Annotations already declare readOnlyHint and idempotentHint, and the description adds substantial behavioral disclosures beyond that: the identical matcher across both modes, compatibility codes with detailed meanings, non-equivalence warnings, skipped/unclassified leg handling, gross vs net spread, and fee treatment. There is no contradiction with the annotations.

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

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

The description is dense but well-structured, using labels like TWO MODES, RESPONSE, and SAFETY FIELDS, and front-loads the core purpose and main caveat. It is longer than average, but nearly every sentence carries distinct information; minor trimming of code enumerations could tighten it.

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

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

There is no output schema, so the description carries the full burden of explaining the return value. It covers leg-by-leg prices, spread fields, flags, compatibility and alignment semantics, the fees note, and skip counters. An agent has enough context to call the tool and interpret its results.

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 already 100%, and the description still adds meaningful parameter semantics: how `topic` maps to pre-mapped events, how `kalshi_event_ticker` and `polymarket_event_slug` override the mapped side, and that both modes run the same matcher. This goes well above the baseline.

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

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

The description clearly states the tool's function: compute the cross-venue spread between Kalshi and Polymarket for the same resolving question. It is specific about the action and resource, but it does not explicitly differentiate itself from closely related sibling tools like polymarket_arbitrage or 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 gives strong usage context: it explains two modes (pre-mapped topics vs explicit ticker/slug), when each is appropriate, and warns that pre-mapped shortcuts often produce warnings and are not automatically tradeable. However, it does not explicitly state when to prefer a sibling tool instead, so it misses the top bar.

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 scoping detail and list capability beyond annotations. No contradiction; readOnly and idempotent hints are consistent.

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 main action, no wasted words.

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

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

Covers operation, scoping, and pairing. Lacks return format details, but acceptable for simple optional-param tool with annotations.

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

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

Schema coverage is 100% with description for key. Description adds example values but no meaning beyond what schema provides. 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?

Description clearly states verb 'Retrieve' and resource 'value previously saved via remember', and distinguishes from siblings by specifying listing behavior on omit key.

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

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

Explicit examples of when to use (look up stored context) and pairing with remember/forget. Could mention when not to use, but context is sufficient.

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

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

The description states mark_read:true flags events as read, implying a state change, but annotations declare readOnlyHint=true and destructiveHint=false. This contradiction hinders transparency. The description does add details about return fields and polling behavior, but the contradiction undermines trust.

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 main action, each sentence provides distinct value—no filler. Efficient and 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?

Covers parameters, filtering, mark_read behavior, polling, and alternative endpoint. Lacks explicit mention of return format (list? order?) but implied by 'most recent' and 'next call only shows newer ones'. Sufficient for a read-only list tool with 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%, and the description adds meaningful usage context beyond schema: explains the purpose of mark_read, provides an example for type, and clarifies since format. This aids agent in correct parameter usage.

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

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

The description clearly states the tool returns alerts from the subscription feed with specific fields, and the verb 'pull fired events' is precise. It distinguishes itself from sibling tools like recent_changes by focusing on alerts/events from the evaluator's feed.

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

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

The description explains filtering by type and since, the mark_read flag for incremental polling, and notes that polls work fine. It also provides an alternative URL. However, it lacks explicit comparisons to sibling tools like recent_changes.

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 and idempotency. The description adds valuable behavioral details: fan-outs to SEC EDGAR, GDELT→GNews fallback with rate-limit note, USPTO soft-fail, and structured return format. This goes beyond annotations without contradicting them.

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

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

The description is thorough but slightly long; however, every sentence adds value. It is front-loaded with example use cases and structured logically. Could be trimmed slightly without loss, but overall efficient.

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

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

Despite no output schema, description adequately explains return structure (changes[], total_changes, citation URIs). The complex behavior (multiple sources, fallback, soft-fail) is well covered. Sibling differentiation is handled. 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 coverage is 100%, but description adds meaning: explains 'since' accepts ISO or relative shorthand with examples, clarifies 'type' is limited to 'company', and notes 'value' accepts ticker or CIK. This provides practical guidance beyond schema descriptions.

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

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

The description clearly states the tool returns a change feed for a company (SEC filings, news, patents) over a time window, and explicitly distinguishes itself from the sibling 'entity_profile' tool, making the purpose highly specific and differentiated.

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 example queries, explains multi-source aggregation, gives typical 'since' parameter values ('30d' or '1m'), and explicitly directs to 'entity_profile' for static profiles. This offers clear context on when and how 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?

Beyond annotations (idempotent, non-destructive), description adds scope (key-value pair by identifier) and persistence details (24h for anonymous, persistent for authenticated). 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?

Four sentences, front-loaded with purpose, no fluff. Well-structured and easy to parse.

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 simple 2-param tool with annotations, description fully covers purpose, usage, behavior, and complementary tools. No gaps.

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

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

Schema covers 100% with descriptions for both key and value. Description adds minor context (key examples, value is any text) but doesn't significantly enhance parameter 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?

Clearly states verb 'save' and resource 'data', distinguishing from siblings 'recall' and 'forget'. Examples clarify what data to store.

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

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

Explicitly says when to use ('discover something worth carrying forward') and provides examples. Also mentions complementary tools for retrieval and deletion.

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

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

Beyond the annotations (read-only, idempotent, open-world), the description discloses rich behavioral details: cascading internal lookups, graceful degradation when GLEIF/OpenFIGI are unavailable, ambiguity handling via `figi_candidates`, explicit `unresolved` fields, and source-labelled identifiers. This gives an agent an accurate mental model of what will and won't happen on each call.

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 trigger examples and the 'Use FIRST' directive, and nearly every sentence carries useful information. It is, however, long and contains dense run-on parentheticals, especially in the 'company' type block, which reduces scannability without adding new semantic content.

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

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

Given the tool's complexity and the absence of an output schema, the description is remarkably complete: it names inputs, outputs, source systems, failure behavior, ambiguity behavior, and enrichment degradation. An agent has enough information to decide when to call it, how to construct `value`, and what to expect back.

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?

Although the schema already describes both parameters at 100% coverage, the description adds substantial extra semantics: exact accepted forms for `value` (ticker, CIK, ISIN, name), entity-specific examples, and the crucial anti-pattern warning to pass the issuer name only and not the full noun phrase. This meaningfully improves correct invocation beyond the schema alone.

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

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

The description opens with concrete user phrasings ('What's the ticker for…', 'find the CIK for…') and states the verb+resource plainly: resolve a user-spoken NAME to canonical/official identifiers other tools require as input. It also enumerates supported types ('company', 'drug') and the specific identifiers returned, so an agent can distinguish this from siblings like entity_profile or compare_entities.

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

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

The description gives an explicit trigger condition: 'Use FIRST whenever you have a name but need an ID.' It also notes that the tool 'replaces 2-3 manual lookups,' reinforcing when it is appropriate. However, it does not name alternatives or state a when-not-to-use case, so it stops short of full exclusion guidance.

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

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

Beyond annotations (readOnly, idempotent, etc.), the description adds behavioral details: it probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, and signal density. This context enriches the agent's understanding 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 three concise sentences, front-loaded with the primary purpose. Every sentence adds value: purpose, method, use case, and return format. 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 covers what the tool does, how it works (calling ai_visibility_check), and what it returns (ranked list with metrics). Given the annotations cover safety and idempotency, and there is no output schema, this is complete enough for reliable tool 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 coverage is 100%, so baseline is 3. The description adds meaning beyond the schema by noting that the first entity in the 'entities' array is treated as the 'subject' for narrative purposes, which is not in the schema 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's purpose: 'Compare AI visibility across multiple entities side-by-side.' It uses specific verbs (compare, probes, ranks, surfaces) and identifies the resource (entities). It distinguishes from sibling tools like ai_visibility_check by emphasizing multi-entity comparison and ranking.

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

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

The description provides clear context for use: 'Useful for competitive AI-marketing audits' with an example question. It implies when to use this tool vs. single-entity alternatives, but does not explicitly state when not to use it or mention alternatives like compare_entities.

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. Description adds crucial details about partial failures degrading gracefully, bundlephobia latency (5-30s), and the 'sources_failed' field.

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 but well-structured, front-loading the core value proposition and then detailing behavioral nuances. Every sentence adds value without redundancy.

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

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

Despite lacking an output schema, the description comprehensively details the return structure (summary block, per-advisory detail, links, alternative versions) and handles edge cases like partial failures, making the tool's behavior fully predictable.

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 for both parameters. Description adds that 'version' defaults to latest published when omitted and that scoped packages are accepted, providing useful 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?

Description clearly states it's a composite check for deciding whether to add an npm package, covering license, advisories, version history, bundle size, etc. It distinguishes itself from sibling tools by being a single call that fans out across multiple sources.

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 whenever an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me''. Also specifies NPM ecosystem only in v1 and directs to deps.dev:version for other ecosystems.

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

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

The description adds significant behavioral context beyond annotations: mentions BGE-base-en embeddings, cosine similarity over 500-char overlapping windows, 200K char cap with truncation flagging. All annotations (readOnlyHint, idempotentHint, destructiveHint) are consistent and reinforced.

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 tightly-written paragraph with no wasted words. It delivers purpose, usage guidance, technical details, and limitations in a coherent flow.

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

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

Given no output schema, the description thoroughly explains return format (passages with offsets and similarity scores) and internal mechanics. It covers all necessary context for an agent to use and interpret results.

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 value by providing default limit (5) and query examples ('supply-chain risk', 'fiscal year 2024 revenue'). While it doesn't describe all parameter constraints in extreme detail, the examples enhance usability.

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 'semantic search INSIDE a fetched record' with specific verb+resource, and distinguishes it from sibling tools like ask_pipeworx_grounded by explaining the pairing and different use cases.

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

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

Explicitly tells when to use ('when the record is too big to cram into the prompt') and provides an alternative (pairs with ask_pipeworx_grounded for grounded responses). Also explains benefits: saves context and returns passages with offsets for verification.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds value by detailing the output: 'returns a brutal verdict, number of pivots required, a funny comparable, a realistic YC rejection reason, and the actual TAM (always $4 trillion)'. This provides context beyond the annotations.

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

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

The description is one sentence that efficiently conveys the tool's purpose and outputs, with no wasted words. It is front-loaded and easy to parse.

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 lighthearted tool, the description fully sets expectations. The output schema exists (inferred from context), so return values are documented. The description explains the unique TAM value, which is a key behavioral detail.

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

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

Schema description coverage is 100% for all parameters, so the schema already documents each parameter. The description does not add further meaning to the parameters; it focuses on the output. 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 uses the specific verb 'evaluate' with the resource 'startup idea', clearly stating the tool's purpose. It lists the specific outputs (verdict, pivots, comparable, rejection reason, TAM), making it distinct from sibling tools which are more serious and analytic.

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

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

The description implies a humorous, informal use case through terms like 'brutal verdict', 'funny comparable', and 'realistic YC rejection reason'. However, it does not explicitly state when to use this tool versus alternatives, or when not to use it.

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

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

The description adds significant behavioral context beyond annotations, including account type restrictions, subscription type details, delivery channel limits (10/day SMS cap), and webhook auto-disable after 10 failures. 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 thoroughly informative but somewhat lengthy; however, every sentence adds value and the structure is well-organized. Could be slightly more concise but remains efficient.

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

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

Given the complexity of nested objects and no output schema, the description fully covers all types, parameters, delivery options, and return value, 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?

With 100% schema coverage, the description provides extensive parameter semantics: examples for each type, required fields, and detailed explanations for the delivery object, enriching the schema.

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

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

The description clearly states the tool creates a proactive monitoring subscription and returns a subscription ID, with specific verb and resource. It distinguishes from siblings like list_subscriptions and unsubscribe.

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

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

The description explicitly states when to use (create subscription), prerequisites (Pipeworx OAuth account), and provides detailed type-specific parameters and delivery channel constraints, aiding selection over 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 indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds value by detailing that it returns example questions from a live catalog and can be called with or without a topic. No contradictions with annotations.

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

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

The description is a single paragraph that efficiently packs all necessary information. It front-loads common user queries. However, it could be slightly more scannable with a list of topics, but overall it is appropriately sized.

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 simplicity of the tool (one optional parameter, no output schema), the description is remarkably complete. It explains the return format, usage with and without the topic parameter, and the tool's role in the overall flow, leaving no critical gaps.

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

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

Schema coverage is 100%, but the description enriches the single optional parameter by enumerating concrete topic values (finance, pharma, etc.) and explaining the behavior difference when omitted (full spread). This adds significant meaning beyond the schema.

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

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

The description clearly states a specific purpose: returning category-bucketed example questions along with the exact tool and argument shape to answer each. It distinguishes itself from the sibling tool 'ask_pipeworx' by specifying it is for onboarding and exploration, not direct answering.

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 this FIRST when you do not yet know what Pipeworx can do for you' and mentions learning meta-tools. It provides clear context but does not explicitly exclude alternative scenarios, such as when a user already knows what they want to ask.

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 value beyond annotations by explaining the deactivation (not deletion) and ownership enforcement. Annotations indicate non-destructive, idempotent write; description matches and elaborates.

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, no filler, front-loaded with core action and key constraints.

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

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

Complete description for a simple 1-param tool with no output schema. Covers purpose, behavior, ownership, side effects, and links to related tool recent_alerts.

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

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

Schema already provides clear description for the single parameter 'id'. Description adds minimal extra context beyond schema coverage of 100%.

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 provides specific verb ('Cancel') and resource ('subscription by id'), and distinguishes from sibling tools like subscribe and list_subscriptions by mentioning 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?

Clearly states when to use (to cancel own subscription) and implies exclusion of other actions, with reference to recent_alerts for historical events. Does not explicitly state when not to use.

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

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

The description adds substantial behavioral context beyond the annotations: it defines the verdict values, warns that could_not_verify means the check did not happen (with verification_error{stage,detail}) and must not be treated as evidence, clarifies unsupported, and explains it returns citations and reasoning. It also notes it replaces 4–6 sequential calls. This is rich, non-obvious behavior that directly prevents misuse.

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

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

The description is front-loaded with trigger phrases, followed by a one-sentence usage directive, then clear paths, return values, and warnings. Every sentence adds unique information: routing logic, verdict definitions, verification_error clarification, and efficiency benefit. No padding or redundancy.

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

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

For a tool with no output schema, the description covers all necessary context: what inputs look like, how it behaves internally (two paths), what the output structure is (verdict + value + citation + reasoning), edge-case semantics (could_not_verify vs unsupported), and why it's efficient. It leaves little ambiguity for an agent to invoke or interpret results.

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

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

Schema description coverage is 100%, so the baseline is 3. The tool description itself adds no unique parameter explanation—the claim examples and tolerance_pct semantics live entirely in the schema. However, the schema already thoroughly describes both parameters, including a default and cap for tolerance_pct, so the rating matches the guidance.

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

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

The description opens with concrete natural-language triggers and a clear verb-resource pair: "validate" + "claim" in "natural-language claim verification". It explicitly states the tool's scope (verifying factual claims) and distinguishes this from the many sibling research tools by focusing on a single-claim verification use case.

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

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

States plainly: "Use whenever the agent needs to check whether something a user said is factually correct." It also explains the two internal routing paths (SEC EDGAR for company financials, grounded pipeline for everything else). It does not name alternative sibling tools or provide explicit when-not-to-use rules, but the trigger phrases and scope give a clear context.

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