flood

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. Description adds behavioral details: free vs paid model distinction, direct payment to Anthropic, return format with per-model fields. No contradictions.

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

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

Two sentences: first covers core function and return format, second lists use cases. Every sentence adds value, no redundancy, front-loaded with key 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?

Despite no output schema, description includes return format overview (per-model fields + combined view). Covers all parameters, defaults, optionality, and use cases. Sufficient for correct tool invocation.

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

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

Schema coverage is 100%, baseline 3. Description adds examples for entity, clarifies supported models, explains _apiKey purpose, and context disambiguation role, providing practical usage value beyond schema.

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

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

Description uses specific verb 'probe' and resource 'LLMs', states scoring visibility 0-100 per model. Clearly distinguishes from sibling tools like entity_profile and scan_competitor_ai_presence by focusing on LLM knowledge probing.

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

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

Explains default model (free) and how to add Anthropic with own key, providing clear usage context. Lists use cases (AI-marketing audits, pre-launch brand checks). Implicitly when to use, though no explicit exclusions.

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

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

Annotations already indicate safe, read-only, idempotent behavior. The description adds that it returns structured answers with citation URIs and routes to many tools, complementing without contradicting.

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: bold preference, domain list, examples, alternatives. It is front-loaded and each sentence adds value. Could be slightly more concise, but 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 complexity (many tools, many domains) and no output schema, the description is thorough: purpose, usage, alternatives, examples, and hints at output format. It provides complete context for an agent to decide.

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% (6 params described). The description adds value by explaining the aliases for the question parameter, though it doesn't add much beyond that. Baseline 3, plus one for alias clarification.

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 answers factual questions with authoritative structured data, listing specific domains and providing examples. It distinguishes itself from web search and siblings like ask_pipeworx_grounded and deep_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 explicitly prefers this tool over web search for factual questions, provides extensive when-to-use guidance with examples, and tells when to step up to alternatives (grounded, deep_research).

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description adds value by detailing the extraction process, return fields, and refusal reasons. It also mentions cost, which is beyond the annotations.

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

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

The description is well-structured with front-loaded purpose, concise mechanics, and clear usage guidance. It is dense but not verbose, though it could be slightly trimmed without losing value.

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

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

Given the tool's complexity (hallucination-resistance, multiple refusal reasons) and lack of output schema, the description comprehensively covers return fields and failure modes, compensating fully 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?

Schema description coverage is 100% with all parameters clearly documented as aliases for 'question'. The description adds no additional parameter insights beyond what the schema provides, maintaining the baseline.

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

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

The description clearly states the tool's purpose as a hallucination-resistant answer mode for high-stakes reads, specifying it extracts answers from tool results with evidence or explicit refusals. It distinctly differentiates from sibling tool ask_pipeworx by highlighting the difference in 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 explicitly advises when to use this tool (high-stakes, fact-sensitive contexts) and when to prefer the sibling (casual lookups), including a cost consideration. This provides clear decision criteria for the agent.

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

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

Annotations indicate safe, idempotent, non-destructive behavior. The description adds extensive detail: fan-out process, response shapes, market_match_confidence, parent event extraction, news fallback, safety mechanisms (low-confidence, closed markets, wide spreads), and resolution-rule risk. 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 with sections (Classifiers, Fan-out, Response shapes, etc.). It front-loads the main purpose. Some redundancy (e.g., 'Use for' appears twice) but acceptable given the complexity.

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

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

Given the tool's complexity (3 parameters, no output schema), the description comprehensively covers inputs, behavior, output structure, edge cases, and safety. It leaves no significant gaps for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100% with descriptions for all 3 parameters. The description adds further meaning: explains market input types, depth options (quick vs thorough), and include_raw defaults with size implications.

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 researches a Polymarket bet by pulling Pipeworx data, with specific input formats (slug, URL, question text) and output (evidence packet + comparison). It distinguishes from siblings like polymarket_arbitrage and polymarket_edges, which focus on different tasks.

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 for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' Provides clear usage scenarios but does not explicitly mention when not to use or compare to alternatives.

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

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

Description adds significant details beyond annotations: handles fiscal year offsets, sorts results by primary metric, returns citation URIs. All annotations (readOnly, openWorld, idempotent) are consistent with description. 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?

Front-loaded with examples and key statement about preferring over sequential lookups. Slightly long but each sentence adds value. Could trim minor details 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?

Covers entity types, data sources, return format, and efficiency gain. No output schema but description mentions paired data + citations. Adequately complete for a complex tool with enum-based polymorphism.

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 both parameters with 100% coverage. Description enriches by explaining what data each type retrieves ('10-K revenue' for company, 'FAERS adverse-event counts' for drug) and value formats (tickers/CIKs, drug names).

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 states 'side-by-side comparison of 2–5 companies or drugs' with specific verbs like 'compare', 'rank', and explicitly notes it replaces sequential lookups, clearly distinguishing its purpose from sibling 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?

'ALWAYS PREFER over sequential single-pack lookups when comparing entities' provides clear usage guidance. Examples of queries ('which is bigger', 'X vs Y') cover common patterns. Lacks explicit when-not scenarios but context is strong.

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, openWorldHint, idempotentHint, destructiveHint=false. The description adds that it decomposes questions, routes to 4,482 tools in parallel, returns evidence with gaps, and has 15-60s latency. 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?

Description is about 8 sentences, each informative. Front-loaded with critical prerequisites (account required). Could be slightly more concise but well-structured and no extraneous 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?

Given the tool's complexity, the description covers prerequisites, use cases, limitations, output format (findings with evidence, gaps), and expected latency. No output schema but sufficiently describes return. Comprehensive for the tool.

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

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

Schema description coverage is 100%, baseline 3. The description adds value by explaining depth options (quick=3, standard=5, thorough=8) and that question can be broad/multi-part. This is more specific than the schema enum and text 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 explicitly states it performs 'Grounded multi-source research across Pipeworx's 1129 STRUCTURED data sources' returning a findings packet. It distinguishes from sibling tool ask_pipeworx (single lookup) and mentions alternatives for other use cases.

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

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

Provides explicit when to use (broad/multi-part questions over structured data), when not to (breaking news/current events), and alternatives (ask_pipeworx for single lookups or live news). Also notes account requirements 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 indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false, which the description does not contradict. Beyond annotations, the description adds that the tool returns top-N relevant tools with complete schemas and curated examples, ready for direct invocation, which is 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 front-loaded with the primary purpose and includes examples and usage guidance. It is a bit lengthy but each sentence contributes value. Could be slightly more concise but remains 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 the tool's low complexity (simple query with aliases) and no output schema, the description adequately explains what the tool returns: relevant tools with names, descriptions, and full schemas. It is complete for the task.

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

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

Schema coverage is 100%, so baseline is 3. Description adds value by explaining that 'query' accepts natural language with concrete examples ('analyze housing market trends', 'look up FDA drug approvals') and notes aliases (task, q, search, description). Parameter semantics are well clarified.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists extensive domains and uses a specific verb ('discover') that distinguishes it from sibling tools like 'search_within' or 'entity_profile', which are more specific.

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

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

The description explicitly states when to use: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It implies not for specific lookups, providing clear 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. Description goes beyond by detailing internal fan-out across multiple sources (SEC EDGAR, XBRL, USPTO, news, GLEIF), specifying return fields (CIK, filings with URIs, fundamentals sorted, patents with sunset note, news fallback, LEI), and noting soft-failure for USPTO. 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 concise but dense with information. Front-loaded with example queries and core purpose. Every sentence adds value, though length is slightly high. Still well-structured and efficient.

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

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

Given no output schema, description thoroughly explains return contents: CIK, company_name, recent_filings with URIs, fundamentals sorted, patents with limitation note, news via fallback, LEI. Covers edge cases (USPTO sunset) and provides enough context for an agent to understand what to expect.

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 both parameters with enums and descriptions, achieving 100% coverage. Description adds meaning by noting that value accepts ticker or zero-padded CIK and explicitly excludes names, and that type currently only supports 'company'. This provides helpful guidance beyond schema alone.

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

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

Description clearly states it produces a 'full cross-source profile of a US public company in ONE parallel call', with specific verb 'profile' and resource 'US public company'. It distinguishes from sibling tools like resolve_entity by stating names are not supported and that it should be preferred over chaining single-pack lookups for holistic views.

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

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

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

Annotations already provide destructiveHint=true, readOnlyHint=false, and idempotentHint=true. The description adds context about memory management but does not disclose additional behavioral traits beyond what annotations convey. No contradiction.

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

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

Two sentences, front-loaded with the primary action, and no extraneous information. Every sentence earns its place.

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

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

For a simple tool with one parameter, no output schema, and annotations present, the description is complete. It covers purpose, usage context, and sibling relationships.

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

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

Schema coverage is 100%, and the description does not add meaning beyond the schema. The schema already describes the 'key' parameter, so the description is adequate but not additive.

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

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

The description clearly states the action: 'Delete a previously stored memory by key.' It specifies the resource (memory) and the operation (delete), and distinguishes from siblings by referencing '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: 'when context is stale, the task is done, or you want to clear sensitive data.' It also indicates pairing with 'remember' and 'recall', providing guidance on alternatives.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior; description adds process details ('fetches page, extracts title/description/key links, emits standard format') and output format ('single text blob'), providing complete behavioral context beyond annotations.

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

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

Five sentences efficiently cover purpose, process, output, and use cases. Front-loaded with key action and result, no extraneous 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?

With no output schema, the description adequately explains the output format ('single text blob ready to drop at site-root/llms.txt'). Parameters are fully covered by schema, and annotations ensure behavioral context. Use cases complete the picture for a simple generation tool.

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

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

Schema coverage is 100% with both parameters (url, max_links) fully described in the schema. Description does not add additional parameter-specific information beyond what schema provides, so baseline score of 3 applies.

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

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

The description uses specific verb ('generate') and resource ('llms.txt file for any URL'), clearly distinguishing it from sibling tools like 'scan_competitor_ai_presence' which focuses on auditing rather than generation.

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

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

Provides three concrete use cases (client site indexing, own project drafting, competitor auditing) but does not explicitly mention when not to use or compare to alternatives like scan_competitor_ai_presence.

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

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

Annotations already show read-only, open-world, idempotent. Description adds behavior: returns multi-day projections, statistics, severity. No contradictions.

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

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

Two sentences, front-loaded with purpose and outputs. No fluff.

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

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

Annotations and output schema fill gaps. Description provides usage and output intent. Could mention output schema existence but not needed.

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

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

Schema covers 100% of parameters. Description adds context (location, multi-day) but not detailed per-parameter info. Baseline 3 due to high schema 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?

Clearly states the tool gets a multi-day flood forecast with specific outputs (current, mean, peak discharge, severity). Distinguishes from siblings like get_river_discharge by specifying forecast aspect.

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 to evaluate flood risk and timeline', giving clear usage context. Lacks explicit alternatives or when-not-to-use, but adequate given sibling set.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds no extra behavioral detail beyond mentioning 'forecast', which is already in the name. It correctly does not contradict annotations.

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

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

The description is three short sentences, each adding value: core action, output summary, and usage context. No redundant information, perfectly front-loaded with the essential 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?

The description provides enough context for the tool's purpose and output, especially considering the output schema exists. It could briefly mention that the location is specified by latitude/longitude, but that is covered by the schema. Overall, it is complete for a simple forecast 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%, so the schema adequately documents all parameters (latitude, longitude, forecast_days). The description does not add meaning to the parameters themselves, only to the output (cubic meters per second). Given high coverage, baseline 3 is appropriate.

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

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

The description clearly states the verb 'get' and the resource 'daily river discharge forecast' with specific units (cubic meters per second). It implies a use case for flood risk assessment, but does not explicitly distinguish from the sibling 'get_flood_forecast', missing a chance to clarify scope.

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 suggests monitoring water flow for flood risk assessment, providing some context. However, it does not explicitly state when to avoid this tool or mention alternative tools like 'get_flood_forecast' for more relevant scenarios, leaving usage guidance implied.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds extra behavioral context: it returns specific fields and clarifies that include_inactive controls inclusion of cancelled subscriptions. This aligns with annotations without contradiction.

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

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

The description is two sentences, directly stating the main purpose and return fields, followed by usage guidance. It is front-loaded and contains no fluff.

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

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

For a simple list tool with annotations and clear schema, the description covers the key aspects: what it does, what it returns, and why to use it. It does not mention pagination or limits, but given the tool's simplicity and annotations, this is acceptable.

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

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

Schema coverage is 100% with a clear description for the single parameter. The description reinforces the default behavior (active subscriptions) but does not add meaning beyond the schema. A score of 3 is appropriate as the description does not significantly enhance parameter understanding.

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

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

The description clearly states the verb 'list' and the resource 'the caller's active subscriptions', and specifies the return fields. It distinguishes itself from sibling tools like subscribe and unsubscribe by stating it's for reviewing before adding or finding an ID to cancel.

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

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

The description provides clear usage context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' It implies when to use this read tool relative to write tools, though it doesn't explicitly exclude alternative 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?

Discloses non-destructive nature (free, rate-limited, team reads daily, affects roadmap), complementing annotations that indicate no readOnly, idempotent, or destructive 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?

Concise yet comprehensive: front-loaded with purpose, followed by usage guidance and constraints, with no redundant statements.

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

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

Fully covers what an agent needs: feedback categories, contextual fields, message guidelines, rate limits, and impact on roadmap. No output schema needed for a non-query 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?

Adds substantial meaning beyond schema: explains enum values in detail, describes context object purpose, and specifies message content guidelines (be specific, 1-2 sentences, 2000 char max).

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 is for sending feedback about Pipeworx, specifying four categories (bug, feature/data_gap, praise) and distinguishing from data retrieval 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?

Explicitly explains when to use each feedback type, how to structure the message (refer to tools/packs, not user prompts), mentions rate limits (5/day), and clarifies it's free with no quota impact.

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 idempotent, read-only, and non-destructive behavior. The description adds valuable context: caching duration (5min-1h), data source (CF analytics-engine), and that it contains no PII. This goes well 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, with no wasted words. It uses bullet-like formatting for use cases, making it easy to scan. Every sentence adds meaningful information.

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

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

For a simple read-only tool with one optional parameter, the description fully covers what it returns (top tools, top packs, call volume), caching behavior, and data source. No output schema exists, but the description adequately describes the return value.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds semantic value by explaining the trade-off between window lengths ('shorter windows surface what's hot right now; longer windows show steady-state demand'), which aids parameter selection.

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

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

The description uses specific verbs and nouns: 'Returns the top tools, top packs, and total call volume over a recent window'. It clearly distinguishes the purpose from sibling tools, which are diverse and unrelated to trending analytics.

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

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

The description explicitly lists three use cases (discovering hot data sources, confirming canonical choices, seeing alignment), providing clear context for when to use the tool. It does not explicitly state when not to use it or name alternatives, but the context is sufficient.

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

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

Despite ample annotations (readOnlyHint, idempotentHint, openWorldHint), the description adds substantial behavioral detail: the mutual exclusivity of parameters, the algorithmic checks (Jaccard similarity, partition filter), the fill check sub-step, and when not to trade. 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 statement and purpose. It is comprehensive but slightly long; each sentence adds value. Could be tightened slightly but remains efficient.

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

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

Given the tool's complexity (two modes, multiple checks, no output schema), the description fully explains the response structure, the fill check, and conditions for null returns. It also directs to a related tool for custom sizing, ensuring completeness.

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

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

Schema coverage is 100%, but the description significantly enhances understanding by explaining how each parameter is used (e.g., event slug vs. seed question), providing examples, and detailing the behavioral differences between modes.

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

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

The description clearly states that the tool 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks', with distinct modes (event and topic). This distinguishes it from sibling tools like polymarket_edges, which likely focus on different aspects of Polymarket analysis.

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 guidance on when to use each mode: 'event (recommended for a specific market)' and 'topic (for cross-event scanning)'. It also warns about calling with no args and refers to polymarket_fill_risk for custom sizing. However, it does not directly compare to sibling tools like polymarket_edges.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds significant behavioral detail: caching at 1h, response structure with diagnostics, handling of Fed bets, and per-segment logic (e.g., placeholder-slug filtering). It fully explains what happens under the hood beyond any annotation.

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 excessively long and dense, with detailed technical formulas (e.g., 'lognormal barrier from 90d FRED log-returns') that are likely unnecessary for agent decision-making. It front-loads purpose but back-loads granular details, making it verbose. Every sentence adds some value, but conciseness is sacrificed.

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

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

No output schema exists, but the description comprehensively explains the response structure (by_segment segments, diagnostics, per-opportunity fields like edge_pp_net and kelly_fraction). It covers edge cases (Fed bets excluded, partition handling) and filter effects. The agent has all needed context 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%, so baseline is 3. The description adds value by explaining parameters as 'knobs' in context (e.g., 'Tradeable-edge filter' for min_liquidity and max_spread_pp) and their interactions. It ties parameters to real-world behavior, improving understanding beyond raw 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: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It immediately frames the use case ('what should I bet on today') and distinguishes three model segments. The verb 'scan' and resource 'Polymarket markets' are specific, and it differentiates from sibling tools by focusing on Pipeworx disagreement.

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

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

The description provides clear guidance: 'agents discover opportunities without paging hundreds of markets' and details tradeable-edge knobs like min_liquidity and max_spread_pp. It implies usage for identifying mispriced markets but does not explicitly state when alternatives (e.g., polymarket_arbitrage) are better suited. Still, the context is strong.

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

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

The annotations already declare readOnlyHint and idempotentHint, but the description adds rich behavioral context: detailed response fields (time-series, trend, decay), explanation of expired items and snapshot gaps, and caveats about daily closes vs intraday. 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 lengthy but packed with valuable information. It front-loads the purpose and then systematically explains the response structure. Some internal redundancies could be trimmed, but overall it earns 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 no output schema, the description fully documents the return values (tracked, expired, snapshot_dates) with field semantics and edge cases. It also covers limits and interpretation guidance, making it complete for this moderately complex tool.

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

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

The input schema covers both parameters with descriptions (100% coverage). The tool description merely restates the defaults and constraints without adding new meaning beyond the schema, so baseline 3 applies.

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

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

The description clearly states the tool's purpose: providing edge persistence and decay telemetry from daily snapshots. It uses specific verbs like 'answers' and defines the core question it resolves. It distinguishes itself from sibling tool polymarket_edges by focusing on time-series analysis rather than current edges.

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

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

The description implicitly guides when to use this tool by contrasting fresh vs. old edges, and it lists limits like 60-day TTL. However, it does not explicitly name alternative tools for current edge data (though sibling list includes polymarket_edges), leaving some ambiguity.

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

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

The description adds significant behavioral context beyond the annotations (readOnlyHint, idempotentHint, etc.). It explains that the tool checks order book depth without modifying state, details the return values (verdict, slippage, etc.), and warns about risks like partial basket fills. This fully aligns with annotations and provides agents with necessary safety information.

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

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

The description is well-structured with clear sections (REQUIRES, SINGLE-MARKET, BASKET) and front-loaded with the main purpose. While it is relatively long, every sentence contributes essential information given the tool's complexity. It could be slightly tighter but remains efficient.

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

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

The description thoroughly covers both modes, including specific return fields, edge cases (thin_legs, forced_directional_risk), and practical warnings. Despite lacking an output schema, the description compensates fully, making the tool's behavior and outputs predictable.

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

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

Although the input schema already describes every parameter (100% coverage), the description enhances semantics by explaining parameter behavior in different modes (single-market vs basket), defaults (side auto-detection in basket), and interpretation of size_usd. This adds value beyond the schema, justifying a score above baseline.

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

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

The description clearly states the tool's purpose: "Realizable-vs-theoretical edge check against live CLOB order-book depth." It distinguishes between single-market and basket modes, specifying what each does and what it returns. This is specific and differentiates it from sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

The description explicitly advises when to use this tool: "USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500." It also explains why (theoretical overround not capturable, partial fills create unhedged positions), providing clear context and 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 mark the tool as read-only and non-destructive. The description adds extensive behavioral details: two modes, response structure, safety fields (compatibility_warning, temporal_alignment, skipped counters), and the caveat that pre-mapped topics often return warnings. No contradiction with annotations.

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

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

The description is front-loaded with the core purpose and modes, then logically details response and safety fields. While slightly verbose for a simple tool, the complexity of cross-venue spread justifies the length. Every sentence adds value, but minor redundancy could be trimmed.

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

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

Given the tool has no output schema, the description fully covers the response structure, including leg prices, top spreads, and safety fields like compatibility_warning and temporal_alignment. It addresses edge cases (non-equivalent bet shapes, temporal misalignment) and explains counters, making it complete for agent usage.

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

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

Schema coverage is 100%. The description adds meaning by explaining how topic maps to shortcuts (with list), how explicit parameters override, and the relationship between modes. Examples are given (e.g., 'fed', 'btc'), enhancing 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 computes cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes from siblings like polymarket_arbitrage by emphasizing the cross-venue nature and explaining the two modes (topic and explicit). The verb+resource is specific and unambiguous.

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

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

The description provides explicit guidance on when to use each mode (topic shortcuts vs explicit tickers) and includes warnings about when spreads are not meaningful (compatibility_warning cases). It notes that real spreads are rarer than the macro shortcut list suggests, helping agents avoid false positives.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint as true/true/false, covering safety. The description adds useful context: scoping to identifier (anonymous IP, etc.), and explains the tool's role in the remember/forget ecosystem. No contradiction with annotations.

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

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

Two sentences, front-loaded with the core action. Every sentence adds value; no wasted words.

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

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

For a simple tool with one optional parameter and no output schema, the description covers all essential aspects: purpose, usage, scoping, and relationship to sibling tools. Nothing missing.

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

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

Schema coverage is 100% and already explains that omitting key lists all keys. The description reinforces this but doesn't add additional 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 the action ('Retrieve a value... or list all saved keys') and the resource (values saved via remember), with specific verb-resource pair. It explicitly distinguishes from siblings remember and forget, making it unambiguous.

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

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

Explicitly states when to use the tool ('to look up context the agent stored earlier') and when not (omitting key for listing). Provides context on scoping and pairing with remember/forget for alternative actions.

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

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

Discloses key behaviors: mark_read modifies read state (non-destructive but stateful), polling works fine, and the return payload structure. Adds value beyond annotations which only hint at read-only and idempotent; description handles the nuance of stateful read marking without contradiction.

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

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

Efficient three-sentence structure: first sentence states purpose and return, second details fields, third covers filtering and mark_read. No unnecessary words; information is front-loaded and easily parseable.

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

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

Given no output schema, description covers return fields (source, citation_uri, payload), filtering, mark_read, polling, and alternative endpoint. Sufficient for an agent to understand usage and behavior without gaps.

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

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

Schema covers 100% of parameters with descriptions. The description adds context with an example for type ('sec_8k') and explains the effect of mark_read, enhancing understanding beyond schema basics.

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 'Pull fired events from your subscription feed' with specifics about return fields (source, citation_uri, raw payload). It distinguishes from sibling tools like list_subscriptions by focusing on alerts (events) rather than subscriptions themselves.

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 filtering examples (type, since), explains mark_read for read tracking, and mentions polling suitability. Also gives an alternative endpoint for scripts. Lacks explicit comparison to sibling tools or when not to use, but guidance is clear and helpful.

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, such as fanning out to multiple sources, fallback logic, and handling of API limitations. Annotations already indicate read-only, open-world, idempotent, and non-destructive, and the description complements these without contradiction.

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

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

The description is well-structured with examples, fallback details, and a clear pointer to the sibling tool. While it is somewhat verbose, every sentence adds value, and key information is front-loaded with query patterns.

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

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

Despite lacking an output schema, the description fully specifies the return structure (changes grouped by source, total_changes count, citation URIs). It covers all relevant aspects for a complex data aggregation tool, making it self-sufficient.

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

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

Schema coverage is 100%, but the description enriches parameter meaning by explaining the 'since' format with examples and suggesting typical values like '30d'. It also clarifies that 'type' is limited to 'company' and 'value' accepts tickers or CIKs, adding practical guidance.

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

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

The description clearly states that the tool provides a change feed for a company by aggregating SEC filings, news, and patents. It uses precise verbs like 'fans out' and explicitly distinguishes from the sibling tool 'entity_profile', which provides static profiles.

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

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

The description gives concrete example queries (e.g., 'What's new with X', 'latest on Y') and explicitly advises when to use the alternative tool 'entity_profile' instead. It also details the fallback mechanism from GDELT to GNews and notes the PatentsView API sunset, guiding appropriate use.

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

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

Description adds value beyond annotations: explains scoping by identifier, retention policies, and that it's a key-value store. Works well with idempotentHint=true and destructiveHint=false 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?

Four sentences, front-loaded with purpose. Information is well-organized but 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?

Given the simplicity (2 required params, no output schema), the description covers purpose, usage, behavior, and persistence adequately. No 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?

Schema already has 100% coverage with good descriptions. Description adds context but does not significantly enhance parameter semantics 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?

The description clearly states the tool saves data for reuse across conversations/sessions. It gives specific examples (ticker, address, preference) and distinguishes from sibling tools recall and forget.

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

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

Explicitly tells when to use the tool ('when you discover something worth carrying forward') and provides context on pairing with recall and forget. Also covers persistence differences for authenticated vs anonymous sessions.

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 adds significant behavioral context: it cascades through several endpoints, auto-disambiguates, and returns specific fields (ticker, CIK, company_name for company; RxCUI, ingredient, brand for drug) with 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, front-loaded with example queries, then detailing supported types and return values. Every sentence adds value, though it is slightly lengthy. It could be trimmed without losing essential info, but overall it's effective.

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

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

With only 2 parameters and no output schema, the description fully explains the tool's behavior: what it returns per type, internal cascading, and disambiguation. It covers the core use case completely, including citation URIs. No output schema is needed given the detailed return descriptions.

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

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

Schema coverage is 100%, but the description enriches both parameters: for 'type' it lists supported values with context, for 'value' it provides detailed input format examples (ticker, CIK, name for company; brand/generic for drug). The schema's own descriptions are minimal, so the description adds substantial 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?

The description clearly states the tool resolves names to canonical identifiers, with specific examples (e.g., ticker, CIK, RxCUI) and supported entity types (company, drug). It distinguishes itself from sibling tools like compare_entities or entity_profile by focusing on ID resolution, and uses strong verbs like 'resolve' and 'look up'.

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 FIRST whenever you have a name but need an ID', providing clear when-to-use guidance. It also explains that it replaces multiple lookups, but lacks explicit when-not-to-use scenarios or alternatives. The supported types and input formats are well-detailed.

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

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

Annotations declare readOnlyHint, idempotentHint, and no destructive behavior, which the description aligns with by describing a comparative probe operation. The description adds valuable behavioral details: 'probes each entity with ai_visibility_check, ranks by score, surfaces which is most/least recognized', and specifies the return format with score, confidence, and signal density per entity.

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 uses two well-structured sentences. The first clearly states the action and method, the second provides usage context and output summary. Every sentence adds value without unnecessary words.

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

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

Given no output schema, the description adequately describes the return format (ranked list with score, confidence, signal density). It explains the mechanism (probing each entity with ai_visibility_check) and covers all parameters implicitly. For a tool with 4 parameters and no nesting, this is 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?

With 100% schema coverage, baseline is 3. The description adds meaning by noting the first entity is treated as the 'subject' for narrative and that context is shared across probes. This goes beyond the schema's descriptions, particularly for the entities and context parameters.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, using a specific verb 'compare' and resource 'AI visibility'. It distinguishes from siblings like ai_visibility_check (single entity) and compare_entities (more general) by specifying it probes each entity with ai_visibility_check and ranks by score.

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 it is 'useful for competitive AI-marketing audits' and provides an example question. While it does not explicitly state when not to use it or name alternatives like ai_visibility_check for single entities, the context is clear and logically implies its appropriate use for multi-entity 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?

Discloses composite fan-out, partial failure degradation, and first-measurement delay. Annotations already indicate read-only, idempotent, non-destructive; description adds valuable behavioral detail without contradiction.

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

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

Dense single paragraph with all key info; slightly long but no redundancy. Could benefit from bullet points, but still 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?

For a 2-parameter tool with no output schema, description fully covers return fields, limitations, and ecosystem scope. Annotations complement behavioral aspects, making it 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 100%, but description adds value: explains scoped packages, default version behavior, and lists return fields (summary, advisories, alternatives).

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 aggregates npm package checks from deps.dev and bundlephobia, answering safety, popularity, size. Distinguishes from sibling tools by specific scope and composite nature.

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 ('is X safe / popular / small', 'what does adding lodash cost me') and ecosystem limitation (NPM only), with fallback guidance for other ecosystems.

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

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

Adds details beyond annotations: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation flagging, and character offset per passage. 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 detailed yet concise; each sentence adds value. Front-loaded key purpose and usage scenarios. No unnecessary words.

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

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

Despite no output schema, description clearly states return value format: top-N passages with offsets and similarity scores. Also covers input constraints (200K cap) and behavior (truncation flag). Complete for this tool's complexity.

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

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

Schema coverage is 100% but description adds valuable context: 'Pass the text you already pulled' for text, natural-language query examples for query, and limit range with default. Not drastically new but enriches understanding.

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

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

Description clearly states 'Semantic search INSIDE a fetched record' with specific verb and resource. Provides examples (SEC 10-K, article) and distinguishes from siblings by contrasting with ask_pipeworx_grounded and stating when to use.

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 the record is too big to cram into the prompt' and 'Pairs with ask_pipeworx_grounded' offering an alternative workflow. Prerequisite implied by 'Pass the text you already pulled'.

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 discloses behavioral traits beyond annotations: requires OAuth, returns subscription id, delivery channel limitations (SMS cap, auto-disable webhook), and verification requirements. 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 with the main purpose. It is somewhat lengthy but every sentence adds value, balancing detail with 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 complexity (3 params, nested objects, multiple delivery channels), the description is thorough: covers requirements, supported types with examples, delivery options with limitations, and return value. No output schema exists, but the description compensates.

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 description coverage, the description adds significant meaning to parameters with examples, constraints (e.g., required params for each type), and details on delivery options (email validation, SMS verification, webhook signing).

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

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

The description clearly states the action ('Create a proactive monitoring subscription'), the resource ('live-data event stream'), and the return value ('Returns the new subscription id'). It distinguishes from sibling tools by detailing specific subscription types and delivery channels.

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 the requirement for a Pipeworx OAuth account and mentions supported types and delivery channels, providing context for when to use. It does not explicitly compare to siblings like list_subscriptions or unsubscribe, but the usage 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 cover safety (readOnly, idempotent, non-destructive). The description adds behavioral context: it returns examples from the live catalog, explains output structure (category-bucketed), and clarifies behavior with/without arguments. 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?

Highly efficient: front-loaded with alternative phrasings and purpose, then describes output, then usage. Every sentence earns its place. No redundancy or filler.

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

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

Given the tool's simplicity (1 optional param, no output schema), the description fully covers purpose, usage, and output. Annotations handle safety. No missing information for correct agent invocation.

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

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

Schema coverage is 100% with a clear description of the topic parameter. The main description reinforces this and adds usage nuance (e.g., 'pass `topic` to focus') and lists example values, providing extra context beyond the schema.

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

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

The description clearly defines the tool as the onboarding entry point, listing alternative user phrasings and stating it returns category-bucketed example questions with exact tool+argument shapes. This distinguishes it from sibling tools like ask_pipeworx or search-focused 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 says 'Use this FIRST' and provides specific when-to-use scenarios (agent new to Pipeworx, learning meta-tools). Also explains how to call without arguments for full spread or with topic for focus. No when-not-to guidance needed given its introductory role.

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 value beyond annotations: it specifies that rows are deactivated rather than deleted, preserving historical events for 'recent_alerts'. Annotations indicate non-destructive and idempotent, which aligns. The description explains the exact behavior, which is helpful.

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

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

The description is very concise: two sentences that efficiently convey all necessary information without any fluff. It is front-loaded with the primary action and resource, then adds critical behavioral details.

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

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

Given the tool's simplicity (one parameter, no output schema), the description covers all essential aspects: the action, ownership constraint, and the deactivation vs deletion nuance. It is complete for an AI agent to understand usage.

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

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

The input schema already fully describes the single 'id' parameter with 100% coverage. The description does not add new semantic information about the parameter beyond what the schema provides, so a baseline score of 3 is appropriate.

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

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

The description clearly states the action 'Cancel a subscription' and the resource 'by id'. It distinguishes itself from siblings like 'subscribe' and 'list_subscriptions' by specifying the cancellation function. Additional details about ownership enforcement and deactivation further clarify the 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?

It provides clear context for when to use the tool: when you want to cancel your own subscription. It also mentions ownership enforcement, implying only self-owned subscriptions. However, it does not explicitly state when not to use or list alternative tools, though no direct alternative exists.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds specific behavioral details: returns a verdict with five possible outcomes, a structured form, actual value with pipeworx:// citation, and percent delta. This enriches the agent's understanding beyond the annotations.

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

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

The description is two tight sentences with no extraneous words. It front-loads the purpose with trigger phrases, then efficiently specifies scope and outputs.

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 clearly lists the return fields (verdict, structured form, actual value, citation, delta). For a simple one-parameter tool with rich annotations, this is fully adequate.

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 single 'claim' parameter has 100% schema coverage, and the description provides concrete examples (e.g., 'Apple's FY2024 revenue was $400 billion') and explains the natural-language format. This adds significant meaning beyond the schema alone.

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

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

The description starts with natural-language triggers ('Is it true that…', 'fact check') that make the tool's purpose immediately clear. It specifies the domain (company-financial claims via SEC EDGAR + XBRL) and notes it replaces multiple sequential calls, effectively distinguishing it from sibling research tools.

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

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

The description explicitly directs agents to use this tool whenever factual verification is needed, and limits usage to company-financial claims. It provides context on what kinds of claims are supported, but does not explicitly list when not to use it or alternative tools for other claim types.

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