newton

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

The description adds substantial behavioral context beyond annotations: default model (Workers AI Llama-3.3-70b), optional Anthropic probing with BYO API key, cost implications, and the return format (per-model object + combined view). Annotations indicate readOnly and idempotent behavior, which is consistent with probing.

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 and front-loaded: first sentence states main action, second covers defaults/keys, third describes output, fourth lists use cases. No redundant information; every sentence serves a purpose.

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

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

Given the tool's complexity (4 parameters, multiple models, optional API key, scoring) and lack of output schema, the description fully explains inputs, outputs, use cases, and cost model. Annotations cover safety and idempotency. No gaps identified.

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?

While schema descriptions cover 100% of parameters, the description adds valuable semantics: default model selection, that `_apiKey` is only needed for 'anthropic' model, and that 'context' helps disambiguate. It explains the behavior of the 'models' parameter and the free/probing cost distinction.

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

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

The description clearly states the tool's purpose: to probe LLMs for knowledge about an entity and score visibility. It specifies the verb 'probe', the resource 'LLMs', the output 'score (0-100) per model', and the default model. It distinguishes itself from siblings like 'scan_competitor_ai_presence' by focusing on single-entity probing.

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

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

The description explicitly lists use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring'), providing clear context for when to use the tool. However, it does not explicitly mention when not to use it or compare to alternatives like 'scan_competitor_ai_presence'.

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, non-destructive. The description adds valuable context about routing to 3,775 tools and returning structured answers with citations, enhancing transparency beyond annotations.

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

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

The description is relatively long but well-structured with a clear preference statement, list of sources, and examples. Every sentence adds value, but slight conciseness 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?

Given the tool's complexity (covering 3,775 tools) and no output schema, the description appropriately explains the input format, use cases, and output nature (structured with citations). It is complete enough for an agent to use 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% with multiple aliases for 'question'. The description clarifies that the parameter expects natural language input and provides examples, adding meaning beyond the schema's type/description.

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

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

The description clearly states the tool routes questions to a vast array of sources (SEC filings, FDA, etc.) and returns structured answers with citations. It distinguishes itself from web search by being preferred for authoritative structured data.

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

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

Explicitly says 'PREFER OVER WEB SEARCH' and provides a comprehensive list of use cases (SEC, FDA, economics, etc.) with concrete examples. It tells the agent exactly when to invoke this tool.

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

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

The description fully discloses the return structure ({answer, evidence, confidence, source, fetched_at, refusal_reason:null}) and lists explicit refusal reasons. It also notes the extra LLM call cost. This goes well beyond the annotations, which already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint.

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

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

The description is dense but well-structured, with a clear hierarchy of purpose, behavior, return format, and usage guidance. Every sentence adds value, though it could be broken into bullet points for easier digestion. Still, it's concise given the amount of information conveyed.

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 6 parameters (1 required) and no output schema, the description provides complete context: it explains the process (routing, fetching, extraction), return format (including failure modes), and usage scenarios. The agent has sufficient information to select and invoke this tool correctly.

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

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

Schema coverage is 100% with all 6 parameters (aliases for question) described. The description adds minimal parameter semantics beyond the schema; it doesn't elaborate on how the question is processed. Baseline 3 is appropriate as schema does the heavy lifting.

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 a hallucination-resistant answer mode for high-stakes reads. It specifies the verb (extracts answer) and resource (data from 3,775 tools across 895 sources), and distinguishes it from sibling ask_pipeworx by mentioning cost and use case.

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

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

The description explicitly states when to use this tool (quoted/cited/acted on answers, high-stakes scenarios) and when to prefer the alternative (ask_pipeworx for casual lookups). It lists specific use cases like financial verdicts, legal claims, medical lookups, and public statements.

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

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

The description goes far beyond annotations, detailing fan-out behavior, response shapes, resolver contract confidence levels, safety checks (low-confidence short-circuit, closed markets, wide spreads), resolution-rule risk, and news fallback mechanisms. Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, and the description adds extensive behavioral context without contradiction.

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

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

The description is very detailed but somewhat verbose, with extensive fan-out examples and nested explanations. While structured with headings (CLASSIFIERS, FAN-OUT EXAMPLES, etc.), it could be more concise for an agent to quickly parse. The front-loading of core purpose is good, but the length may hinder quick comprehension.

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

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

Given no output schema, the description thoroughly explains response structure (result.market, result.analysis, result.evidence) and covers edge cases: low-confidence matches, closed markets, wide spreads, resolution-rule risk, news fallback fields, and safety checks. It is highly complete for the tool's complexity.

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

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

Schema coverage is 100% with all three parameters described. The description adds semantic clarity: it explains the market parameter accepts slug, URL, or question text (reinforcing schema), describes depth options ('quick' vs 'thorough') and default, and clarifies the include_raw parameter's effect on response size and when to use true.

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

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

The description starts with a clear verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It explicitly lists use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') and provides classifiers and fan-out examples, making it distinct from sibling tools like polymarket_edges or polymarket_arbitrage.

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

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

The description explicitly states when to use the tool ('Use for...'), provides classifiers and fan-out examples, and mentions checking resolver contract and safety before trusting analysis. However, it does not explicitly state when not to use it or provide direct alternatives from the sibling list, though the specificity implies appropriate use cases.

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

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

Annotations already indicate readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable behavioral details: off-calendar fiscal years handled correctly, results sorted by primary metric, returns citation URIs. No contradictions with annotations.

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

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

The description is approximately 130 words, front-loaded with user query examples, then the core action, then details. Every sentence adds value: entity types, data sources, sorting, off-calendar handling, and citation URIs. No redundant content.

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

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

Given the complexity (two entity types, different data sources, sorting, citations), the description covers key aspects well. It mentions off-calendar handling and result sorting. It lacks an output schema but describes return details. It could explicitly list the financial metrics (revenue, net income, etc.) and counts for drug data, but overall it is thorough.

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

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

Schema coverage is 100%, and the description significantly enriches parameter meaning. It explains that type='company' pulls financial data from SEC EDGAR and type='drug' pulls FAERS data. It provides examples for values (tickers/CIKs for companies, drug names) and mentions constraints (2–5 items). This adds substantial 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 starts with clear user query examples ("Compare X and Y") and explicitly states the action: side-by-side comparison of 2–5 companies or drugs in one parallel call. It specifies entity types and what data is pulled (financials for companies, FAERS data for drugs), distinguishing it from 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 explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' providing clear usage guidance. It also explains when to use each type (company vs drug). It could briefly mention when not to use the tool (e.g., for historical data or non-standard entities), but the guidance is strong overall.

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

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

Discloses key behaviors: automatic decomposition, parallel routing to many sources, return of verbatim evidence with confidence scores and citations, never inventing facts, explicit gaps. No contradiction with annotations (all consistent).

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

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

The description is well-structured and front-loaded with the main purpose, but slightly verbose with multiple clauses. Still, 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?

Given no output schema, the description thoroughly explains return format (structured findings with verbatim evidence, confidence, source, fetched_at, citation, gaps). It covers prerequisites and expected timing, making it very 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 the description adds value by explaining depth options (quick=3, standard=5, thorough=8) and the paid plan requirement, plus clarifies that the question can be broad/multi-part.

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 'Grounded multi-source research in ONE call' and explains the decomposition process. It distinguishes itself from sibling tools like ask_pipeworx by comparing use cases.

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

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

Provides explicit when-to-use guidance: 'for broad or multi-part questions' and even names an alternative (ask_pipeworx) for simple lookups. Also notes prerequisites (Pipeworx account, paid plan for certain depth).

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint as safe. The description adds behavioral context: it differentiates with respect to x and returns the derivative. No contradictions.

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

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

Two sentences with zero waste. First sentence states the purpose and key detail (with respect to x). Second sentence gives input format and output. Front-loaded effectively.

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?

Tool is simple with one parameter, rich annotations, and an output schema. Description covers what it does, input format, and output. No additional context 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?

Schema coverage is 100%, so the schema already documents the single parameter. The description adds an example but no additional semantics beyond what the schema provides. Baseline of 3 is appropriate.

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

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

Clearly states the tool 'finds the derivative of an expression with respect to x'. The verb 'find' and resource 'derivative' are specific. It distinguishes from siblings like 'simplify' or 'factor' by naming the mathematical 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?

Provides explicit input format ('algebraic notation, e.g., "x^2"') and output ('returns the derivative'). While it doesn't explicitly state when not to use it, the context implies use for differentiation tasks, which is clear enough.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds that it returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly.' This enhances transparency about output format and readiness beyond annotations.

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

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

The description is a single paragraph that efficiently covers purpose, usage, example domains, return format, and guidance. It is front-loaded with the action. Minor redundancy (e.g., list of domains) but not excessive.

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 discovery tool with 1 required parameter, no output schema, and strong annotations, the description explains the return value fully (tools with schemas and examples). It also provides context like 'no second schema lookup needed.' No gaps identified.

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. The description repeats that 'query' accepts aliases but doesn't add new semantic meaning. Baseline 3 is appropriate since the schema does the heavy lifting.

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 'Find tools by describing the data or task' and lists extensive domains (SEC filings, FDA drugs, etc.), distinguishing it from sibling tools which are task-specific (e.g., ask_pipeworx, compare_entities). It establishes discover_tools as a meta-tool for exploration.

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

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

Explicitly says 'Use when you need to browse, search, look up, or discover' and 'Call this FIRST when you have many tools available.' This provides clear when-to-use guidance. It lacks explicit when-not-to-use statements, but the positive guidance is strong enough.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable context: it performs a parallel fan-out across multiple sources, returns specific fields, mentions that the patents API 'soft-fails until reactivated', and notes the return includes pipeworx URIs. No contradictions.

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

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

The description is dense with useful information but somewhat lengthy. It front-loads example queries effectively followed by details. While every sentence earns its place, it could be slightly more concise. Still highly informative.

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

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

Given no output schema, the description lists specific return fields (CIK, filings with URIs, fundamentals sorted by period_end, patents, news via fallback, LEI). It also mentions error/fallback behavior. It lacks a formal structure description but covers the key return aspects adequately.

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 2 required parameters. The description adds meaning beyond the schema by explaining the value parameter format (ticker or zero-padded CIK, examples given) and why names are not supported. It clarifies the type enum is currently limited to 'company'. This significantly aids correct parameter selection.

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

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

The description clearly states this tool provides a 'full cross-source profile of a US public company' with specific data fields (CIK, filings, fundamentals, patents, news, LEI). It distinguishes from sibling 'resolve_entity' by noting names are not supported and that tool should be used first. The purpose is specific and actionable.

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

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

Explicit guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also explicitly states when not to use (if only a name, use resolve_entity) and provides example prompts covering various phrasings. This is model behavior.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, so the safety profile is clear. The description adds minimal behavioral context beyond input examples and output 'factored form'. 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 two sentences, concise and front-loaded. It is efficient but could include a brief note on output format or constraints without sacrificing clarity.

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

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

Given the existence of an output schema, the description does not need to detail return values. However, it lacks specification of input constraints (e.g., valid variable names, coefficient types) that would enhance completeness for safe usage.

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

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

The input schema has 100% coverage, describing the 'expression' parameter as a polynomial string. The description echoes this with examples but does not add significant new meaning beyond what the schema already provides.

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

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

The description clearly states the tool factors a polynomial into irreducible factors, specifying the action and resource. It distinguishes itself from sibling tools like 'simplify' or 'derive' which perform different mathematical 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 provides examples of valid inputs but does not explicitly state when to use this tool versus alternatives like 'simplify' or 'derive'. It gives implied usage but lacks explicit guidance on context or exclusions.

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

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

Annotations already indicate destructiveHint=true and readOnlyHint=false. The description reinforces this by stating 'delete' and 'clear sensitive data,' adding contextual value beyond the annotations. No contradiction.

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

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

The description is extremely concise: two sentences with no wasted words. It front-loads the action and covers key points efficiently.

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

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

Tool complexity is low (single parameter, no output schema). The description fully covers purpose, usage, and relationships with sibling tools, leaving no gaps.

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

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

Schema coverage is 100%, so baseline is 3. The description does not add any additional semantic information about the 'key' parameter beyond what the schema already provides ('Memory key to delete').

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

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

The description clearly states 'Delete a previously stored memory by key,' using a specific verb and resource. It distinguishes from siblings by mentioning 'remember' and 'recall' as complementary tools.

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

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

The description provides explicit use cases: 'when context is stale, the task is done, or you want to clear sensitive data,' and advises pairing with 'remember' and 'recall.' It lacks explicit exclusion of other scenarios but is still clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds valuable behavioral details: fetches the page, extracts title/description/key links, and outputs standard markdown format. 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?

Two concise sentences followed by a bullet list of use cases. Every sentence adds value, and the key action is front-loaded. No wasted words.

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

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

Given only 2 parameters, no output schema, but rich annotations, the description fully covers what the tool does, how it works (fetch, extract, emit), the output format, and when to use it. Complete for agent invocation.

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

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

Schema coverage is 100% with good descriptions for both parameters. The description reinforces the url parameter's purpose and provides default and max values for max_links, which adds meaning beyond the schema.

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

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

The description uses a specific verb ('Generate') and resource ('llms.txt file'), clearly states the purpose of enabling AI crawler indexing, and distinguishes from sibling tools by listing concrete use cases (client site, own project, competitor audit).

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

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

The description explicitly lists three use cases where the tool is useful, providing clear context. However, it does not mention when not to use it or suggest alternative tools, though the distinct sibling list makes the niche 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, idempotent, and non-destructive. The description adds that it returns an antiderivative with constant C, which complements the annotations without contradiction. No additional behavioral traits are hidden.

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 no wasted words. It concisely states purpose, input format, and output. 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?

Given the simple tool (1 parameter, full annotations, output schema exists), the description covers everything needed. The annotations and schema handle safety and parameters, and the description clarifies the operation and return format.

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

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

The schema has 100% coverage for the single parameter 'expression' with a basic description. The description adds context by showing algebraic notation examples ('x^2') and the input format, which goes beyond the schema's description.

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

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

The description clearly states the verb 'Find the indefinite integral' and the resource 'expression' with respect to x. It gives an example 'x^2' and distinguishes from sibling tools like 'derive' and 'simplify' by its specific mathematical 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 implies when to use this tool (for integration) without explicit alternatives, but the purpose is specific enough that an agent can infer usage from the context of sibling tools like 'derive' and 'simplify'. No explicit when-not is given, but the clarity offsets this.

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

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

Annotations already mark it as readOnly, idempotent, and non-destructive. The description adds specific return fields and behavior regarding inactive subscriptions, adding value beyond annotations.

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

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

Two concise sentences: first states purpose and return fields, second gives usage guidance. No wasted words.

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

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

Given one optional parameter, full annotations, and no output schema, the description is complete. It covers purpose, return fields, and usage context.

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

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

Schema coverage is 100% with one well-described parameter. The description does not add extra meaning beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states 'List the caller's active subscriptions.' which is a specific verb and resource. It distinguishes from sibling tools like subscribe and unsubscribe.

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

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

Explicitly says 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This provides clear when-to-use guidance and implies alternatives.

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

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

Adds helpful behavioral context beyond annotations: it's free, does not count against tool-call quota, and is rate-limited to 5 per identifier per day. 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?

Three sentences, front-loaded with purpose, and includes all key details efficiently. No wasted words.

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

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

For a feedback tool with 3 parameters (2 required, 1 enum, nested object), the description covers usage, constraints, formatting, and rate limits. Lacks output schema but feedback tools typically return simple success; no critical gaps.

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

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

Schema coverage is 100% and description enriches each parameter: repeats and expands on the type enum, adds guidance for the message field (be specific, 1-2 sentences, 2000 chars max), and clarifies context as optional structured info. Provides meaningful additions beyond schema.

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

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

The description clearly states the tool sends feedback to the Pipeworx team about bugs, missing features, data gaps, or praise. It distinguishes from sibling tools by focusing on communication rather than data retrieval or actions.

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

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

Explicitly provides when to use (bug, feature, data_gap, praise) and what not to do (don't paste end-user prompt). Also mentions rate limit and free usage. Does not explicitly contrast with every sibling, but the guidance is sufficient for selecting the tool.

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

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

Annotations already confirm read-only, idempotent, non-destructive behavior. The description adds valuable context: data source (CF analytics), privacy (no PII), and caching policy (5min-1h). 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?

Five sentences, no wasted words. Starts with a clear definition, followed by bullet-like use cases, then technical details. Information is front-loaded and well-organized.

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

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

Given the tool's simplicity (one optional parameter, no output schema), the description fully covers return values, caching, and data origin. No gaps for the intended use.

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

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

Schema has 100% description coverage for the only parameter. The description further adds semantic guidance by explaining how different window lengths affect results (hot vs. steady-state), which supplements 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 returns top tools, packs, and call volume over a recent window. It uses specific verbs and resource names, and distinguishes from siblings by focusing on trending agent-usage data.

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

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

Lists three explicit use cases, providing clear context for when to use the tool. However, it does not specify when not to use it or mention alternative sibling tools for comparison.

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

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

Annotations indicate readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds extensive behavioral context: algorithm details (monotonicity, partition checks), thresholds (3pp deviation), Jaccard similarity >= 0.30, placeholder filtering, fill check against live CLOB depth, and conditions for null arb signal. 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 detailed and front-loaded with the requirement. Every sentence provides useful information, though it is slightly verbose. Could be more structured but remains clear and efficient.

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

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

Given the tool's complexity, 2 parameters (100% schema coverage), no output schema, the description is remarkably complete. It covers modes, algorithm, edge cases, fill check, sibling tool reference, and return format. Nothing essential is missing.

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

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

Schema description coverage is 100% with clear descriptions for each parameter. The description adds significant semantic meaning: explains when to use each parameter, how they affect mode of operation, and what processing occurs. It adds value beyond schema.

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

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

The description clearly states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks, distinguishes between event and topic modes, and uses specific verbs like 'walks', 'checks', 'emits'. It differentiates from sibling tools by its unique functionality.

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

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

The description explicitly requires one of 'event' or 'topic' and notes that calling with no args fails. It recommends 'event' for specific markets and 'topic' for cross-event scanning, explaining the advantages of cross-event mode. It does not directly compare with all sibling tools but mentions '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 goes far beyond the annotations by detailing the three model segments, caching behavior (1h KV), diagnostic outputs, and filter knobs, providing complete transparency into what the tool does and how it behaves.

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 main purpose and well-organized into segments, knobs, and diagnostics. While lengthy, every sentence is valuable, though a slightly more concise structure could be achieved.

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 thoroughly explains the response structure (by_segment, fed_candidates, diagnostics) and return fields, making it complete for a complex tool with nine parameters.

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%, providing a baseline of 3. The description adds contextual value by explaining how knobs like min_liquidity and max_spread_pp serve as tradeable-edge filters, enhancing understanding beyond the schema.

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

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

The description explicitly states 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price' and frames it as 'what should I bet on today', clearly distinguishing it from sibling services like polymarket_arbitrage.

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

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

The description provides clear context for when to use the tool (discovering Pipeworx-based edge opportunities) and details knobs for filtering, but does not explicitly state when not to use it versus alternative tools like polymarket_arbitrage.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint. The description adds context about history limits (60-day TTL), snapshot availability, and that decay is computed from daily closes. No contradiction with annotations.

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

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

The description is front-loaded with purpose and well-structured, covering response fields and limits. It is slightly long but every sentence provides necessary information. Could be slightly more concise but still effective.

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

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

With no output schema, the description fully explains the response structure (tracked, expired, snapshot_dates) and limits. For a tool with 2 optional params, this is complete and leaves no ambiguity about what data is returned.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by explaining the 'days' parameter's default and max clamp, and for 'window' it specifies snapshot family with examples ('24hr', '1wk', '1mo'). This adds value 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 it provides edge persistence and decay telemetry from daily snapshots, answering the specific question about edge age. It distinguishes itself from sibling tools like polymarket_edges by focusing on time-series and decay.

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

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

The description implies usage for understanding edge age and decay but does not explicitly state when to use this tool over alternatives or provide when-not-to-use guidance. Siblings like polymarket_edges exist but are not contrasted.

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

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

Annotations indicate readOnlyHint, idempotentHint, and non-destructive behavior. The description adds detailed behavioral context: it 'walks the ladder' and returns specific fields like top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, and verdict for single-market; similarly detailed for basket mode with per-leg fill detail and forced_directional_risk. No contradiction with annotations.

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

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

The description is well-structured with bold headings for SINGLE-MARKET, BASKET, and USE THIS, making it scannable. Every sentence provides necessary information without redundancy. It is appropriately sized for the tool's complexity.

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

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

Given the tool's complexity (two modes, many return fields, safety warnings) and the absence of an output schema, the description is highly complete. It explains inputs, outputs, edge cases (thin_legs, forced_directional_risk), and deployment context. The agent can fully understand how 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?

Schema coverage is 100% for 4 parameters, but the description adds meaning beyond the schema. It explains that size_usd is interpreted differently in single vs basket mode (max spend vs target proceeds vs settlement notional), side has auto-detection logic for basket, and market/event determine the mode. This adds crucial context for correct usage.

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

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

The description clearly states the tool's purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes between single-market and basket modes, and explicitly differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by specifying when to use this tool before those.

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 guidelines: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains the rationale by warning about partial basket fills converting 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?

The description extensively details behavioral aspects beyond annotations: compatibility_warning conditions (non-equivalent bet shapes, unrelated events), temporal alignment checks, skipped counters for cross-type/subtype mismatches. This fully leverages the read-only, open-world, and idempotent annotations.

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

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

The description is relatively long but well-structured and information-dense. Every sentence contributes meaning, and the key information (purpose, modes, response fields) is front-loaded. Minor redundancy in warning about pre-mapped topics 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?

Despite lacking an output schema, the description thoroughly explains the response structure: leg-by-leg prices, matched spread array, compatibility_warning, temporal_alignment, and skipped counters. This covers all necessary aspects for an agent to understand and use the tool correctly.

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

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

Schema coverage is 100%, providing parameter descriptions. The description adds significant value by explaining the topic parameter's macro shortcuts, the interaction between topic and explicit parameters, and practical examples (e.g., 'fed', 'btc'). It enriches understanding beyond the schema.

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

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

The description clearly states the tool's purpose: computing cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes itself from sibling tools like polymarket_arbitrage by focusing on two specific prediction markets, and it specifies two modes of operation (topic shortcuts and explicit pairings).

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

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

The description provides clear guidance on when to use each mode (topic vs. explicit) and warns that most pre-mapped topics currently return compatibility warnings. However, it does not explicitly contrast with alternative tools like polymarket_arbitrage or state when not to use this 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 provide readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds storage context (scoped to identifier, pairs with siblings) but no contradiction.

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

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

Two sentences, front-loaded with purpose, no wasted words, well-structured with clear separation of usage and behavior.

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

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

Completeness is high given one optional parameter, annotations covering safety, and clear purpose. Output schema not needed for this tool; description covers all necessary context.

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

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

Schema covers 100% of parameters with description that omitting key lists all keys. Description adds context about use but does not add significant semantic value beyond schema.

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

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

Clearly states verb 'Retrieve' and resource 'value previously saved via remember, or list all saved keys'. Distinguishes from sibling tools 'remember' and 'forget'.

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

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

Explicitly states when to use (look up context stored earlier) and scopes to identifier. Mentions pairing with remember/forget. Does not explicitly state when not to use, but context is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. The description adds context about return fields, the mark_read mutation (which is acknowledgment, not true write), and the alternative access method. No contradiction with annotations and adds meaningful behavioral detail.

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

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

Four sentences, front-loaded with purpose, every sentence adds value: action, output fields, filtering and mark_read behavior, and alternative access. No fluff 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?

Tool has 5 optional params, no output schema, and annotations provide safety. Description covers the main use cases, key fields, filter options, and mark_read behavior. Lacks error conditions or rate limits, but for a read-only polling tool with good annotations, it is fairly complete. Slight deduction for missing return format details.

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 each parameter is described in schema. The description goes beyond by giving an example for type ('sec_8k') and explaining the effect of mark_read. It adds value without repeating the schema, so above baseline 3.

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

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

The description starts with a clear verb 'Pull fired events from your subscription feed' and specifies the resource and what the output contains (source, citation_uri, raw event payload). This purpose is distinct from sibling tools like list_subscriptions or subscribe.

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

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

Provides clear context: filter by type and/or since, and set mark_read for read tracking. Mentions polling works fine and there's an alternative REST endpoint. Lacks explicit when-not-to-use or alternatives to sibling tools, but the guidance is sufficient.

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

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

Discloses multi-source fan-out, fallback from GDELT to GNews, and soft-fail for USPTO. Adds value beyond annotations which already mark it as read-only and idempotent.

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

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

Front-loaded with concrete user queries, dense but every sentence adds value. No wasted words.

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

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

Despite no output schema, describes return structure (changes[], total_changes, citation URIs) and covers edge cases like fallback and soft-fail.

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

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

Schema coverage is 100% but description adds richer context: explains 'since' accepts ISO or relative shorthand with examples, and 'value' accommodates ticker or CIK.

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

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

The description uses specific verbs like 'change feed' and lists concrete example queries, clearly distinguishing it from sibling tool 'entity_profile' which handles static profiles.

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

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

Explicitly states when to use 'entity_profile' instead, and provides example queries for when to use this tool. Lacks explicit 'when not to use' but context is clear.

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

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

Adds behavioral details beyond annotations: storage as key-value pairs scoped by identifier, persistence differences between authenticated users (permanent) and anonymous sessions (24 hours). 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?

Three focused sentences with zero waste. Each sentence adds essential information: purpose, usage scenario, and behavioral 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?

Covers purpose, usage, and behavior comprehensively. Lacks explanation of return values (e.g., confirmation or error handling), which is not critical but would enhance completeness.

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

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

Schema coverage is 100% with clear parameter descriptions. The description adds no additional meaning beyond what the schema provides, achieving the baseline for 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 clearly states the tool's purpose: 'Save data the agent will need to reuse later'. It provides specific examples of when to use (resolved ticker, target address, etc.) and distinguishes from sibling tools like recall and forget.

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

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

Explicit usage guidance: 'Use when you discover something worth carrying forward'. It also directs to pair with recall and forget, giving clear context for when to use this tool versus alternatives.

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

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

Annotations indicate safe, read-only, idempotent behavior. Description adds value by revealing internal cascading lookups and auto-disambiguation, and states it replaces 2-3 manual lookups—context beyond annotations.

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

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

Front-loaded with examples and clear sections. Every sentence is informative; no fluff. Slightly long but justified given the detail needed for two entity types.

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 two required params with 100% schema coverage and no output schema, the description fully explains return values (ticker, CIK, RxCUI, etc.) and behavior. No gaps.

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

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

Schema covers 100% of parameters; description enriches with details like what each type returns (e.g., company returns ticker+CIK+company_name) and example inputs for value (e.g., 'ozempic', 'metformin'). Baseline 3; plus for meaningful additions.

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

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

Description uses action verbs ('resolve', 'look up') and specific examples ('ticker', 'CIK', 'RxCUI'), clearly identifying the tool's role. It states 'use FIRST whenever you have a name but need an ID,' distinguishing it from sibling tools like entity_profile or compare_entities.

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

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

Explicit guidance: 'Use FIRST whenever you have a name but need an ID.' Provides example queries and specifies supported types with return values. Lacks explicit when-not-to-use or alternative tools, but context is sufficient.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds context about the internal process (calling ai_visibility_check, ranking, returning scores). No contradiction; adds value beyond annotations.

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

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

The description is two concise sentences. First sentence states action and process, second provides use case and example. No wasted words, front-loaded with key information.

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

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

Despite no output schema, the description specifies return as 'ranked list with score, confidence, signal density per entity.' Covers input, process, output sufficiently for a composite tool.

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

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

Schema has 100% parameter descriptions. The description adds meaning by noting the first entity is treated as 'subject' and others as competitors, which is an important semantic not in 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 compares AI visibility across multiple entities, using verbs like 'probes', 'ranks', and 'surfaces'. It distinguishes from sibling 'ai_visibility_check' which does a single probe, making purpose clear and distinct.

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 use case ('competitive AI-marketing audits') and an example question. It references sibling tool 'ai_visibility_check' implying when to use a single probe. However, it lacks explicit when-not-to-use instructions.

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 safe (readOnly, idempotent). The description adds valuable behavioral context: partial failures, first measurement delay (5-30s), graceful degradation with 'sources_failed' list. 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 a single, dense paragraph packed with information. It is efficient but could be broken into clearer sections. Still, every sentence provides 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 no output schema, the description thoroughly explains the return structure (summary fields, advisories, links, alternative versions) and error handling. It covers all essential aspects for an agent to understand the tool's behavior.

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

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

Schema coverage is 100% with clear descriptions for both parameters. The description does not add new semantic meaning beyond what the schema 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 explicitly states the tool's verb and resource: 'composite check in ONE call' for 'should I add this npm package'. It distinguishes from siblings by emphasizing the composite nature and listing the data sources (deps.dev, bundlephobia).

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

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

Provides clear when-to-use: 'whenever an agent asks is X safe / popular / small'. Also specifies limitations: 'NPM ecosystem only in v1' and points to alternatives for other ecosystems (PyPI, Maven, etc.).

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

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

Annotations already declare readOnlyHint and idempotentHint. Description adds significant behavioral detail: uses BGE-base-en embeddings + cosine similarity, 500-char overlapping windows, 200K char cap with truncation flag, return of offsets and similarity scores. No contradiction with annotations.

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

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

Approximately 100 words, effectively front-loaded with purpose and usage. Every sentence adds critical context. No redundant or vague statements.

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

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

Given no output schema, description explains return format (passages with offsets, similarity scores). Covers input limits, chunking strategy, and pairing with sibling tool. Fully equips an agent to use the tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. Description adds value by explaining the underlying chunking mechanism, embedding model, and character limit, which go beyond schema descriptions. Provides example queries for the 'query' 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?

Clearly states 'Semantic search INSIDE a fetched record', specifying verb and resource. Distinguishes from sibling tools like ask_pipeworx_grounded by explaining the different use case (search vs. grounding). Examples (SEC 10-K, article) reinforce purpose.

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

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

Explicitly states when to use: 'Use when the record is too big to cram into the prompt'. Contrasts with ask_pipeworx_grounded, naming the alternative and how they pair. Provides clear context for appropriate invocation.

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

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

Annotations declare readOnlyHint, idempotentHint true, and destructiveHint false, so the agent knows it's safe. Description adds input format context but doesn't 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?

Two sentences, no wasted words. Information is front-loaded and efficient.

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

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

For a simple tool with one parameter and an output schema, the description is sufficient. It explains purpose and input format, though return value details are not needed due to output schema.

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

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

Schema coverage is 100% with description and examples for the single parameter. The tool description adds no new meaning beyond the schema's parameter description.

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

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

The description clearly states the tool reduces mathematical expressions to simplest form, giving input format and example. It distinguishes from siblings like 'derive' and 'factor' by specifying 'simplest form', but does not explicitly contrast with them.

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

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

No guidance on when to use this tool vs alternatives like 'derive' or 'factor'. The description implies usage but lacks explicit when-not or alternative tool references.

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 non-read-only, open-world, idempotent, non-destructive behavior. The description adds substantial context: account requirements, supported types with examples, delivery channels with constraints (email, sms cap, webhook signing). It does not discuss rate limits or idempotency, but annotations cover the core traits.

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 detailed but well-structured with a logical flow (purpose, account requirement, types, delivery). It is not overly verbose given the complexity, but could be slightly more concise for an AI agent.

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

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

Given the tool's complexity (3 parameters, nested objects, multiple types and delivery options) and no output schema, the description is comprehensive. It covers all type-specific params, delivery constraints, and return value, leaving little ambiguity for correct invocation.

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

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

Schema coverage is 100%, but the description adds rich meaning beyond the schema: examples for each type (e.g., sec_8k items codes), detailed delivery options (webhook HMAC signature, phone verification), and completeness for required parameters. This significantly aids correct parameter selection.

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

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

The description clearly states it creates a proactive monitoring subscription to a live-data event stream, specifying the verb (create), resource (subscription), and return value (subscription id). It distinguishes from sibling tools like list_subscriptions and unsubscribe by focusing on creation.

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

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

The description provides context on when to use (creating a monitoring subscription) and includes prerequisites (Pipeworx OAuth account) and constraints (delivery caps, phone verification). However, it does not explicitly state when not to use or compare to alternatives, though sibling tools exist.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds that it draws from a live catalog and returns example tool calls, providing useful behavioral context beyond annotations.

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

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

The description is thorough and well-structured, starting with common user questions, then output details, then usage. It is slightly long but each sentence adds value.

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

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

Given no output schema, the description explains return format (category-bucketed questions with tool calls) and parameter usage, making it fully complete for the onboarding purpose.

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

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

The parameter 'topic' has a description in the schema, but the description adds concrete usage examples and enum-like values (finance, pharma, etc.), significantly aiding agent understanding.

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

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

The description clearly defines the tool as an onboarding entry point that returns category-bucketed example questions with exact tool calls, distinguishing it from siblings by specifying it's for initial exploration.

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 to use this tool first when the agent doesn't know what Pipeworx can do, and to learn how to call meta-tools. It implies context but doesn't list exclusions or alternatives in detail.

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

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

Adds value beyond annotations by explaining that the row is deactivated (not deleted) and that historical events remain available via recent_alerts. No contradiction with annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true).

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 succinct sentences that convey all necessary information without redundancy. Every word adds value.

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

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

Given one parameter, no output schema, and annotations covering safety, the description fully explains behavior, side effects, and constraints. No 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?

Only one parameter 'id' with schema description 'Subscription id (uuid) returned by subscribe.' Schema coverage is 100%, so the description adds no additional meaning beyond what the schema already provides.

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

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

The description clearly states the action ('Cancel a subscription by id') and the specific resource ('subscription by id'). It distinguishes from sibling tools like 'subscribe' and 'list_subscriptions' by emphasizing the cancellation action.

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 context: ownership enforcement ('you can only cancel your own subscriptions') and the deactivation behavior. While it doesn't explicitly state when not to use or name alternatives, the context is sufficient for an agent to determine appropriate 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 indicate read-only, open-world, idempotent, non-destructive behavior. The description adds valuable context: it uses SEC EDGAR + XBRL, returns a verdict with citation and percent delta, and replaces multiple sequential calls. No contradiction with annotations.

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

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

The description is well-structured, front-loaded with triggers and usage, then domain, return format, and value proposition. Every sentence is informative and concise.

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

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

Given the tool has one well-documented parameter and no output schema, the description is comprehensive: it explains input, output format, domain, and benefit. It does not cover edge cases or error handling, but overall it is sufficient.

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

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

Schema description coverage is 100% for the single parameter 'claim', and the description reinforces its meaning with examples and natural-language triggers. The description adds context beyond the schema's example.

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

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

The description explicitly lists natural-language triggers and states the tool's function: claim verification against authoritative sources. It specifies the current domain (company-financial claims) and distinguishes itself from sibling tools by noting it replaces multiple sequential calls.

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

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

The description clearly says 'Use whenever the agent needs to check whether something a user said is factually correct' and specifies the scope (company-financial claims). However, it does not explicitly exclude non-financial claims or provide alternative sibling tools for other domains.

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