caruon

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds valuable behavioral context: the default model is Workers AI Llama-3.3-70b (free), passing _apiKey probes Anthropic with direct payment to Anthropic, and the return format includes per-model score, confidence, signals, raw_response, plus a combined view. This goes beyond the 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 a compact two-sentence block that front-loads the core purpose and then packs in return structure, default behavior, costs, and use cases. Every sentence carries meaningful information with no redundancy or 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?

For a read-only probe tool with annotations covering safety, the description fully explains what the tool does, what it returns, when to use it, and the optional configuration. No output schema exists, but the description explicitly lists the return fields (score, confidence, signals, raw_response, combined view), making the tool self-contained and easy 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?

The schema covers all 4 parameters with descriptions, satisfying the baseline. The description adds extra meaning by clarifying that _apiKey is only needed when 'anthropic' is in models and that it's passed straight through to api.anthropic.com, plus the default model context for the 'models' parameter. This is value beyond the schema.

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

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

The description clearly states the tool's function: 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' This is a specific verb+resource combination ('probe... LLMs', 'score visibility') that distinguishes it from sibling tools like ask_pipeworx (which is for chatting) and scan_competitor_ai_presence (which likely focuses on a different scanning approach).

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 usage context: 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also explains operational choices (default model, optional API key for Anthropic). It doesn't explicitly name alternatives or say when NOT to use it, but the context is sufficiently clear for an agent to select it appropriately.

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 readOnly, openWorld, idempotent, and non-destructive behavior. The description adds valuable behavioral context beyond this: it routes across thousands of tools, fills arguments, returns structured answers with stable pipeworx:// citation URIs, and claims to work on every tier with 'one fast call'. This exceeds baseline annotation disclosure, though it doesn't discuss failure modes or rate limits.

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

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

The description is long but densely packed with actionable information: preferred usage, alternatives, examples, and scope. It is front-loaded with a strong directive ('PREFER OVER WEB SEARCH') and organized in a logical flow from recommendation to exceptions. While every sentence earns its place, it could be slightly tightened without losing value.

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

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

Given the tool's high complexity (meta-router over 5,462 tools with no output schema), the description is remarkably complete. It covers what the tool does, when to use it, when not to, provides diverse examples, and mentions the return format (structured answer with citation URIs). The only minor absence is error-handling detail, but this is not critical for a selection decision.

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

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

Schema description coverage is 100% with all six parameters clearly described as aliases for 'question'. The description itself adds no new parameter semantics beyond what the schema already provides, but the examples illustrate realistic usage. Baseline 3 is appropriate because the schema carries the full parameter documentation burden.

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

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

The description clearly identifies a specific verb+resource: routes questions to one of 5,462 tools across 1,419 verified sources and returns structured answers with citations. It distinguishes itself from siblings by naming ask_pipeworx_grounded and deep_research as alternatives for different needs, and explicitly states it is the default entry point.

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

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

Provides explicit when-to-use guidance ('PREFER OVER WEB SEARCH', 'START HERE for most questions'), when-not-to-use ('Step up only when needed'), and names specific alternatives (ask_pipeworx_grounded for hallucination-resistant answers, deep_research for broad/multi-part questions). Also clarifies breaking-news handling and gives concrete example queries.

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

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

Beyond the readOnly/idempotent annotations, the description discloses the experimental nature ('candidate routing improvements enabled live'), the current inactivity ('No candidate is active right now'), and that it fully works ('Falls back to nothing — this IS a full working router'). This adds valuable context about potential behavior changes and trustworthiness.

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 and front-loaded with the core purpose. It is mostly concise, though the repetition of 'identical' and 'same 5,462 tools, same arguments, same response shape' is slightly redundant. The specific retirement date adds useful current-state context but could be trimmed.

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

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

For a complex universal router, the description covers the key aspects: what it does, current operational state, how to use it, and its relationship to the stable version. However, it relies on the sibling ask_pipeworx for response shape details and doesn't explicitly describe the output format or routing behavior further, which would be helpful given 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?

The schema already covers 100% of parameters with descriptions and aliases. The description adds minimal parameter information beyond stating 'same arguments' as ask_pipeworx, which is redundant given the schema is present. 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 function: it is a beta version of ask_pipeworx, acting as an identical universal router with the same 5,462 tools and arguments. It distinguishes itself from the sibling ask_pipeworx by its experimental routing improvements and explicitly frames it as a full working router, not a stub.

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 guidance: 'Use it exactly like ask_pipeworx when you want the newest routing' and mentions results are compared against the stable router. It also clarifies the current state (no candidate active) and that it matches ask_pipeworx exactly, making the decision context clear.

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

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

Goes beyond annotations by detailing the refusal mechanism (explicit refusal_reason codes), the guarantee of using only contained tool results, and the extra LLM call cost. Annotations declare read-only and non-destructive, and the description adds rich behavioral context consistent with those 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 compact yet complete: purpose, routing, output format, refusal behavior, use cases, and tradeoff are each covered in a single sentence. Front-loaded with the core definition, every sentence adds value.

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

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

Despite lacking an output schema, the description fully specifies the return object and refusal reasons, making it self-sufficient. It also covers cost implications and high-stakes use cases, so an agent can confidently select and invoke the tool.

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

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

Schema coverage is 100% with all 6 parameters documented as aliases for 'question.' The description adds no parameter-specific detail beyond the schema, but the schema's alias explanation is sufficient; baseline 3 applies.

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

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

The description opens with a specific verb+resource: 'Hallucination-resistant answer mode for high-stakes reads,' and clarifies it extracts answers only from tool results. It distinguishes itself from sibling ask_pipeworx by explicitly referencing 'Same routing as ask_pipeworx' and contrasting 'prefer ask_pipeworx for casual lookups.'

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

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

Provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts,' with concrete examples (financial, legal, medical). It also names the alternative tool and when to prefer it: '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 goes far beyond the annotations (readOnly, openWorld, idempotent, non-destructive) by detailing response shapes, resolver confidence contracts, safety short-circuit behaviors, closed-market statuses, wide-spread tradeability flags, and cancellation-rule risk. It even warns to inspect resolver fields before trusting analysis. This is rich behavioral context that fully informs the agent, 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 front-loaded with a one-sentence summary, then uses labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.) to structure dense information effectively. While some repetition exists (e.g., fan-out examples), the structure and section headers make it navigable and each section adds substantive value.

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

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

With no output schema, the description thoroughly documents return values: market fields, analysis edge, evidence keys, resolver confidence, parent-event extractor, news fallback fields, and status codes. It also covers safety and error paths (low-confidence matches, closed markets, wide spreads) and resolution-rule risks. This is a complete operational specification for a complex fan-out tool.

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

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

The input schema declares 3 parameters with 100% description coverage, including examples and defaults. The tool description mostly repeats the same input formats (slug/URL/question) and adds fan-out examples, but it does not materially alter how an agent should set each parameter beyond the schema. 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 opening sentence 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call' clearly specifies the verb (research), resource (Polymarket bet), and scope (Pipeworx data). It also lists concrete use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') and includes classification and fan-out details that distinguish it from siblings like deep_research or ask_pipeworx.

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

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

The description explicitly states 'Use for ...' with three common query patterns, giving clear context for when to invoke the tool. It also provides category-specific fan-out examples, which further clarify usage. However, it does not explicitly mention when not to use it or name alternatives, so it stops 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?

Even though annotations declare readOnly/openWorld/idempotent, the description adds substantial behavioral context: it pulls from SEC EDGAR/XBRL for companies and FAERS/FDA/trials for drugs, correctly handles off-calendar fiscal years, sorts by the primary metric, and returns paired data with pipeworx:// citation URIs. This goes far beyond the annotations and clearly sets expectations for result content and 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 dense and structured well, starting with user phrasings and moving to a clear verb+resource statement, then type-specific details, then output characteristics. It's longer than some, but every sentence carries operational value; a minor tightening of the phrase 'off-calendar fiscal years handled correctly' could make it more concise, but overall structure supports quick scanning.

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

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

The description is complete for a read-only comparison tool: it covers supported entity types, data sources, result formatting (sorted by primary metric, paired data, citation URIs), and explicitly frames the tool's place relative to sequential lookups. With no output schema present, describing the return format inside the description sufficiently compensates for the missing structured output metadata.

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

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

The schema already provides 100% coverage for both parameters, but the description enriches the semantics: it specifies exactly what financial data items are pulled for company type (latest 10-K revenue, net income, cash, long-term debt) and what counts are pulled for drug type, and clarifies how 'values' maps to tickers/CIKs or drug names. This helps the agent construct correctly formatted inputs with confidence.

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

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

The description immediately establishes the tool's purpose with concrete query examples ('Compare X and Y', 'X vs Y') and clearly states it performs side-by-side comparison of 2–5 companies or drugs in one parallel call. It distinguishes itself from singleton lookups by emphasizing 'in ONE parallel call' and 'ALWAYS PREFER over sequential single-pack lookups', making its unique value clear relative to sibling tools like entity_profile.

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

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

The description gives explicit when-to-use guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and provides examples of triggering queries. It also differentiates between company and drug types with data sources, and notes it 'Replaces 8–15 sequential lookups,' effectively telling the agent when not to use 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?

Even though annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, the description adds substantial behavioral context: it decomposes questions into facets, routes to 5,462 tools in parallel, returns explicit gaps[] rather than inventing answers, includes a hop field and citation_uri that is always fetchable, excerpts semantically, and reports latency expectations (15-60s, up to 90s). It also discloses the depth-dependent contradiction[] and gap-recovery behavior, which the annotations do not capture. No contradiction with annotations.

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

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

The description is dense but effectively front-loaded: the account requirement and critical alternative are immediately stated, followed by the core purpose in the first sentence. Every sentence carries operational value. However, it is quite long (roughly 200 words) and some details (e.g., listing all data source categories, 5,462 tools) could be trimmed without losing essential guidance. Still, the structure uses clear signposting and no redundant 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?

For a complex tool with only 2 parameters, no output schema, and no nested objects, the description is remarkably complete. It explains what the tool returns (findings packet with verbatim evidence, confidence, source, fetched_at, stable citation, gaps[], contradictions[]), how it behaves over multiple hops, latency expectations, auth requirements, and exactly when it should NOT be used. The sibling context is rich and the description successfully differentiates against ask_pipeworx and other siblings.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes beyond the schema by explaining the behavioral implications of each depth value: 'quick=3 (single hop)', 'standard=5... adds a gap-recovery hop... plus a contradictions[] scan', and 'thorough=8 (paid; adds a full iterative hop... plus the contradictions[] scan)'. It also clarifies that broad/multi-part questions are acceptable, adding meaning to the 'question' parameter beyond the schema's generic description. Minor deduction because the exact facet counts and hop mechanics are only lightly tied to the parameters.

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 strong verb+resource statement: 'Grounded multi-source research across Pipeworx's 1419 STRUCTURED data sources... in ONE call' and immediately distinguishes this from open-web search and sibling ask_pipeworx. It also clearly enumerates what deep_research is for ('best for broad/multi-part questions over structured data') with concrete examples, making its purpose unmistakable.

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

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

The description provides explicit when-to-use and when-not-to-use guidance: it says to use ask_pipeworx for single lookups, for BREAKING/colloquial current-news topics, and whenever the user is not signed in. It names the alternative tool directly and explains why deep_research would return empty gaps[] in those cases. It also covers the account requirement and paid tier for 'thorough' depth, giving full decision 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?

The annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds that it 'Returns the top-N most relevant tools with names, descriptions, and full input schemas,' which clarifies the output behavior. It is consistent with annotations and adds useful context about the result format and readiness to call directly.

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 primary action, uses brief enumerations, and avoids redundant filler. The three sentences each add distinct value: purpose, usage scenarios, and output details.

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 adequately explains what the caller receives (top-N tools with full schemas) and how to use it (provide a natural-language query). It doesn't discuss limit defaults, but that is captured in the parameter schema, so the description is sufficiently complete.

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

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

Schema coverage is 100% and all parameters are well-documented as aliases. The description reinforces the natural-language query expectation ('describing the data or task') but adds little beyond the schema, which is acceptable given the high coverage.

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 'Find tools by describing the data or task,' clearly indicating the tool's function as a discovery/search utility. It distinguishes itself from sibling domain-specific tools by enumerating the domains it covers and framing itself as a lookup for available tools.

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

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

It explicitly states 'Use when you need to browse, search, look up, or discover what tools exist' and advises to 'Call this FIRST when you have many tools available.' This provides clear when-to-use guidance and implicitly contrasts with directly calling a known 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?

Annotations already declare readOnly/openWorld/idempotent, but description adds behavioral specifics: fans out across five sources, returns five named data groups, patents 'soft-fails until reactivated' due to USPTO API sunset, news uses GDELT→GNews fallback, and results are returned in a single parallel call. 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 densely informative; it front-loads typical user queries and then systematically lists sources, return fields, and constraints. No filler sentences, though slightly over-packed for a quick scan.

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

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

No output schema exists, so the description carries the burden of explaining return values—it does so explicitly (cik, recent_filings with URIs, fundamentals with field names, patents status, news fallback, LEI). Input constraints and fallback behavior are fully covered.

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% description coverage for both params (type and value), with examples and the name-not-supported caveat. The description echoes the same parameter guidance and adds query-phrase examples, but no new semantic depth beyond the schema, so 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 opens with concrete use cases ('Tell me about X' / 'research Acme') and a precise definition: 'full cross-source profile of a US public company in ONE parallel call.' It explicitly contrasts with chaining single-pack lookups and mentions resolve_entity for name-only queries, distinguishing it from siblings.

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 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' Also provides an exclusion: 'names not supported (use resolve_entity first if you only have a name).' This is explicit when-to-use and when-not.

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 destructiveHint=true and idempotentHint=true, so the description carries a lighter burden. It adds useful context by framing the deletion as clearing 'previously stored' memory and 'sensitive data', implying permanence and a privacy rationale. It does not contradict annotations.

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

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

The description is two compact sentences: the first states the core operation, the second gives usage conditions and sibling pairings. Every sentence earns its place with 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 well-documented parameter, strong annotations (destructive, idempotent), and no output schema, the description fully covers the what, when, and how it relates to other tools. There are no significant gaps in context for an agent to invoke it correctly.

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

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

The input schema has 100% coverage: the key parameter is described as 'Memory key to delete'. The description's phrase 'by key' adds no additional meaning beyond the schema, so the baseline of 3 is appropriate.

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

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

The description opens with 'Delete a previously stored memory by key' — a specific verb and resource that clearly states the operation. It distinguishes from siblings like remember (store) and recall (retrieve) by focusing on deletion, so the purpose is 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 explicitly states when to use the tool: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also names companion tools ('Pair with remember and recall'), providing direct guidance relative to alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description complements these by explaining the fetch-extract-emit process and the output as a single text blob in standard llms.txt format, adding useful behavioral context without contradicting 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 concise and well-structured, with the main purpose front-loaded in the first sentence, followed by output details and use cases. Every sentence adds value and there is no redundancy.

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

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

For a simple tool with two parameters and comprehensive annotations, the description covers purpose, process, output, and use cases. It could mention error handling for inaccessible URLs, but overall it is sufficiently complete for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100% for both parameters (url and max_links), so the baseline is 3. The description mentions 'any URL' but does not add additional meaning beyond the schema's parameter descriptions.

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

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

The description clearly states it generates a production-ready llms.txt file for any URL, with a specific process (fetches, extracts, emits) and output format. This distinguishes it from sibling tools like ai_visibility_check and scan_competitor_ai_presence, which focus on analysis rather than generation.

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

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

The description provides explicit use cases (getting a client's site indexed, drafting llms.txt, auditing competitor visibility) through the 'Useful for:' list. It does not mention alternatives or when not to use the tool, but the context is clear.

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

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

Annotations already declare the tool as read-only and non-destructive. The description adds useful behavioral context by specifying 'current' and 'real-time', indicating the data is a live snapshot rather than historical. It also enumerates the energy sources included (gas, coal, wind, etc.), clarifying the scope of the returned data beyond what annotations provide.

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

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

The description is two short sentences, front-loaded with the action and resource. The first sentence states the core purpose and lists data sources; the second gives a brief use case. No unnecessary words or repetition.

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

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

For a simple read-only tool with no parameters and an output schema, the description covers all needed context: what it does (grid mix by source), geographic scope (UK), temporal nature (current/real-time), and a use case. The annotation and output schema fill in safety and return-structure details, so nothing critical is missing.

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

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

The tool has zero parameters and the schema is trivially complete. With no parameters to document, the baseline is 4. The description needs no additional parameter information, and it does not attempt to invent any.

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

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

The description clearly states the tool's function: 'Check current UK electricity grid composition by source percentage.' It specifies the exact resource (UK grid mix) and the data provided (source percentages for gas, coal, wind, etc.). This distinguishes it from related sibling tools like get_intensity, which focus on carbon intensity rather than generation mix.

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 usage context: 'Use to understand real-time grid energy mix.' It implies this tool is for real-time generation mix queries. However, it does not explicitly mention alternatives or when not to use it, such as for historical data or regional breakdowns, which are covered by sibling tools like get_intensity_by_date or get_regional_intensity.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, but the description adds useful behavioral details like returning forecast and actual values and the intensity level range. This goes beyond annotations by explaining the output semantics 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?

Two sentences, first states purpose and return values with specific units, second gives a primary use case. No wasted words, well front-loaded.

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

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

Given the tool is a simple no-parameter read, the description fully covers what it does, what it returns, and why it might be used. The output schema exists but the description already explains the key return fields (forecast, actual, level).

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 tool has zero parameters, and the schema is 100% covered (empty). The description adds the contextual meaning of 'current' (as opposed to historical or regional), which is inherently the parameter space. Although it doesn't explicitly state 'no parameters,' the description implies that only current data is returned, which is enough.

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

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

The description clearly states the tool checks current UK electricity carbon intensity, with specific output units (gCO2/kWh) and forecast/actual distinction. It distinguishes itself from siblings like get_intensity_by_date and get_regional_intensity by specifying 'current UK' and the return of both forecast and actual readings.

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

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

It explicitly says to use it 'to schedule energy-intensive tasks during low-carbon periods,' which is a clear use case. It doesn't mention alternatives or exclusions, but for a simple no-parameter tool, this is sufficient context for typical usage.

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

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

Annotations already declare read-only and idempotent behavior, so the description adds value by disclosing output details: 30-minute intervals, gCO2/kWh units, forecast and actual values. This gives more context about what the tool returns 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 two concise sentences, front-loaded with the primary action and example, followed by a use case. Every word adds value with no redundancy.

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

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

For a simple one-parameter read-only tool with an output schema, the description covers what it returns, the granularity, and an example. It also suggests a practical use case. No further explanation of return values is needed given the output schema exists.

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

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

Schema coverage is 100% with a clear description for the date parameter. The tool description repeats the format and gives an example but does not add meaningful semantic details beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description clearly states the tool retrieves UK electricity carbon intensity for 30-minute periods on a specific date, with a concrete example. It distinguishes itself from siblings by specifying the date-based granularity and return of forecast/actual values.

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 a clear use case: 'Use to identify lowest-carbon hours.' However, it does not explicitly name alternatives or explain when not to use this tool versus siblings like get_intensity or get_regional_intensity, so it lacks 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint as safe. The description adds useful context about units (gCO2/kWh), per-fuel-type scope, and example values, but does not describe return format or any data volatility. No contradiction exists.

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

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

The description is a single, front-loaded sentence with concrete examples. Every word earns its place; there is no redundancy or 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?

For a simple zero-parameter lookup, the description provides units, scope, and example values. It could be more explicit about the exact return format (e.g., object mapping), but the examples and context are sufficient for a task of this simplicity.

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

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

The tool has zero parameters and schema coverage is complete. Per the rubric, a 0-parameter tool gets a baseline of 4; the description does not need to add parameter details since none exist.

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

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

The description clearly states that the tool returns carbon intensity factors per fuel type, with units and example values. This distinguishes it from sibling tools like get_intensity and get_regional_intensity by emphasizing the per-fuel-type breakdown and headline-figure context.

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

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

No explicit guidance is given on when to use this tool versus the sibling tools. The phrase 'used in the headline figures' implies a context, but it does not mention alternatives or exclusions, such as 'use get_intensity_by_date for date-specific values'.

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

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

Annotations already mark the tool as read-only, open-world, idempotent, and non-destructive. The description adds valuable behavioral context: 'Regional figures are forecast-only' and 'Omit both for all regions at the current half-hour,' which explain data nature and no-arg behavior. It does not describe error responses or pagination, but with annotations covering safety, this is adequate.

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: purpose, usage, and caveat. Every sentence earns its place; no redundant information. It is front-loaded with the core function.

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 compensates by telling the agent exactly what data is returned (carbon intensity forecast + index band, generation mix) and how to select regions. The forecast-only caveat sets appropriate expectations. It is complete for a two-parameter read-only tool, though it doesn't discuss error cases or data limitations.

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

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

The schema already has 100% coverage with descriptions and examples for postcode and regionid. The description adds the crucial instruction that omitting both parameters returns all regions, which is not in the schema. It also clarifies that either parameter can be passed, reinforcing the schema's optional nature. This goes above the baseline for fully-covered schemas.

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: 'Carbon intensity (forecast gCO2/kWh + index band) and generation mix for a specific Great Britain region.' This clearly distinguishes it from sibling tools like get_intensity (likely national) and get_generation_mix by combining regional scope and both data types.

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

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

The description gives clear instructions: 'Pass "postcode"... or "regionid"... Omit both for all regions at the current half-hour.' It does not explicitly name alternatives, but the regional scope and forecast-only caveat imply when this tool is appropriate. A missing explicit reference to sibling tools prevents a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the tool is known to be a safe read operation. The description adds meaningful context by specifying it lists the caller's subscriptions (not all system-wide), returns only active ones by default, and enumerates the exact fields returned, going beyond the annotation-only picture.

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

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

The description is two sentences, with the first clearly stating the action and output fields and the second providing practical usage advice. Every sentence is informative with no redundancy or 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?

For a simple one-parameter read-only list tool with no output schema, the description supplies the essential return fields, the default filtering behavior, and a clear use case. It is complete enough for an agent to select and invoke the tool correctly without further clarification.

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 has 100% coverage for the only parameter, include_inactive, with a description. The tool description does not add extra parameter semantics beyond what the schema already provides, so 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 clearly states the tool lists the caller's active subscriptions, which is a specific verb + resource. It distinguishes itself from the sibling tools subscribe and unsubscribe by focusing on listing, and it also explicitly lists the fields returned.

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 usage context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This clearly indicates when to use the tool, though it does not explicitly mention alternatives or when not to use it, so it misses a small piece of the highest benchmark.

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

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

Annotations are all false, so the description carries the burden. It adds meaningful behavioral context beyond annotations: 'Rate-limited to 5 per identifier per day. Free; doesn't count against your tool-call quota' and 'The team reads digests daily and signal directly affects roadmap.' This clarifies side effects and constraints. It could mention what the response looks like, but that is not critical for a feedback submission tool.

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

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

The description is longer than the bare minimum but front-loaded with the core purpose and efficiently organizes subsequent guidance (when to use, exclusions, rate limit). Every sentence carries useful information; however, some phrasing could be tightened without losing value, preventing a perfect score.

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

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

For a feedback tool, the description is complete: it covers purpose, trigger scenarios, exclusions, rate limits, quota impact, and expected content of the feedback. No output schema exists, but the tool's return value is unlikely to be complex enough to need documentation. The description fully equips an agent to know when and how to invoke it.

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 practical parameter guidance beyond the schema: it maps enum values to real-world triggers (e.g., 'returns wrong/stale data' = bug), and instructs users to 'Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt.' This helps correctly fill 'type', 'context', and 'message'.

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: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It names the specific resource (Pipeworx team) and distinguishes itself from sibling data/research tools by explicitly limiting it to only Pipeworx-served tools and explaining the feedback categories.

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?

Usage is explicitly guided: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also provides a clear exclusion (do not use for other MCP servers' tools) and an alternative action ('file it with that server instead').

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 context beyond the annotations: it reveals the underlying source ('CF analytics-engine'), guarantees privacy ('no PII'), specifies data shape ('just (pack, tool, count)'), and states caching behavior ('Cached 5min-1h depending on window'). These details go beyond the readOnly/idempotent hints and give the agent a clear behavioral model.

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 efficient, front-loading the primary purpose in the first sentence and structuring the 'Useful for' list for skimmability. It is slightly verbose with the numbered use cases, but every sentence contributes value, so it earns a 4 rather than a 5.

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 single optional parameter and no output schema, the description is fairly complete: it names the output fields, data provenance, caching, and privacy. It stops short of describing exact response formatting, but that is not critical for a simple trend read.

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

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

The schema already documents the only parameter (window) with enum values and explains the tradeoff between short and long windows, so the description adds minimal new meaning. It merely echoes the options without enriching them beyond schema coverage, keeping this at 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 clear question and answer: 'What other AI agents are calling on Pipeworx right now,' followed by an explicit statement of what it returns ('top tools, top packs, and total call volume'). This distinguishes it from sibling tools like discover_tools by emphasizing aggregate usage signal rather than a directory of tools.

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

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

The description provides three explicit use cases: discovering hot data sources for current events, confirming a canonical tool, and checking alignment with other agents' needs. However, it does not mention when not to use it or name alternative tools, so it lacks exclusionary guidance.

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

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

The description goes far beyond the annotations by detailing exact behaviors: partition-check thresholds, placeholder filtering, semantic similarity requirements, fill-check logic, and the instruction not to trade when realizable_edge_pp ≤ 0. This is rich contextual disclosure that annotations alone would not provide.

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

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

The description is long but appropriately so for the tool's complexity. It is front-loaded with the core purpose, then organized into labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) that make it easy to scan. Every sentence adds operational detail; there is no fluff.

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

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

Even without an output schema, the description fully explains the response shape (opportunities[], partition_check{}, fill_check details), critical filters, and decision recommendations. It covers all relevant behaviors, limitations, and prerequisites, making it self-sufficient for an agent to invoke the tool correctly.

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

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

Although the schema already covers 100% of parameters with detailed descriptions, the tool description adds substantial meaning by explaining how each parameter changes the mode (event vs topic vs default), how slugs are used, and what kind of input is expected (e.g., full URLs also accepted). This goes well beyond the schema's static 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 opens with a specific verb+resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly defines the tool's scope and distinguishes it from siblings like polymarket_edges and polymarket_fill_risk by naming specific methods and modes.

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 usage guidance: call with no args for trending_scan, use 'event' for a specific market, use 'topic' for cross-event scanning. It even recommends when each mode is best ('event (recommended for a specific market)') and references the alternative tool polymarket_fill_risk for custom sizing.

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

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

The description offers extensive behavioral detail beyond the annotations: it explains the three model families, edge_pp_net and slippage calculations, Kelly caps, liquidity/spread filters, diagnostics funnel counters, and KV-level caching. Annotations declare readOnly/idempotent/non-destructive, and the description adds rich context about what the tool computes and returns, making behavior very transparent.

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 and very long, with many run-on parentheticals and lists. It is somewhat structured via CAPS section labels, but it could be far more scannable with bullet points or line breaks. Every sentence carries information, but the overall format is not concise or well-organized for quick consumption.

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

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

With no output schema, the description fully documents the response structure: by_segment with three segments, fed_candidates/fed_note, and _diagnostics with funnel counters. It also explains edge fields, slippage, Kelly caps, and caching. For a tool of this complexity, the description is extremely complete and leaves little ambiguity about what the agent will receive.

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 provides 100% coverage with detailed descriptions for all 9 parameters. The description adds extra semantic value by explaining how knobs interact, e.g., min_liquidity/max_spread_pp drop unrealizable edges and the nuance that partition arbs have kelly_fraction_half=0 at the parent level, which clarifies min_partition_leg_kelly. This goes 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 the tool scans top Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. It names the three model families and the by_segment output, establishing a distinct purpose. However, it does not explicitly name sibling tools or contrast with them, so it stops short of full sibling differentiation.

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: 'what should I bet on today' and notes it avoids paging hundreds of markets. It also includes behavioral caveats, like Fed bets being excluded from ranking and the 24h-move warning. It does not explicitly state when not to use this tool or point to alternative sibling tools, so it lacks explicit exclusion guidance.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantial behavioral context: 60-day snapshot TTL, snapshot gaps due to cache-miss behavior, and that decay numbers are computed from daily closes rather than intraday. It also explains what happens to expired opportunities (closed, resolved, or arbed away).

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 into purpose, args, response, and limits sections. Every sentence contributes useful information about what the tool returns, how to interpret the data, and its limitations. It is front-loaded with the core purpose.

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

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

With no output schema, the description carries a heavy burden and fully delivers: it specifies the exact shape of tracked[], expired[], and snapshot_dates[], defines each field (edge_pp_net, trend, decay_pp_per_day, lifespan_days), and covers caveats such as TTL and snapshot 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%, with both parameters already described with defaults and constraints. The description adds minor framing ('lookback', 'snapshot family') but mostly restates the same information without meaningfully enriching 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?

The description clearly states the tool's purpose: it provides edge persistence and decay telemetry from daily polymarket_edges snapshots, answering 'how long has this edge existed and is it shrinking?'. This distinguishes it from siblings like polymarket_edges by focusing on time-series behavior rather than just current edges.

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

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

The description gives strong contextual guidance, including the trade-relevant distinction between fresh and 3-week-old wide edges. However, it does not explicitly name alternative tools or state 'when not to use' this tool, so it falls slightly short of full exclusionary guidance.

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

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

Annotations already declare readOnlyHint/idempotentHint, and the description adds behavioral context: it walks the order-book ladder, returns a verdict (clean|degraded|cannot_fill), and warns about forced directional risk. It does not contradict annotations and explains the loss mode beyond what structured metadata offers.

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 long single paragraph but well-organized: purpose, mode requirements, single-market outputs, basket outputs, and usage trigger are clearly sequenced. Every sentence adds substantive info and no fluff; the length is justified by the tool's complexity.

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

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

With no output schema, the description enumerates all return fields for both modes (vwap_fill_price, slippage_pp, thin_legs[], forced_directional_risk, etc.) and explains the interpretation of inputs in each mode. Also covers defaults, restrictions, and the exact scenario where this tool is needed.

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?

Despite 100% schema coverage, the description adds critical semantics: side defaults differ by mode, size_usd is interpreted as max spend for buys vs target proceeds for sells vs settlement notional (shares per leg) in basket mode, plus the clamp range (10–1,000,000). This far exceeds the brief schema field 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 opens with a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes from sibling trade-signal tools (polymarket_arbitrage, polymarket_edges) by positioning itself as the risk-check before acting on those 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 states: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also provides the rationale: thin-book overround is not capturable, and partial basket fills convert an arb into an unhedged directional position.

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?

While annotations already declare readOnlyHint=true and destructiveHint=false, the description adds substantial behavioral context beyond that: it discloses the compatibility_warning logic, temporal alignment constraints, and skipped_cross_type/subtype counters. It explicitly states when spreads are meaningless (non-equivalent bet shapes or temporal misalignment), which is critical for safe interpretation. No contradiction with annotations.

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

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

The description is long but every sentence provides unique value: it introduces the core concept, defines two modes, explains the response format, and details safety fields. It is structured with clear labels (TWO MODES, RESPONSE, SAFETY FIELDS) that improve scannability. 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?

This is a complex tool with no output schema, so the description must carry the burden of explaining return values and edge cases. It covers leg-by-leg prices, spread computation, compatibility_warning cases, temporal alignment, and skipped cross counters. It even warns about the rarity of tradeable spreads, making the tool's limitations and behavior fully transparent 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%, so the baseline is 3. The description adds extra meaning by explaining the two operational modes (topic vs explicit override) and how kalshi_event_ticker and polymarket_event_slug override the topic-mapped sides. This goes beyond schema descriptions by clarifying the interplay between parameters, warranting a 4.

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

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

The description states a specific verb+resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' This clearly distinguishes it from sibling tools like polymarket_arbitrage or polymarket_edges by emphasizing cross-venue comparison of identical questions. It also outlines two distinct modes, making the tool's scope 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 explicitly describes when to use each mode (pre-mapped shortcuts vs explicit pairing) and provides strong exclusion guidance: 'Real cross-venue spreads are rarer than the macro-shortcut list suggests — most pre-mapped topics return compatibility_warning today; pre-mapped ≠ tradeable.' It also explains when the output is meaningful via compatibility_warning and temporal_alignment, effectively guiding the agent on when results should not be trusted.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds meaningful behavioral context beyond annotations: scoping to the agent's identifier (anonymous IP, BYO key hash, or account ID) and the listing behavior when key is omitted. This gives the agent a clearer mental model of how the tool behaves in different scopes.

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, front-loaded with the core action. Each sentence earns its place: the first states the operation, the second gives usage context with examples, and the third covers scoping and companion tools. 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 single-optional-parameter tool with no output schema, the description covers both invocation modes, scoping, and pairing with companions. It provides enough context for an agent to select and call the tool correctly without needing additional documentation. The absence of an output schema is compensated by the explicit statement that retrieving a value returns the saved value, and omitting the key lists all keys.

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 provides 100% coverage with the key parameter description ('Memory key to retrieve (omit to list all keys)'). The tool description reinforces this but adds no new parameter-level detail beyond illustrative examples of key values, which are helpful but not necessary for understanding the parameter.

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: 'Retrieve a value previously saved via remember, or list all saved keys.' It clearly distinguishes the tool from siblings by explaining its role in the remember/recall/forget family and providing concrete examples of stored context (target ticker, address, research notes).

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

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

The description explicitly states when to use this tool: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also names companion tools (remember to save, forget to delete) and differentiates retrieval from other sibling tools by focusing on previously saved memory.

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?

Annotation Contradiction: readOnlyHint=true conflicts with the described mark_read:true behavior, which flags returned events as read and changes future responses. This is a stateful mutation, directly contradicting the read-only annotation. The description adds useful return-format details, but the contradiction forces a score of 1 per rubric.

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 five sentences, each serving a distinct purpose: purpose, payload, filtering, mark_read behavior, and alternative access. It is structured logically and front-loaded, though slightly verbose. Every sentence earns its place, but brevity could be improved.

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

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

Despite having no output schema, the description covers the essential aspects: return fields, filtering, the mark_read side effect, and alternative access. It does not directly explain limit or unread_only, but those are fully documented in the schema. For a tool with this complexity, the description is adequately complete.

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

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

Schema coverage is 100% with each parameter described, but the description adds value beyond the schema: it gives a concrete type example ('sec_8k'), clarifies since as an ISO timestamp, and explains the side effect of mark_read on subsequent calls. This goes beyond 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 'Pull fired events from your subscription feed,' a specific verb+resource that clearly states the tool's function. It distinguishes itself from siblings like list_subscriptions and recent_changes by detailing the returned payload (source, citation_uri, raw event).

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 usage context: filtering options, polling suitability, and an alternative URL for scripts/dashboards. It implies when to use this tool versus the external endpoint but does not explicitly name sibling alternatives or state when not to use it, preventing a perfect score.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds valuable behavioral context: GDELT→GNews fallback on rate limiting, USPTO patents soft-fail due to PatentsView API sunset in May 2025, and that results are grouped by source. This goes well 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 fairly long but every sentence provides distinct value: sources, fallback logic, date formats, return structure, and alternative tool. It is dense rather than wasteful, though it could be tightened slightly without losing meaning.

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

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

With no output schema, the description explains the return shape (changes[], total_changes count, citation URIs). It also covers the tool's non-purpose (static profile via entity_profile) and the exact time-window semantics, making it fully complete for an agent to select and call 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 reinforces the format for `since` and `value`, and adds a practical recommendation ('Use 30d or 1m for typical monitoring') that gives extra guidance beyond the schema's dry parameter 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?

Clearly describes a change feed for a company over a time window, listing specific data sources (SEC EDGAR, GDELT/GNews, USPTO). It also differentiates from entity_profile by noting that alternative provides a static profile regardless of window.

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

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

Explicitly says when to use this tool vs entity_profile, and provides example query phrasings. It also notes fallback behavior (GDELT preferred, GNews on rate limit/5xx) and explains `since` accepted formats and recommended values like '30d' or '1m'.

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

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

The description goes beyond annotations by disclosing scoping ('scoped by your identifier'), persistence details ('Authenticated users get persistent memory; anonymous sessions retain memory for 24 hours'), and the full lifecycle ('Pair with recall to retrieve later, forget to delete'). This adds significant behavioral context that annotations alone do not cover.

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

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

The description is concise (5 sentences) and front-loaded with the core purpose in the first sentence. Every sentence adds value—usage context, storage behavior, persistence, and related tools—without redundancy.

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

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

For a simple write tool with 2 well-documented parameters and no output schema, the description is complete. It covers purpose, usage, scoping, persistence, and the related lifecycle tools (recall/forget). No critical gaps remain.

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 description does not add parameter-specific details beyond the schema, but it does reinforce the key-value structure. This is acceptable given the schema already fully documents both parameters.

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

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

The description clearly states the tool's purpose: 'Save data the agent will need to reuse later.' It uses a specific verb ('save') and resource ('data' as key-value pairs). It also distinguishes from siblings by explicitly naming 'recall' and 'forget' for related operations.

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 when you discover something worth carrying forward... so you don't have to look it up again.' It also names alternatives for related actions: 'Pair with recall to retrieve later, forget to delete.' This clearly contextualizes when to use this tool versus siblings.

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

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

Annotations already indicate readOnly, idempotent, and non-destructive behavior, but the description adds valuable behavioral context: internal cascading through multiple lookup endpoints, auto-disambiguation of inputs, and the return of specific citation URIs (pipeworx://edgar/company/{cik}, pipeworx://rxnorm/concept/{rxcui}). This goes beyond the annotations and helps the agent understand what happens under the hood.

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

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

The description is moderately long but well-structured and front-loaded with concrete example queries. Every sentence adds value—supported types, return details, and usage guidance. It could be tightened slightly, but it remains focused and readable.

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 moderate complexity (2 params, no output schema), the description fully prepares an agent: it explains what the tool returns, which entity types are supported, what input forms are accepted, and how it fits into the broader tool ecosystem (replacing 2-3 manual lookups). Sibling tools like entity_profile or compare_entities would logically follow after obtaining an ID through this 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 description coverage is 100%, with detailed descriptions of both 'type' and 'value' parameters. The description largely repeats what the schema already says (e.g., accepted formats for company and drug). It adds minor context about return payloads, but that is not strictly 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 function: resolving a user-spoken name to the canonical identifier required by other tools. It provides specific examples (ticker, CIK, RxCUI) and explicitly distinguishes its role from siblings like entity_profile or compare_entities by emphasizing it supplies the ID for subsequent lookups.

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

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

The description gives explicit guidance: 'Use FIRST whenever you have a name but need an ID.' This clearly indicates when to invoke the tool. It does not explicitly state when not to use it or name alternative tools, but the context is strong enough to avoid misuse.

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 read-only and idempotence. The description adds valuable behavioral context by mentioning it probes each entity with ai_visibility_check, ranks by score, and returns score/confidence/signal density. This goes beyond the 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 three sentences with no filler. It front-loads the main action, then covers the method, use case, and output format efficiently. 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?

Despite having no output schema, the description clearly explains the return value (ranked list with score, confidence, signal density) and the process (probing each entity with ai_visibility_check). For a tool of this complexity, it provides sufficient context for an agent to select and invoke it correctly.

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

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

Schema coverage is 100%, so all parameters are already documented with descriptions. The tool description does not add new meaning beyond what the schema provides; for example, the 'first entity as subject' detail is already in the schema. Thus it meets the baseline but doesn't exceed it.

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

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

The description clearly states 'Compare AI visibility across multiple entities side-by-side' with a specific verb and resource. It distinguishes itself from the sibling ai_visibility_check by focusing on multi-entity comparison and ranking, making the tool's purpose unambiguous.

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

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

The description provides a concrete use case ('competitive AI-marketing audits') and explains that it probes multiple entities, implying it is for comparisons. However, it doesn't explicitly exclude alternatives like compare_entities or state when not to use it, so it falls short of full explicit guidance.

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

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

Annotations already indicate readOnly, idempotent, and non-destructive, but the description adds critical behavioral details: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and a `sources_failed` field lists timed-out sources. It also clarifies ecosystem scope and what the return block contains. No contradictions with annotations.

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

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

The description is front-loaded with the core purpose and uses just four sentences to convey composite nature, use cases, return values, ecosystem scope, and failure behavior. Every sentence provides distinct value, and the length is justified for a tool with this complexity.

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

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

The description fully covers the tool's scope, inputs, outputs (summary block fields, per-advisory detail, links, alternative versions), failure modes, and ecosystem coverage. Since there is no output schema, the description adequately compensates by specifying the return 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?

The input schema already provides 100% description coverage for both `package` (npm package name, scoped accepted) and `version` (specific version, defaults to latest). The description does not add additional parameter-level syntax beyond the schema, so the baseline of 3 applies.

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

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

The description opens with 'Composite "should I add this npm package to my project" check in ONE call', clearly identifying the tool as a composite scanner for npm packages. It specifies the two data sources (deps.dev and bundlephobia) and the exact purpose. This distinguishes it from any sibling tools, none of which cover dependency scanning.

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 whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. Also provides exclusion and alternative: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.' This gives clear when-to and when-not-to guidance.

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

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

Annotations already mark the tool as read-only and idempotent, and the description adds valuable non-obvious behavior: returns character offsets and similarity scores, uses BGE-base-en embeddings with cosine over 500-char windows, and truncates at 200K characters with a flag. This goes beyond the annotation basics and gives the agent concrete expectations about output structure and constraints.

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 focused sentences pack the tool's purpose, usage, pairing, and technical constraints without redundancy. Information is front-loaded with the core action, making it easy to scan, and every sentence contributes useful 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?

For a tool with no output schema, the description covers what it returns (passages with offsets and similarity scores), when to use it, and limitations (truncation at 200K). Combined with rich annotations, this gives a complete picture for selection and invocation, 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 descriptions cover all three parameters (100% coverage), and the description reinforces the meaning of 'text' as already-pulled content and 'query' as a natural-language request. It adds helpful examples (e.g., SEC 10-K, article) but does not fundamentally change parameter semantics, so the 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 opens with 'Semantic search INSIDE a fetched record,' providing a specific verb and resource that clearly distinguishes it from sibling ask_pipeworx tools. It explains the input (text + query) and output (passages with offsets and similarity scores), leaving no ambiguity about the tool's function.

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

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

Explicitly states 'Use when the record is too big to cram into the prompt' and explains how it saves context. It also names a complementary sibling, ask_pipeworx_grounded, and gives a concrete workflow (fetch with the gateway, ground over relevant passages), offering clear guidance on when to use this tool versus alternatives.

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

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

Beyond annotations, it discloses that the operation returns a subscription id, requires authentication, and has delivery-specific behaviors like SMS verification and a 10/day cap. It does not, however, address the idempotentHint annotation by explaining what happens on duplicate subscription requests, leaving a minor gap.

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 contributes useful details, moving from purpose to requirements to types to delivery. The use of parentheses and em dashes makes it somewhat run-on, but it is well front-loaded and lacks 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?

Given the tool's complexity (nested objects, multi-type enum, no output schema), the description covers return value, auth, and delivery channels, and references how to retrieve alerts. It omits two of the five schema types (patent_grant, clinical_trial) from the description, but the schema covers them, so this is not a critical gap.

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 schema coverage at 100%, the baseline is 3, but the description adds value by giving concrete examples for each subscription type (e.g., sec_8k items, polymarket topic, fred series_id) and clarifying delivery requirements (phone verification, cap). It does not duplicate webhook details already in the schema, which is acceptable.

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: 'Create a proactive monitoring subscription to a live-data event stream.' It clearly distinguishes from sibling tools like list_subscriptions, unsubscribe, and recent_alerts by focusing on creation and enumerating supported subscription types with concrete examples.

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

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

It states the prerequisite (Pipeworx OAuth account, anonymous/BYO cannot persist) and gives context on when subscribing is appropriate. It also implies an alternative to subscription by noting the feed is always on and can be pulled via recent_alerts or a public URL, but does not explicitly name sibling tools as alternatives for listing/unsubscribing.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds substantial behavioral context beyond that: it returns category-bucketed example questions, maps them to exact tool + argument shapes, draws from the live catalog, and varies output by whether `topic` is supplied. No contradictions exist.

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 longer than average but every clause earns its place: example queries, return details, parameter explanation, and usage guidance. It is front-loaded with user-phrase examples, making it immediately scannable, though a slight trim could improve punch.

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 one-optional-parameter tool with no output schema and rich annotations, the description covers everything needed: purpose, return format, parameter behavior, and when to use. No critical gaps remain.

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, but the description enriches the `topic` parameter by giving concrete examples ("finance", "pharma", "betting") and explaining omission yields a cross-category spread. This adds meaning beyond the schema's terse 'Optional focus area' line.

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 the tool as an onboarding entry point that returns category-bucketed example questions for what to ask Pipeworx. It distinguishes from siblings by positioning itself as the 'FIRST' use case and referencing meta-tools like ask_pipeworx and entity_profile, showing how it teaches calling 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 explicitly states when to use: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also explains the two calling modes (no arguments vs. with `topic`), providing clear context without needing to enumerate 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?

The description adds valuable behavioral traits not covered by annotations: 'Ownership is enforced — you can only cancel your own subscriptions' and 'The row is deactivated (not deleted)' with the consequence that historical events remain available via recent_alerts. This goes beyond the readOnlyHint/destructiveHint/idempotentHint annotations.

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

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

Two sentences with no filler. The first sentence immediately states the action, and the second adds necessary behavioral context. Every word 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?

This is a simple one-parameter tool with annotations already covering safety/idempotency. The description explains the action, ownership constraint, side effect (deactivation), and relationship to recent_alerts. No output schema is needed, and nothing critical is missing.

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

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

The input schema fully documents the single parameter 'id' as 'Subscription id (uuid) returned by subscribe,' so schema coverage is 100%. The description only says 'by id' and adds no additional meaning beyond the schema, warranting the baseline score 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 'Cancel a subscription by id' — a specific verb and resource that clearly differentiates this tool from siblings like subscribe or list_subscriptions. The additional detail about deactivation (not deletion) further clarifies the exact operation.

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

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

The description provides clear context: cancellation is by id, ownership is enforced (only your own subscriptions), and the operation is a deactivation rather than a deletion. It does not explicitly name alternative tools, but the usage context is well established.

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 readOnly, idempotent, and non-destructive behavior; the description adds meaningful behavioral context: dual-path routing, tolerance-based grading via 'exact percent-delta math', the verdict set, and citation/reasoning outputs. It does not contradict the annotations. It could mention limitations or failure modes for 'unsupported' claims, but it is generally transparent.

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

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

The description is well-structured, front-loading the most useful trigger phrases and then explaining usage, behavior, and returns. The paraphrase list is somewhat lengthy, but each sentence adds value; the 'Replaces 4–6 sequential calls' sentence is a useful efficiency note. Not perfectly concise, but appropriately dense for a complex tool.

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

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

Given the tool has only 2 parameters and no output schema, the description covers the essential return values (verdict, actual value with pipeworx:// citation, reasoning) and explains the routing logic. It could be more complete by explaining what triggers 'inconclusive' or 'unsupported' verdicts, but it is largely sufficient for a medium-complexity tool.

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

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

Schema coverage is 100%, with both 'claim' and 'tolerance_pct' fully described in the input schema. The description adds only contextual behavior like 'exact percent-delta math' but does not provide new parameter-level semantics beyond what the schema already states, warranting the 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 defines the tool as natural-language claim verification against authoritative sources, with explicit trigger phrases like 'fact check' and 'verify the claim that...'. It specifies the two execution paths (SEC EDGAR fast path for company financials, grounded pipeline for all other claims), and distinguishes itself by consolidating multiple sequential steps into one call.

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 'Use whenever the agent needs to check whether something a user said is factually correct,' giving clear guidance. It further differentiates between company-financial claims and all other factual claims, but does not name alternative tools to use instead in specific cases, 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.