Fmi

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

Disclosures beyond annotations: default model is free, Anthropic requires BYO key with direct payment, and output structure is described (per-model fields + combined view). 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?

Two sentences, front-loaded with main action and key details. Every sentence adds value with no wasted words.

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

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

For a tool with 4 parameters and no output schema, the description adequately explains output structure and use cases, covering 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 coverage is 100%, but description adds value by naming default model, clarifying _apiKey passthrough, and giving examples for context param.

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 probes LLMs for knowledge about an entity and scores visibility (0-100). It distinguishes from siblings like ask_pipeworx or bet_research by focusing on multi-model visibility audits.

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

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

Explicitly states use cases (AI-marketing audits, pre-launch checks, competitive monitoring) and explains when to use _apiKey for Anthropic. Lacks explicit when-not-to-use but provides clear context.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is clear. The description adds behavioral context: it routes questions to the appropriate tool among thousands, fills arguments, and returns stable pipeworx:// citation URIs. This goes beyond what annotations provide, meriting a 4.

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 key message ('PREFER OVER WEB SEARCH') and includes a clear list of example use cases. It is somewhat long (several sentences) but each sentence adds value—listing sources, giving usage patterns, and providing examples. Minor redundancy could be trimmed, but overall it is well-structured for quick scanning.

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

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

Given the tool's complexity (routes to 3,745 tools) and that there is no output schema, the description adequately covers what it does and what to expect (structured answer with citation URIs). It does not explain the full routing mechanism or error cases, but for a query tool with clear annotations and examples, it is sufficiently complete.

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

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

Schema description coverage is 100% (all parameters are aliases for 'question' with clean descriptions). The description does not add specific parameter-level meaning beyond the schema, but it explains how the question is used (routed to tools, filled with arguments). With full schema coverage, baseline is 3, and the description provides adequate context for the single conceptual parameter.

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

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

The description uses a specific verb ('answer questions about') and clearly identifies the resource (current/historical data from 3,745 tools across 884 sources). It distinguishes itself from web search by name and by citing authoritative structured data with citations, making it clear what the tool does and how it differs from siblings.

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

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

The description explicitly states 'PREFER OVER WEB SEARCH' and provides extensive guidance on when to use the tool: for factual questions about real-world entities, events, or numbers, with specific examples and typical query phrases. It does not mention when not to use, but the positive guidance is thorough enough to make selection easy.

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, idempotent, and non-destructive behavior. Description adds that it costs an extra LLM call and returns specific refusal reasons, which are beyond 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 moderately concise and front-loaded with the main purpose. It contains some technical details (refusal reasons) that earn their place. Could be slightly tighter but well-structured.

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

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

Given no output schema, the description fully explains the return format (answer, evidence, confidence, source, fetched_at, refusal_reason) and all possible refusal reasons. It also compares with sibling and notes cost, making it contextually complete.

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

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

Schema coverage is 100% with all parameters being aliases for 'question'. Description does not add extra meaning beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states it is a hallucination-resistant answer mode for high-stakes reads. It explains the same routing as ask_pipeworx but with extraction using only tool results, distinguishing it from its sibling. Specific verb 'EXTRACTS' and resource 'answer from tool result' provide clear 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 says 'Use whenever an answer will be quoted, cited, or acted on' and 'prefer ask_pipeworx for casual lookups'. Includes conditions for refusal reasons, giving clear when-to-use and when-not-to-use guidance.

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

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

The description extensively discloses behavioral traits beyond annotations: resolver contract (market_match_confidence, alternatives), parent event extraction, news fallback fields, safety mechanisms (low-confidence short-circuit, closed market handling, wide-spread liquidity notes), and resolution-rule risk (cancellation parsing). Annotations already declare readOnly, idempotent, non-destructive; the description adds critical context like how low-confidence matches block analysis. 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 lengthy but well-structured with labeled sections (RESPONSE SHAPES, RESOLVER CONTRACT, etc.) and front-loaded with the core purpose. Every sentence provides essential detail for a complex tool. While not terse, it earns its length through specificity and completeness. Slight reduction could be made without losing meaning, hence a 4.

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

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

Given no output schema, the description thoroughly covers all return values: market details (bid/ask, spread, liquidity, price change), analysis (model probability, edge, kelly fraction, 24h move warning), evidence sources, resolver match confidence, parent event extraction, news fallback fields, and safety checks. It is complete 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 a baseline of 3. The description adds substantial meaning: it explains the 'market' parameter accepts slug, URL, or question text; the 'depth' parameter controls quick vs thorough fan-out; 'include_raw' controls response size and format. It gives concrete examples of each, significantly enriching the schema's bare definitions.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies inputs (slug, URL, question text) and outputs (evidence packet + comparison). It also gives use cases like 'should I bet on X', 'what does the data say about Y'. This strongly differentiates it from siblings like polymarket_edges or ask_pipeworx, which have different scopes.

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 and examples (e.g., 'Use for "should I bet on X"'). It discusses when the tool short-circuits (low-confidence matches, closed markets) but does not explicitly state when not to use it or contrast directly with siblings. The context is clear enough for an agent to decide, but lacks explicit exclusions or 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?

The description adds significant behavioral context beyond annotations: it discloses data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), explains handling of off-calendar fiscal years, states results are sorted by primary metric, and mentions citation URIs. Annotations already mark it as read-only and idempotent, and the description aligns with that.

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 somewhat long but front-loaded with example queries that immediately convey purpose. Every sentence adds value, though it could be slightly more concise. The structure is logical: purpose, usage preference, type details, sorting, output.

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 adequately describes the return format (paired data + citation URIs). The tool is moderately complex with two types, and the description covers all necessary aspects: what each type retrieves, sorting behavior, and the efficiency benefit. 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% with descriptions for both parameters. The description adds meaning: for 'type', it explains the data each enum value retrieves; for 'values', it provides concrete examples (tickers for company, names for drug) and the range 2-5. This goes beyond the schema's bare descriptions.

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

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

The description clearly states the tool performs side-by-side comparison of 2-5 companies or drugs in one parallel call. It provides example user queries like 'Compare X and Y' and 'which is bigger / better', making the purpose immediately understandable. It distinguishes from sequential lookups by explicitly preferring this tool.

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

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

The description explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', giving clear guidance on when to use this tool. It also details what each type ('company' or 'drug') retrieves, helping the agent decide based on the entity type. There is no explicit when-not, but the context strongly implies this is the go-to for comparisons.

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 well beyond annotations by detailing the research mechanism (decomposition, parallel execution), output structure (verbatim evidence, confidence, source, fetched_at, citations, gaps array), and constraints (never invents). Annotations already mark readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false; description adds rich behavioral context.

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

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

The description is moderately long (~120 words) but well-structured: purpose first, then details, then usage guidelines. Every sentence provides useful information, though could be slightly more concise.

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

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

Despite the tool's complexity (parallel research, many sources, no output schema), the description fully explains input semantics, output structure, prerequisites, and caveats. It compensates for the lack of output schema by detailing return fields.

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 meaningful context: depth enum values mapped to numeric facets (quick=3, standard=5, thorough=8) and clarifes that question can be broad/multi-part. 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 the tool performs 'grounded multi-source research in one call', decomposing questions into sub-questions and routing to 3,745 tools. It distinguishes from sibling tool ask_pipeworx by specifying use case (broad/multi-part vs single lookups).

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

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

Explicitly says when to use ('broad or multi-part questions') and when not ('use ask_pipeworx for single lookups'). Also details prerequisites: requires Pipeworx account, sign-in via GitHub, and paid plan for 'thorough' depth.

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

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

Annotations already indicate safe, read-only, idempotent behavior. Description adds useful behavioral details: returns top-N relevant tools with full schemas and curated examples, ready to call directly. Could disclose edge cases like ambiguous queries, but overall is sufficient.

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

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

Description is informative but somewhat lengthy. Every sentence adds value, including the usage directive and return format. Could be slightly more concise, but structure is clear with front-loaded 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?

Completeness is high: describes return format (tool names, descriptions, full schemas), usage context, and example queries. No output schema needed because description adequately covers expectations.

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

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

Schema description coverage is 100% with detailed parameter descriptions. Description reinforces aliases for 'query' and provides concrete examples ('analyze housing market trends'), adding value beyond the schema.

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

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

Description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists numerous example domains (SEC filings, FDA drugs, etc.), distinguishing it from sibling tools that perform specific analyses rather than discovery.

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

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

Explicitly states when to use: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available.' Also implies when not to use by contrasting with direct calls to specific tools.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds value by explaining the parallel fan-out across sources, the fallback chain for news, and the soft-fail for patents. No contradiction with annotations.

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

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

Front-loaded with example queries and all key information is present. Slightly verbose with the detailed return value list, but every sentence earns its place. Good structure overall.

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?

Description covers the main return fields and limitations (patent sunset, CIK format). However, without an output schema, more detail on the shape of the returned data (e.g., JSON structure) would be helpful. Adequate for the 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 descriptions for both parameters. Description restates the same examples and limitations (ticker/CIK format, no names) without adding significant new 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?

Description clearly states the tool returns a full cross-source profile of a US public company in one parallel call. It lists specific data sources (SEC EDGAR, XBRL, USPTO, news, GLEIF) and what fields are returned. It distinguishes itself from chaining single lookups and from the sibling tool resolve_entity.

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 to use this tool when the user asks for a holistic view of a company and to prefer it over chaining. Provides when-not-to-use: if only a name is given, use resolve_entity first. Also notes the patent sunset limitation.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is already clear. The description adds no further behavioral context such as data freshness, model version, rate limits, or required permissions. With annotations handling the core traits, the description offers minimal additional transparency.

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

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

The description is a single sentence that efficiently conveys the tool's core capabilities: model, geography, and time horizon. It is front-loaded with the most critical information and contains no extraneous words. Every part of the sentence earns its place.

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

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

Given the tool's simplicity and the presence of a complete output schema and informative annotations, the description covers the essential elements (model, region, horizon). However, it could clarify that the place must be in Finland and mention output format details (though schema handles it). Overall, adequate for a basic forecasting tool.

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

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

Schema description coverage is 100% with all three parameters (place, timestep, parameters) described adequately. The description adds a top-level context (60-hour horizon) but does not enhance parameter semantics beyond what the schema already provides. Baseline score of 3 is appropriate since the schema bears the full load.

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

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

The description clearly states the tool provides a multi-hour HARMONIE forecast for a place name in Finland with a 60-hour horizon. It specifies the model, geography, and time range, making the purpose unambiguous. Although it doesn't explicitly distinguish from siblings, the sibling tools are mostly unrelated (e.g., bet_research, deep_research), so no confusion arises.

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 does not provide any guidance on when to use this tool instead of alternatives, nor does it specify prerequisites or usage contexts. Without recommendations on appropriate scenarios or exclusions, the agent lacks decision support for tool selection beyond the basic purpose.

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 destructive and idempotent hints. Description adds minor context about clearing sensitive data but lacks depth on permanence or side effects.

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 filler, front-loaded with main action and usage guidance.

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 delete tool with one parameter, the description covers purpose, usage, and parameter adequately given the available annotations.

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

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

Schema covers parameter 'key' with full description; description adds no new meaning beyond what schema provides.

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

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

Description uses specific verb 'delete' and resource 'previously stored memory by key', clearly distinguishing from sibling tools 'remember' and 'recall'.

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 (stale context, task done, clear sensitive data) and pairs with related tools.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds value by explaining the internal process (fetches the page, extracts title/description/key links) and the output format, which goes beyond what annotations provide.

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

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

The description is concise, front-loaded with the main action, and every sentence adds value. 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?

For a simple tool with well-documented schema and annotations, the description fully covers input, process, and output. The lack of an output schema is compensated by describing the output as 'a single text blob ready to drop at site-root/llms.txt'.

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

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

Schema coverage is 100% with both parameters described. The description adds minimal extra context (e.g., 'Full URL' vs just 'URL'), but does not significantly enhance understanding beyond the schema descriptions. Baseline 3 is appropriate.

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

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

The description uses a specific verb 'Generate' and resource 'llms.txt file for any URL', clearly distinguishing it from sibling tools like 'ai_visibility_check' or 'scan_competitor_ai_presence' which have different purposes. It also lists concrete 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?

The description states when to use the tool (getting a client's site indexed, drafting for own project, auditing a competitor), providing clear context. However, it does not explicitly mention when not to use it or name alternative 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 already declare the tool read-only, open-world, idempotent, and non-destructive. The description adds no additional behavioral context (e.g., data freshness, pagination, or availability limitations) beyond what annotations provide.

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

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

The description is a single brief sentence, which is concise. However, it lacks structure (e.g., bullet points for key details) and could be expanded slightly to convey more information without losing efficiency.

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

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

Given the low complexity and presence of an output schema, the description should still cover parameter usage and selection criteria. It does not, leaving critical gaps for an agent to correctly invoke the tool.

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

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

The description does not mention or explain the two parameters (place, parameters) at all. With 0% schema coverage, the description should compensate by clarifying the parameter format and allowed values, but it fails to do so.

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

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

The description states the tool returns 'most recent observation values for a place,' which gives a clear verb+resource. However, it does not distinguish from the sibling 'recent_observations' nor specify what counts as an observation (e.g., weather parameters), leaving room for ambiguity.

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

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

No guidance on when to use this tool versus alternatives like 'recent_observations' or 'forecast.' There is no mention of prerequisites or restrictions, leaving the agent without context for selection.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the description adds minimal behavioral context beyond listing return fields. 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: first defines function and output, second gives usage guidance. No unnecessary 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?

For a simple list tool with one optional param and no output schema, the description plus annotations cover purpose, usage, safety, and return fields completely.

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

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

Schema coverage is 100% for the single optional parameter, so the description doesn't need to add more. It doesn't mention the parameter, but the schema is sufficient.

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

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

The description clearly states the tool lists active subscriptions and returns specific fields. This distinguishes it from siblings 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?

The description provides explicit usage context: review before adding more subscriptions or to get IDs for cancellation. It could be improved by explicitly stating when not to use, but the guidance 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 are all false and provide no safety profile. The description compensates by disclosing rate limits (5 per identifier per day), that it's free, and doesn't count against tool-call quota. 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?

Well-structured with purpose first, then usage guidance, then constraints. Slightly lengthy but every sentence adds value. Could be slightly more concise but effective.

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

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

Given no output schema, the description adequately covers what the tool does, when to use it, and behavioral constraints. It provides enough context for an AI agent to invoke it correctly.

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

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

Schema has 100% coverage with descriptions for each parameter. The description adds extra context for the 'type' enum values and clarifies the 'context' object structure, 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 clearly states the tool's purpose: sending feedback about bugs, missing features, data gaps, or praise. It distinguishes itself from sibling tools by being the dedicated feedback mechanism among many analytical tools.

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

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

Explicitly provides when to use: for bugs, feature requests, data gaps, praise. Also specifies what not to do (don't paste end-user prompts, describe in terms of Pipeworx tools). Includes rate limits and quota info.

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-destructive, read-only, idempotent behavior. The description adds valuable details: data source (CF analytics-engine), no PII, caching policy (5min-1h window). 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?

Description is compact (4 sentences), front-loaded with core function, followed by use cases and technical notes. No redundant or irrelevant text.

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

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

For a simple tool with optional parameter and no output schema, the description covers purpose, use cases, data origin, caching, and privacy, leaving no ambiguity for an agent.

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

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

Schema has 100% coverage for the single parameter, but the description adds semantic guidance on window choice (shorter for hot, longer for steady-state), exceeding schema bare minimum.

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 trending data (top tools, packs, call volume) over configurable windows, distinguishing it from siblings like 'discover_tools' or 'ask_pipeworx'.

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

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

Three explicit use cases are provided, guiding appropriate scenarios. However, it does not mention when to avoid this tool or name direct alternatives among siblings.

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

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

Beyond annotations (readOnly, openWorld, idempotent), the description details internal logic (monotonicity violations, partition-sum checks, Jaccard similarity, placeholder filter) and explains output behavior (null arb signal if placeholder fraction >20%). No contradictions with annotations.

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

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

The description is front-loaded with the requirement, then explains modes in order. Every sentence contributes essential information (e.g., semantic anchor, partition filter, fill check). No redundancy; length is justified by complexity.

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

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

Despite no output schema, the description fully specifies the response structure (opportunities[], partition_check) and explains the fill check. References to polymarket_fill_risk for custom sizing ensure the agent understands next steps. Complete for a complex arbitrage detection tool.

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

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

Schema coverage is 100%, but the description adds substantial meaning: examples of valid inputs ('fed-decision-may-2026'), acceptance of full URLs, and contextual use cases for each parameter. The warning about no-args failure is also valuable 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: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes between two modes (event and topic) and differentiates from sibling tools like polymarket_edges and polymarket_fill_risk by focusing on arbitrage detection.

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 requires one of event or topic, warns that calling with no args fails. Provides guidance on when to use each mode (event for specific markets, topic for cross-event scanning) and mentions fill check with condition 'do not trade it'. References polymarket_fill_risk for custom sizing, offering clear alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds extensive behavioral context: explains three segments (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT) with their formulas, edge calculations (_net, kelly_fraction, etc.), response structure (by_segment, diagnostics), tradeable-edge knobs, and caching behavior. No contradictions with annotations.

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

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

The description is long but well-structured into logical sections (segments, knobs, response structure). Every sentence earns its place given the tool's complexity. A slight reduction could be possible (e.g., merging some details), but the level of detail is justified for a tool with 9 parameters and no output schema.

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

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

Despite no output schema, the description fully explains the return structure: per-opportunity fields (edge_pp_net, kelly_fraction, etc.), top-level segments (by_segment, fed_candidates/fed_note, diagnostics), and why segments might be empty. Caching is documented. All 9 parameters are covered. The description compensates entirely for the missing 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?

Input schema covers 100% of parameters with descriptions. Description adds significant value beyond schema: e.g., for slippage_pp it explains Polymarket fee structure and typical bid/ask spread; for min_partition_leg_kelly it clarifies relationship with min_kelly and why partition arbs need this separate filter. This enhances the agent's understanding of how to set each parameter correctly.

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 verb-resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly distinguishes from siblings like polymarket_arbitrage or polymarket_kalshi_spread by focusing on Pipeworx data disagreement, and states the primary use case: 'what should I bet on today'.

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: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' Mentions caching (1h at KV level) for efficiency. Does not explicitly state when not to use, but the context of sibling tools (e.g., polymarket_arbitrage for internal arbs) provides implicit guidance.

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

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

Annotations already declare readOnly, idempotent, non-destructive. Description adds critical behavioral details: daily closes not intraday, 60-day TTL, snapshot gaps, response structure. 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?

Though lengthy, content is well-organized with sections and bold key terms. Every sentence adds value; minor redundancy in LIMITS but overall efficient.

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

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

Despite no output schema, description fully explains response fields (tracked, expired, snapshot_dates) and their semantics. Also covers limits and snapshot gaps, making the tool's behavior self-contained.

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

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

Both parameters fully described in schema (100% coverage). Description supplements with default values, clamping, and window family options. No additional param details needed.

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?

Purpose is specific: edge persistence and decay telemetry from daily snapshots. Clearly distinguishes from sibling 'polymarket_edges' by focusing on time-series trends rather than raw current edges. Verb+resource+scope fully articulated.

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?

Implicitly guides use via the question 'how long has this edge existed and is it shrinking?' and LIMITS section explaining constraints. Does not explicitly contrast with alternatives, but context 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?

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses important behavioral traits: the tool requires one of 'market' or 'event', details the two modes and their outputs (including verdicts like 'clean|degraded|cannot_fill'), and warns about risks of partial basket fills. 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: first sentence states purpose, then required arguments, then detailed explanations of each mode, and finally usage advice. While it is somewhat lengthy, every sentence contributes essential information for a complex tool. It is front-loaded with the most critical info.

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

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

Given the tool's complexity and lack of an output schema, the description comprehensively explains return values for both modes. For single-market: top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict. For basket: theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg fill detail, thin_legs[], max_clean_notional_usd, forced_directional_risk. It also covers edge cases and risks.

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 covers 100% of parameters, but the description adds valuable context beyond schema definitions. For example, it explains the default 'side' behavior in basket mode ('auto — sell if partition sum > 1, buy if < 1') and the interpretation of 'size_usd' in basket mode as 'settlement notional — shares per leg'. This additional meaning justifies a score 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 explicitly states it performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth'. It clearly distinguishes between single-market and basket modes, and differentiates itself from sibling tools like 'polymarket_arbitrage' and 'polymarket_edges' by stating 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 clear usage guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It explains why this tool is necessary, including the risks of thin books and partial basket fills converting arbs into unhedged directional positions.

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

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

Description adds substantial behavioral context beyond annotations: details compatibility_warning triggers (bet shape mismatch, token overlap failure), temporal alignment flag, skipped comparison counters, and realism note about rare tradeable spreads. Annotations only provide readOnly/idempotent hints.

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

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

Description is long but well-structured with clear sections for modes, response, and safety fields. Could be more concise without losing critical detail. Information density is high, but verbosity may overwhelm.

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, description fully explains response structure (leg-by-leg prices, top_spreads_pp, safety fields, temporal alignment), parameter semantics, and edge cases. Comprehensive for a tool with 3 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 covers all 3 parameters (100% coverage), but description adds value by explaining mode interaction (topic vs explicit overrides), listing topic values, and providing examples. Exceeds baseline 3 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?

Description clearly states the tool computes cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes from siblings like polymarket_arbitrage and bet_research by focusing on cross-venue comparison with detailed mode explanation.

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?

Description explicitly covers two modes (topic shortcuts and explicit tickers), warns that most pre-mapped topics return compatibility_warning, and explains conditions for meaningful spreads (aligned temporal resolution, equivalent bet shapes). Provides when-not-to-use context implicitly through safety fields.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, indicating a safe read operation. The description adds valuable context beyond these annotations by specifying scoping ('anonymous IP, BYO key hash, or account ID') and explaining dual behavior (retrieve specific key vs list all keys). 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 sentences, front-loaded with the primary action. Every sentence adds value without redundancy or wasted words. Structurally 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 simplicity (one optional parameter, no output schema, clear annotations), the description covers all necessary aspects: purpose, usage, scoping, and sibling relationships. 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% with one optional 'key' parameter. The description adds meaning by explaining the effect of omitting the key ('list all saved keys') and connecting the value to the 'remember' action. This goes beyond the schema's basic description of the parameter.

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

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

The description explicitly states 'Retrieve a value previously saved via remember, or list all saved keys', specifying both the verb ('retrieve'/'list') and the resource ('values saved via remember'). It distinguishes from siblings 'remember' and 'forget' by name and provides concrete use cases like 'user's target ticker, an address, prior research notes'.

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

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

The description clearly states when to use the tool ('to look up context the agent stored earlier') and implies scoping ('Scoped to your identifier'). It mentions pairing with 'remember' and 'forget', but does not explicitly list when not to use it or name alternative tools for similar purposes, which prevents a perfect score.

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

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

Description discloses the mark_read parameter flags events as read, a state change, but annotations declare readOnlyHint=true, implying no write side-effects. This contradiction undermines transparency.

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

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

Description is front-loaded with purpose, then covers filtering, side-effects, and alternatives in a logical order. Slightly verbose with the JSON endpoint mention, but overall efficient.

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

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

No output schema, but description explains return fields. Covers key aspects: what it returns, filtering, side-effects, and polling behavior. Could briefly define 'alerts' or mention pagination, but sufficient given tool 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 descriptions for all 5 parameters. Description adds context (e.g., 'ISO timestamp' for since, 'default false' for boolean flags) but does not fundamentally extend schema meaning.

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

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

Description clearly states it pulls fired events from subscription feed, listing specific fields returned (source, citation_uri, raw event payload). However, it does not explicitly differentiate from sibling tools like 'recent_observations' or 'list_subscriptions'.

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

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

Provides explicit filtering options (type, since) and side-effect behavior (mark_read: true to flag events read). Mentions an alternative JSON endpoint for scripts/dashboards, implying when not to use the tool. Lacks direct 'when not to use' compared to specific siblings.

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

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

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description details fan-out behavior to multiple sources, fallback from GDELT to GNews, and soft-fail for patents. It also describes the return structure (changes grouped by source, total_changes count, citation URIs).

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

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

The description is long but well-structured, with example queries upfront and clear sections for behavior, parameters, and alternatives. Every sentence adds value, though some trimming could improve conciseness.

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 sources, fallback logic, multiple parameter formats, no output schema), the description is remarkably complete. It covers all necessary behavioral, semantic, and usage details, leaving no major gaps.

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

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

Although schema coverage is 100%, the description adds significant value: it explains the since parameter with examples (ISO date and relative shorthand), recommends typical values, and clarifies that value accepts ticker or CIK. This goes beyond the schema descriptions.

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

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

The description clearly states it is a 'change feed for a company' and lists example queries ('What's new with X', 'latest on Y'), making the purpose immediately clear. It also distinguishes from sibling tool entity_profile by specifying when to use that instead.

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

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

The description provides explicit when-to-use guidance with example queries, explains the data sources (SEC EDGAR, GDELT/Google News, USPTO) and fallback logic, and gives parameter usage tips (e.g., 'Use "30d" or "1m" for typical monitoring'). It also directs users to entity_profile for static profiles.

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 readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds no additional behavioral context, so it does not exceed the baseline expected from 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 extremely brief (one sentence) but is under-specified rather than concisely informative. It sacrifices clarity for brevity, making it less useful.

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

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

Despite having an output schema, the description leaves ambiguity about the nature of observations, expected data range, and how to interpret results. It is incomplete 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?

Only one of three parameters ('hours') has a description in the schema (1-48, default 6). The tool description does not explain 'place' or 'parameters'. With 33% schema coverage and no compensation, parameter semantics are poor.

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 'Last N hours of observations' indicates a time-window retrieval but is vague about what 'observations' refers to. It could imply weather, market data, etc., and does not distinguish from the sibling 'latest_observations' which likely has a similar 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?

No guidance is provided on when to use this tool versus siblings like 'latest_observations' or 'forecast'. The description lacks context about the data source, frequency, or limitations.

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 context beyond annotations: explains memory persistence (persistent for authenticated users, 24-hour for anonymous) and scoping by identifier. 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?

Description is concise (3 sentences) and front-loaded with purpose, followed by usage guidance and behavioral details. 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 the tool's simplicity (2 params, no output schema), the description fully covers purpose, usage, scoping, and persistence. 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%, and description adds value by providing example key patterns (e.g., 'subject_property', 'target_ticker'), which helps agents understand formatting.

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 'Save' and resource 'data to reuse later across conversations/sessions', directly addressing the tool's purpose. It distinguishes from siblings like 'recall' and 'forget' by mentioning 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?

Explicitly says 'Use when you discover something worth carrying forward' and provides examples (resolved ticker, target address, user preference). Also suggests pairing with recall and forget, guiding 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?

Description adds context beyond annotations: cascades internal lookups, auto-disambiguation, specific return fields (ticker, CIK, RxCUI) and citation URIs. No contradiction with annotations.

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

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

The description is well-structured and front-loaded but slightly verbose with citation URI details; 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?

Without an output schema, the description fully explains return values for each type and internal behavior, making it complete for the agent.

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

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

Schema coverage is 100%, but description adds valuable examples for each type and explains that company accepts ticker, CIK, or name, adding meaning beyond the schema.

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

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

The description clearly states the tool resolves names to canonical IDs, with specific examples (ticker, CIK, RxCUI) and distinguishes it from sibling tools by noting it's the first tool when needing an ID.

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

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

Explicitly says 'Use FIRST whenever you have a name but need an ID' and gives example queries. It also mentions it replaces manual lookups, providing clear when-to-use guidance.

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

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

Annotations already indicate readOnly, idempotent, non-destructive. The description adds details: the tool internally probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, signal density. This goes 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 four sentences, front-loaded with purpose, then mechanism, use case, and output. Every sentence is necessary 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?

Despite lacking an output schema, the description fully describes the return format. It explains the internal call to ai_visibility_check, the context parameter's purpose, and the role of the first entity. Complete 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 coverage is 100%, so the description adds value by clarifying that the first entity in the array is treated as the 'subject' for narrative purposes. This is extra context beyond the schema descriptions.

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

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

The description clearly states the tool compares AI visibility across multiple entities, using the verb 'compare', 'probes', 'ranks', and 'surfaces'. It distinguishes itself from the sibling ai_visibility_check by being a composite tool for competitive audits.

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

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

The description provides a clear use case (competitive AI-marketing audits) and implies when to use this tool over ai_visibility_check, but does not explicitly state when not to use it. However, it gives sufficient context for selection.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds valuable behavioral details: partial failures degrade gracefully, bundlephobia first measurement delay (5-30s), and sources_failed listing if timeouts occur.

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

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

The description is dense and informative, front-loading the purpose. It is a single paragraph but could benefit from structural breaks (e.g., bullet points for output fields). 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 the complexity (multiple data sources, partial failures, no output schema), the description fully explains the return structure (summary block fields, per-advisory, alternatives), behavior on failure, and ecosystem restrictions.

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 both parameters (package and version). The description adds clarity: version defaults to latest when omitted, and scoped packages (e.g., '@types/node') are accepted.

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: a composite check for adding an npm package, aggregating license, advisories, version history, and bundle size. It distinguishes from siblings by specifying NPM-only scope and mentioning alternatives for other ecosystems.

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

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

Explicit usage guidance: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also tells when not to use (non-npm packages) and directs to deps.dev:version directly.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds significant behavioral details: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation flag, and return format (offsets and similarity scores). 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?

Single paragraph, front-loaded with main purpose, no fluff. Every sentence adds value. Efficiently covers use case, technique, limits, and companions.

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

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

Despite no output schema, description explains return format (passages with offsets and scores), truncation behavior, and pairing with sibling tools. For a 3-param tool, this is fully complete.

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

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

Schema coverage is 100% (baseline 3). Description adds value by explaining each parameter's context: 'text' is document text with max chars, 'query' is natural-language with examples, 'limit' is max passages with range. Provides usage context 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 'semantic search INSIDE a fetched record' with specific verb and resource. It distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded and contrasts with whole-document fetching.

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

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

Explicitly tells when to use: 'when the record is too big to cram into the prompt.' Also suggests pairing with ask_pipeworx_grounded as an alternative workflow. Does not explicitly state when not to use, but the context is clear.

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

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

Annotations already indicate write, idempotent, not destructive. Description adds crucial details: OAuth requirement, persistence of subscriptions, return of new id, delivery constraints (SMS cap, webhook auto-disable, one-time secret). 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?

Description is long but well-structured: starts with purpose, then requirements, then types, then delivery. Every sentence adds value; could be slightly tightened but appropriate for 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?

No output schema, but description explicitly states returns new subscription id. Covers prerequisites, type options, delivery with constraints, and return value. Complete for a subscription creation tool.

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

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

Schema coverage is 100%, but description adds value with examples and constraints for each type and delivery channel, e.g., webhook auto-disabled after 10 failures. Adds meaning beyond schema.

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

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

Clearly states the tool creates a subscription, specifies the resource (live-data event stream), and mentions return value. Differentiates from siblings like list_subscriptions and unsubscribe.

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

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

Explicitly states requirement for Pipeworx OAuth account, lists supported types with examples, and explains delivery channel options and constraints. Could mention when to use vs. other tools like ask_pipeworx, but sibling set makes usage context clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. The description adds that the tool returns category-bucketed questions with tool+argument shapes, drawn from the live catalog. 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 front-loaded with the purpose and use case, then provides detailed output and usage. It is somewhat long but every sentence adds value, earning its length.

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, no output schema, and rich annotations, the description fully covers the tool's behavior, output structure, and usage context, including how it fits with meta-tools.

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

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

With 100% schema coverage, baseline is 3. The description adds value by explaining the 'topic' parameter is optional, giving example values, and clarifying that omitting it returns a full spread.

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

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

The description clearly states the tool returns example questions for onboarding, distinguishing it from siblings by being the entry point for new users. It uses specific verbs like 'returns category-bucketed example questions' and explains the 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 says 'Use this FIRST when you do not yet know what Pipeworx can do' and explains how to call with or without a topic filter. It implies when not to use by stating it's for onboarding, but lacks explicit exclusions.

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

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

The description explicitly states that the row is deactivated, not deleted, and that historical events remain available via recent_alerts. This goes beyond annotations (which indicate non-destructive mutation) and adds valuable behavioral context.

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

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

The description is three focused sentences: purpose, ownership constraint, and side effect. No filler, with critical information front-loaded.

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

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

The tool is simple (1 required param, no output schema), and the description covers purpose, constraints, and behavioral effects. It also references a related tool (recent_alerts), making it self-contained.

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 id parameter is already well-documented. The description adds ownership context related to the id, but does not significantly enhance parameter meaning beyond the schema.

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

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

The description clearly states the verb 'cancel' and resource 'subscription by id'. It distinguishes from sibling tools like 'subscribe' and 'list_subscriptions' through the cancel action and ownership enforcement.

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

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

The description specifies ownership enforcement ('you can only cancel your own subscriptions'), providing clear context for when to use the tool. However, it does not explicitly exclude other use cases or mention alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds valuable context beyond annotations: returns a verdict, structured form, actual value with pipeworx:// citation, percent delta, and specifies data sources (SEC EDGAR + XBRL). No contradiction with annotations.

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

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

The description is a single, informative paragraph that front-loads the purpose with examples. Every sentence adds value, though it is somewhat lengthy. No wasted words, but could be slightly more concise without losing clarity.

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

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

Given the tool's simplicity (one parameter), good annotations, and no output schema, the description fully explains return values, data sources, and usage context. It provides a complete understanding of what the tool does and what to expect, making it sufficient for an agent to invoke correctly.

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

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

Schema description coverage is 100% for the single 'claim' parameter, including an example. The tool description expands on the parameter by providing additional examples and context about supported claims. However, the schema already does the heavy lifting, so the description adds marginal but useful semantics.

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 specifies the tool's purpose: natural-language claim verification against authoritative sources. It provides example query patterns and explicitly states the domain (company-financial claims), distinguishing it from sibling tools like 'deep_research' or 'bet_research'.

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 includes explicit usage guidance: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also provides example natural language patterns. It does not explicitly list when not to use or name specific alternatives, but it implies a clear use case contrast with other tools by stating this replaces 4-6 sequential calls.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds value by specifying the geographic scope (Finland), the temporal nature ('currently active'), and the exact output format ('ISO bulletin XML returned as text'), which goes beyond what annotations provide.

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

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

The description is a single sentence with 12 words, front-loaded with the key purpose ('Currently active weather warnings'). Every word contributes essential information without redundancy or fluff.

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

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

Given that the tool has no parameters, strong annotations, and an output schema, the description covers all necessary aspects: what it returns, for which region, and in what format. No gaps or missing information.

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

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

The tool has no parameters, and the input schema is fully documented with 100% coverage. The description adds meaningful context about what the tool returns (weather warnings for Finland in XML format), which is appropriate for a zero-parameter tool.

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

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

Description clearly states it returns currently active weather warnings for Finland, specifying the output format as ISO bulletin XML returned as text. This is a specific verb-resource-scope combination that distinguishes it from siblings like 'latest_observations' or 'recent_alerts'.

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?

Description explains what the tool does but does not provide explicit guidance on when to use it versus alternatives. With many sibling tools, some might serve similar purposes, but no comparison or exclusions are given.

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