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?

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds valuable behavioral context: it routes questions, fills arguments, returns structured answers with stable pipeworx:// citation URIs, and mentions it is a single fast call — all beyond the annotations. It doesn't contradict the annotations. The extra detail about citations and speed is relevant for an agent's expectation management. A 4 is warranted because the description supplements, not just restates, the annotations.

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

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

The description is long but every sentence carries meaning: scope, examples, differentiation, and usage guidance. It front-loads the core instruction ('PREFER OVER WEB SEARCH') and then layers in detail. There is a slight redundancy between 'START HERE' and the preceding sentence about being the default entry point, but overall it is efficiently organized and earns its length. No filler.

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

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

Considering the tool's complexity (many domains, multiple siblings, no output schema), the description comprehensively covers when and how to use it, gives concrete examples, and points to alternatives. It states the return format (structured answer with citation URIs) even without an output schema. The only minor gap is not detailing pagination or any edge-case limitations, but given the annotations and the clarity of the description, it is sufficient for correct usage.

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% — every parameter (the required 'question' and its aliases) is described in the schema, including the fact that aliases are accepted. The description itself doesn't add semantic details about the parameters beyond what the schema already says; it implies natural-language input through examples, but that's minor added value. With high schema coverage, the baseline of 3 applies, and the description doesn't compensate beyond that.

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 an explicit verb ('routes the question') and a very specific resource scope: authoritative structured data across 5,621 tools across 1,472 verified sources. It names concrete domains (SEC filings, FDA drug data, FRED/BLS, etc.) and differentiates itself from siblings like ask_pipeworx_grounded and deep_research. It also gives example queries, leaving no ambiguity about what the tool does.

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

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

The description explicitly says 'PREFER OVER WEB SEARCH' and lists when to use it ('whenever the user asks

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

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

Annotations already establish read-only, open-world, idempotent, and non-destructive behavior. The description adds valuable behavioral context: candidate routing improvements are enabled live when under test, no candidate is active right now, and it does not fall back to a separate backend—it is a full working router. This meaningfully prevents potential misconceptions.

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 beta relationship and then gives relevant operational context about candidate status and fallback behavior. It is slightly verbose with details like the retirement date, but each sentence contributes useful context rather than repeating schema or annotation 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 beta variant that is currently identical to its stable sibling, the description covers the essential operational context: current candidate state, exact relationship to ask_pipeworx, and confirmation that it is a fully functional router. It relies on familiarity with ask_pipeworx for deeper detail, but that is reasonable given the explicit identity relationship.

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 input schema fully documents the parameters and aliases for question. The description adds that the tool accepts the same arguments as ask_pipeworx, but does not need to restate parameter details since the schema already carries that burden.

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

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

The description clearly identifies this as the beta variant of ask_pipeworx, an identical universal router with the same tools, arguments, and response shape. It differentiates itself from the stable sibling by emphasizing experimental routing improvements and the current inactive candidate state, leaving no ambiguity about what the tool does.

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

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

The description explicitly says to use it exactly like ask_pipeworx when wanting the newest routing, and explains that results are compared against the stable router. It implies that ask_pipeworx is the stable alternative, but does not directly state when not to use it or mention ask_pipeworx_grounded as another alternative.

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 read-only/idempotent annotations, the description discloses the extraction mechanism, the exact success and refusal return shapes, the specific refusal reasons, and the extra LLM call cost. This gives the agent a clear model of how the tool behaves and when it will decline to answer.

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: what the tool is, how it works, what it returns, when to use it, and when to choose the sibling instead. It is front-loaded with the most important differentiating feature and includes no filler.

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

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

With no output schema present, the description compensates by explicitly defining both the success response structure and the refusal response structure. Combined with full schema coverage for parameters and clear routing guidance, the agent has everything needed to invoke and interpret this tool correctly.

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

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

The input schema already fully documents the single required question parameter and all six aliases, so the description does not need to repeat that. However, it also adds no additional parameter-level guidance beyond what the schema provides, so a baseline score of 3 is appropriate.

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

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

The description begins with a specific, distinctive purpose: a hallucination-resistant, grounded answer mode for high-stakes reads. It explicitly contrasts itself with ask_pipeworx, making it immediately distinguishable from the closest sibling tool.

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

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

The description gives explicit when-to-use guidance: use whenever the answer will be quoted, cited, or acted on, and the agent must not invent facts. It also names the alternative and tells the agent to prefer ask_pipeworx for casual lookups.

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 already mark it read-only/idempotent, but the description goes far beyond: account/paywall constraints, parallel facet routing, output packet structure, gap[]/contradictions[] behavior, citation_uri fetchability guarantee, semantic excerpting, and latency expectations. No contradiction with annotations.

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

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

Long but information-dense; every sentence earns its place. The most critical caveats (account requirement, not open-web, sibling routing) are front-loaded, followed by behavior and latency.

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

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

Given no output schema, the description fully specifies the return packet shape, edge cases (gaps, contradictions, citations only when resolvable), and time expectations. Nothing necessary to call it correctly is missing.

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

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

Schema description coverage is 100% and the schema already details both `question` and `depth` (including enum meanings and paid-plan implications). The description repeats some of that context but does not add new parameter-level semantics beyond a few illustrative question examples.

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

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

States a specific verb ('research'), a clear resource (Pipeworx's 1472 structured data sources), and explicitly contrasts with open-web search. Differentiates from ask_pipeworx by targeting broad/multi-part questions.

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 use this tool (broad/multi-part structured-data questions), when to use ask_pipeworx instead (single lookups, breaking/current-news topics), and gives a concrete sign-up/sign-in prerequisite with a fallback for unauthenticated users.

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 indicate readOnly, openWorld, idempotent, non-destructive. The description adds valuable behavioral context: it fans out across multiple sources, notes a patent API sunset with soft-fail, describes return fields (cik, filings, fundamentals, etc.), and clarifies fallback mechanisms. 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 fairly long but well-structured, starting with example queries, then usage guidance, then detailed return info. Every sentence adds value; no fluff. Slightly longer than ideal but packed with necessary context.

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

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

Despite no output schema, the description thoroughly lists what the tool returns (cik, filings, fundamentals, patents, news, LEI) and mentions important caveats (patent sunset, name limitation). Given the tool's complexity and lack of output schema, this is complete and actionable.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds extra meaning by reinforcing that value must be ticker or zero-padded CIK (not names) and that type is limited to 'company' for now. This goes beyond the schema's own descriptions.

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

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

The description uses specific verbs like 'brief me on', 'full cross-source profile', and clearly identifies the resource as US public company data. It distinguishes from sibling tools by explicitly contrasting with chaining single-pack lookups and referencing resolve_entity for names.

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 'ALWAYS PREFER over chaining single-pack lookups when the user asks for a holistic view' and clarifies that names are not supported, directing users to resolve_entity first. This gives clear when-to-use and when-not-to-use guidance.

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

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

Annotations 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?

Adds detailed behavioral context beyond readOnlyHint annotations: explains compatibility fields, temporal alignment, and cross-type skipping. 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?

Front-loaded with purpose and modes, but somewhat verbose with detailed counters. Well-structured with clear sections (MODES, RESPONSE, SAFETY FIELDS). Minor conciseness concerns.

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?

Fully explains response structure (leg-by-leg prices, top spreads_pp), safety fields, and temporal alignment. No output schema, so description compensates thoroughly.

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

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

Schema coverage is 100%, and description adds meaning by explaining modes (topic vs explicit) and parameter overrides. Slight redundancy with schema examples, but overall adds value.

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

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

The description clearly states the tool computes cross-venue spread between Kalshi and Polymarket for the same resolving question, distinguishing it from siblings like polymarket_arbitrage by focusing on inter-venue comparison.

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

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

Explicitly describes two modes (topic shortcuts and explicit tickers), provides specific cases where spreads are meaningless (e.g., compatibility_warning, temporal alignment), and warns that pre-mapped doesn't guarantee tradeability.

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?

Annotations already establish readOnly, idempotent, openWorld, non-destructive. The description adds valuable behavioral context: internal cascading through multiple endpoints, graceful degradation if GLEIF/OpenFIGI are unavailable, and that unresolved identifiers are explicitly listed under an `unresolved` key. This enriches the agent's understanding beyond the annotation set.

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, opening with examples and the core purpose. It uses inline lists and parenthetical explanations effectively. While longer than necessary, each sentence adds functional detail (e.g., graceful degradation, unresolved reporting). Slightly verbose, but no filler.

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

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

Despite no output schema, the description explains the return structure (labelled identifiers per source, explicit unresolved array). It covers both entity types with specific identifier details, input formats, and fallback behavior. Given the tool's complexity (multiple datasources, cascading lookups, edge cases), the description provides a thorough mental model for correct invocation.

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

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

Schema coverage is 100%, but the description adds detailed meaning: for the 'type' parameter it explains what identifiers each type returns (CIK, ticker, LEI, FIGI for company; RxCUI, ingredient, brand for drug) and for 'value' it lists accepted formats (ticker, CIK, ISIN, name for company; brand/generic for drug) including edge cases like ISIN-to-LEI resolution. This goes far beyond the simple 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 starts with concrete user queries ('What's the ticker for…') and a clear verb+resource pairing: 'resolve a user-spoken NAME to the canonical/official identifiers'. It implicitly distinguishes from siblings like entity_profile and compare_entities by positioning itself as the first step ('Use FIRST whenever you have a name but need an ID').

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

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

Explicitly states when to use: 'Use FIRST whenever you have a name but need an ID.' Provides real-world query patterns (ticker, CIK, LEI, drug name) and states that one call replaces multiple manual lookups. Does not list alternatives but the usage rule is clear and actionable.

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.