Serper

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

Annotations already indicate the tool is read-only, idempotent, and non-destructive. The description adds the return format (per-model details plus combined view) and the BYO key requirement for Anthropic, providing useful behavioral context beyond annotations.

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

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

The description is concise yet comprehensive, front-loading the primary function and then adding details about models, cost, and return structure. Every sentence adds value with no redundancy.

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

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

Despite lacking an output schema, the description fully explains the return format (per-model and combined). All 4 parameters are described, and the tool's purpose is fully covered given its complexity and sibling context.

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

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

Schema coverage is 100%, but the description adds meaning: it explains the default model, the free tier, and the need for an API key when probing Anthropic. It also clarifies the 'context' parameter's purpose for disambiguation.

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

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

The description clearly states the tool probes LLMs for knowledge about a business/brand/product/topic and returns a visibility score (0-100). It specifies default and optional models, which distinguishes it from sibling tools that likely focus on other data sources or actions.

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

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

The description explicitly lists use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. While it does not mention when not to use or name specific alternatives, the context is clear and sufficient for an agent to decide.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds that the tool routes to the appropriate source, fills arguments, and returns structured answers with stable citation URIs, which is useful beyond annotations.

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

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

The description is relatively long but well-structured: starts with preference claim, then domain list, usage guidance, examples, and alternatives. Every sentence adds value, though it could be slightly more concise without losing clarity.

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

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

For a complex routing tool with no output schema, the description clearly explains what it does, when to use it, what it returns (structured answer with citations), and how it differs from siblings. It's thoroughly 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 documentation covers 100% of parameters, so baseline is 3. The description provides examples but doesn't add semantic detail beyond what the schema says (natural language question). No additional constraints or usage notes for 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 routes questions to one of 4,482 tools across 1129 sources, returning structured answers with citations. It distinguishes from siblings like ask_pipeworx_grounded and deep_research, and provides specific domains and examples.

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

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

Explicitly says 'PREFER OVER WEB SEARCH' for factual queries and 'START HERE for most questions'. Lists when to step up to alternatives (grounded for verbatim evidence, deep_research for broad questions). Includes examples and conditions.

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

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

Annotations already declare readOnlyHint and idempotentHint. Description adds valuable context: hallucination-resistance, one extra LLM call, and explicit refusal reasons. 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 front-loaded with purpose and mechanism, followed by return format and usage guidance. Each sentence adds value, though slightly verbose; could be tighter but still efficient.

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

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

Despite no output schema, description fully explains return format including fields and possible refusal reasons. Covers decision logic, use cases, and comparison to sibling, making it self-contained and complete.

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

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

Schema coverage is 100% with all six parameters as aliases for 'question'. Schema description sufficiently explains each alias. Tool description does not add extra meaning beyond what schema provides, so baseline score 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?

Description clearly states it is a 'hallucination-resistant answer mode for high-stakes reads' and explains the process: picks tool, fetches data, extracts answer using only tool result. Distinguishes from sibling ask_pipeworx by noting extra cost and appropriate use cases.

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

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

Explicitly specifies when to use: 'whenever an answer will be quoted, cited, or acted on' and gives concrete examples (financial, legal, medical, public statements). Also advises to prefer ask_pipeworx for casual lookups, providing clear when-not 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?

Beyond annotations (readOnly, idempotent, non-destructive), the description details resolution logic, fan-out behavior, error handling, response shapes, and edge cases. No contradiction with annotations.

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

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

Long but justifiably so given complexity. Front-loaded with purpose and classifiers. Could be more structured but every sentence adds value.

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

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

Completely covers output fields, error conditions, safety mechanisms, and resolver contract. Without output schema, the description fully substitutes.

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 significant meaning beyond schema: explains market_input formats, depth levels, include_raw effect. Schema coverage is 100%, but description enriches with examples and behavioral details.

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 Polymarket bets by pulling Pipeworx data. It provides specific use cases like 'should I bet on X' and distinguishes from siblings by focusing on betting-specific 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?

Explicitly when to use: for betting questions. Provides examples of market inputs (slug, URL, question) and classifiers. Includes safety instructions and when results should not be trusted (low confidence, closed markets).

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

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

Beyond annotations (readOnly, openWorld, idempotent, not destructive), the description adds behavioral details: off-calendar fiscal year handling for companies, results sorted by primary metric, and return of paired data with citation URIs. No contradictions with annotations.

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

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

Single, well-structured paragraph front-loaded with query patterns, then details. Every sentence adds value; no filler. Efficiently covers purpose, usage, data specifics, and output format.

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 tool complexity (two entity types, dynamic data sources, sorting, citations), the description covers all key aspects: when to use, what data is returned, how results are ordered, and special handling (off-calendar years). No output schema needed; description adequately specifies return format.

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

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

Schema coverage is 100%. Description adds meaning beyond schema: explains what data each type pulls, gives examples of valid values (tickers/CIKs for company, drug names), and specifies min/max constraints. This helps the agent choose correct formats.

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

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

The description clearly states the tool does side-by-side comparison of 2–5 companies or drugs, specifying data sources (SEC EDGAR for companies, FAERS for drugs). It distinguishes itself from siblings by explicitly advising preference over sequential single-pack lookups, and lists example query patterns.

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 usage guidance: common query patterns like 'compare X and Y', 'which is bigger', 'rank these companies'. It states 'ALWAYS PREFER over sequential single-pack lookups', implying when not to use (single-entity lookups should use other tools like entity_profile).

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, and open-world. The description adds substantial behavioral context: parallel decomposition across 4,482 tools, return format (findings packet with evidence, confidence, gaps), expected latency (15-60s), and limitations (no current news, returns gaps when topic is not in structured catalog). 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 relatively long but well-structured with clear sections: account requirement, usage guidance, behavior, timing, examples. Every sentence provides useful information, though minor redundancy could be removed (e.g., mentioning ask_pipeworx multiple times). Front-loaded with critical account info.

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

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

Given the tool's complexity (2 params, no output schema, many siblings), the description is remarkably complete. It explains input, output format, limitations, account requirements, alternatives, and expected behavior. No obvious gaps for an agent to misinterpret.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds value by clarifying the enumeration for depth (quick=3, standard=5, thorough=8) and emphasizing that the question should be broad/natural language. This enriches the semantic understanding 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 clearly specifies the tool's purpose: grounded multi-source research across Pipeworx's structured data sources. It uses specific verbs ('researches', 'decomposes', 'routes'), identifies the resource (1129 structured data sources), and distinguishes it from siblings like ask_pipeworx by stating it is NOT open-web search and is best for broad/multi-part questions.

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

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

Excellent usage guidance: explicitly states when to use this tool (broad/multi-part questions over structured data) vs. alternatives (use ask_pipeworx for single lookup or current news). Also notes account requirements (free sign-in, paid for 'thorough' depth) and provides a fallback tool if not signed in.

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

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

Annotations already provide readOnlyHint=true and idempotentHint=true, so safety is clear. The description adds behavioral context beyond annotations: it returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples)' and states 'each result is ready to call directly, no second schema lookup needed'. 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 purpose and flows logically through usage scenarios, return format, and guidance. It is somewhat verbose due to the long list of domains, but each sentence serves a distinct purpose and adds value.

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

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

Given 6 parameters, many siblings, no output schema, the description covers: core purpose, common use cases, return format (top-N, ready to call), and when to use. It lacks details on ambiguity handling or relevance ranking, but is sufficiently complete for a discovery 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 baseline is 3. The description does not add significant parameter semantics beyond the schema—it only mentions 'top-N' (related to limit) and 'query' implicitly. The description's main value is usage context, not parameter details.

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

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

The description uses a specific verb ('Find') and resource ('tools'), and explicitly lists many domains (SEC filings, FDA drugs, etc.). It distinguishes from sibling tools by advising 'Call this FIRST when you have many tools and want to see the option set', making the purpose unique.

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

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

The description clearly states when to use: 'Use when you need to browse, search, look up, or discover what tools exist for...' and 'Call this FIRST when you have many tools available'. It implicitly suggests not using it when you already know the target tool, but does not explicitly name 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?

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. The description adds context about the patent soft-fail and the multi-source fan-out, which are useful behavioral traits beyond annotations. No contradiction.

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

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

The description is fairly long but well-structured with examples at the start and a clear list of return fields. Each sentence adds value, though some could be slightly more concise without losing 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 complex tool with no output schema, the description comprehensively lists return fields (cik, company_name, recent_filings, fundamentals, patents, news, LEI) and mentions limitations (patent sunset, name not supported). This provides sufficient context for correct invocation.

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

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

Schema coverage is 100%, but the description adds significant semantic value: explains that 'value' can be a ticker or zero-padded CIK, names are not supported, and suggests using resolve_entity. This goes beyond the schema's basic type descriptions.

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

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

Description uses specific verbs ('get full cross-source profile') and examples ('Tell me about X', 'brief me on Tesla') to clarify the tool's purpose. It explicitly distinguishes itself from chaining single-pack lookups, making the purpose unambiguous.

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

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

Strong guidance: states 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' and advises using resolve_entity first if only a name is provided. This helps the agent decide when to use this tool versus alternatives.

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

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

Annotations already declare destructiveHint=true, description confirms deletion and adds context about sensitive data. No contradiction, but description adds little beyond annotations.

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

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

Two sentences, front-loaded with purpose, no wasted words. Efficient and clear.

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

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

Covers purpose, usage, and sibling context. No output schema, but return behavior is implied by deletion. Minor gap: no mention of success/failure indication.

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%; schema describes 'key' as 'Memory key to delete'. Description adds no additional meaning beyond referencing 'by key'.

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 specifies 'delete a previously stored memory by key', uses specific verb and resource. Distinguishes from siblings 'remember' (store) and 'recall' (retrieve).

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, task done, or clearing sensitive data. Mentions pairing with 'remember' and 'recall' for alternative operations.

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?

Describes the process: fetches page, extracts title/description/key links, emits standard markdown. Adds context beyond annotations (output format, placement). No contradiction.

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

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

Four sentences, front-loaded with purpose and format. Every sentence adds value. No redundancy or fluff.

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

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

For a simple tool with robust annotations, the description fully covers purpose, usage, process, and output. No gaps given the parameter count and lack of 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 covers both parameters (100%). Description adds useful context for max_links (default 25, max 50) beyond schema. URL parameter is clear from description context.

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 'generate' and the resource 'llms.txt file for any URL'. It distinguishes from siblings like 'ai_visibility_check' and 'scan_competitor_ai_presence' by focusing specifically on llms.txt 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?

Explicitly lists use cases: getting a client's site indexed, drafting for own project, auditing competitor. Does not exclude alternatives but context is clear.

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

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

Annotations already provide readOnlyHint, idempotentHint, etc. Description adds return field details but no additional behavioral context beyond annotations. Minimal added value.

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

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

Two sentences, no wasted words, front-loaded with action and purpose. Efficient and clear.

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

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

Given simple tool with one optional parameter and no output schema, description covers return fields and usage context adequately. Lacks explanation of default behavior but still complete enough.

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 single boolean parameter described in schema. Description does not add meaning beyond what's in the schema.

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

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

Clearly states 'List the caller's active subscriptions' with specific return fields. Distinguishes from sibling tools (subscribe, unsubscribe) by indicating it's for review.

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

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

Explicitly says 'Use this to review what you're monitoring before adding more or to find an id to cancel', giving clear when-to-use and how it relates to other 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?

Annotations already declare idempotent, non-destructive, read-only. The description adds value by detailing the return fields and mentioning the optional API key, which provides context about rate limits or usage.

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?

A single sentence that efficiently conveys purpose, output details, and main parameters. 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 no output schema, the description adequately explains the return format (title, link, etc.). It also addresses the optional API key and max results. Complete for a simple news search 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% and descriptions are present. The top-level description reinforces parameter details (query, num, gl) but does not add new meaning beyond what the 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 it performs 'Google News search via Serper' and returns specific fields (title, link, snippet, source, date). It distinguishes itself from siblings like 'search' and 'places' by specifying news-only results.

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

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

The description explains what the tool does and its parameters but does not explicitly guide when to use it over alternatives like 'search' or when not to use it. The naming implies news-specific use, but no explicit guidance is given.

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

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

Description discloses rate limit (5 per day), no quota cost, and that feedback is read daily. Annotations only show readOnlyHint false, so description adds significant 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?

Description is well-structured, front-loaded with purpose, then usage guidelines. A bit lengthy but every sentence adds value. Concise for the information provided.

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

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

Covers purpose, usage, constraints, and behavioral notes. No output schema but not needed for feedback tool. Adequate for the context.

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

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

Schema coverage is 100% with descriptions for each parameter. The description adds no additional semantics beyond schema, so baseline 3 is appropriate.

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

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

The description clearly states it's for sending feedback, listing specific types: bug, feature/data_gap, praise. It distinguishes from sibling tools, none of which are about feedback.

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 details when to use: for bugs, missing features, praise. Provides instructions to describe issues in terms of tools/packs and not paste prompts. Also mentions rate limits and quota.

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, destructiveness. Description adds caching behavior, data source (CF analytics-engine), and privacy note (no PII). No contradiction.

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

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

Single paragraph front-loaded with main purpose, followed by bulleted uses, then technical details. No redundancy, every sentence adds value.

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

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

Given no output schema, description explains return values (top tools, packs, volume) and temporal behavior (caching). Adequate for a read-only, idempotent 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 already documents the enum window parameter fully. Description adds semantic guidance on choosing shorter vs longer windows (hot vs steady-state demand). Adds value beyond schema.

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

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

Clearly states the tool returns top tools, top packs, and total call volume over a window. Specific verb 'returns' and resource defined. Distinguishes from siblings as it's the only trending tool.

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

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

Lists three explicit use cases (discovering hot data sources, confirming canonical tools, aligning use case). No direct alternatives or when-not-to-use, but context is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds detail about return fields and that it uses Serper API, providing sufficient behavioral context beyond annotations.

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

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

The description is a single concise sentence front-loaded with the main purpose. No unnecessary words, every part earns its place.

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

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

Given no output schema, the description lists the return fields. With 100% schema coverage and clear purpose, the description is sufficient. Could mention result count limits or pagination, but not essential for basic use.

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

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

Schema description coverage is 100%, with each parameter having a clear description. The description briefly mentions 'query plus optional country code (gl) and location string', which aligns with the schema but adds no new semantic meaning beyond what the schema already provides.

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

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

The description clearly states it performs 'Google Maps local business search via Serper' and lists the returned fields (title, address, rating, etc.). This differentiates it from sibling tools like 'search' (general web search) and 'news'.

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

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

The description explains parameters (query, optional country code, location string) but does not explicitly guide when to use this tool over alternatives. However, the purpose is distinct enough to infer usage context.

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false. The description adds valuable behavioral context: the tool requires one of two parameters, performs specific checks (monotonicity, partition-sum, semantic anchor, fill check), and warns against trading when realizable edge ≤ 0. 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 well-structured with sections (event mode, topic mode, semantic anchor, partition filter, fill check) and front-loaded with the prerequisite. Every sentence adds value, though some 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 no output schema, the description covers the response structure (opportunities array, partition_check object, fill_check) and behavior. It lacks explicit error handling, but overall completeness is high for a tool of this 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 description coverage is 100%, and the description significantly enhances the schema: it explains the formats for event slugs and topic seeds, provides examples, and details how each parameter is used in the analysis. This goes well beyond the schema's basic descriptions.

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

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

The description clearly states the tool's purpose: finding arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes itself from sibling tools like polymarket_edges, polymarket_fill_risk, etc., by specifying its unique functionality.

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

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

The description explicitly tells when to use each parameter (event for single-event mode, topic for cross-event mode), warns that calling with no arguments fails, and provides an alternative tool (polymarket_fill_risk) for custom sizing. It also explains the benefits of cross-event mode over single-event mode.

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

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

The description extensively covers behavioral traits beyond annotations: it explains the three model families (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT), their detailed methodology, tradeable-edge filters, response structure including diagnostics and caching, and even caveats like Fed bet unreliability. This far exceeds the annotation baseline.

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 and front-loaded with purpose. It uses headings implicitly with uppercase words and bullet-point-like formatting. While it is verbose, every sentence contributes necessary detail for such a complex tool, making it efficient rather than wasteful.

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

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

Given the complexity (9 parameters, no output schema, multiple segments), the description is remarkably complete. It explains the response structure in detail (by_segment, diagnostics, Fed note), caching behavior, and even subtle points like the 24h-move warning. It leaves no major gaps for an agent to understand what the tool returns.

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 baseline is 3, but the tool description adds significant value by explaining parameter interactions and use cases (e.g., min_partition_leg_kelly clarifies that partition arbs always return kelly_fraction_half=0 at parent level, so this knob applies to per-leg Kelly instead). It also provides context for default values and when to adjust (e.g., slippage_pp suggests bumping for thin partitions).

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 ('Scan') and resource ('top Polymarket markets'), and explains the core function: returning opportunities where Pipeworx data disagrees with market price. It also distinguishes itself from siblings by focusing on Pipeworx data disagreement and being designed for 'what should I bet on today', which is unique among sibling tools like polymarket_arbitrage.

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

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

The description provides clear context for when to use the tool ('what should I bet on today', eliminating the need to page hundreds of markets) and details on filtering knobs. However, it does not explicitly state when not to use this tool or directly name alternative tools for different scenarios, leaving some room for ambiguity.

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

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive. The description adds significant behavioral details: LIMITS about TTL, snapshot start time, and that decay uses daily closes not 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?

Description is verbose but well-structured: starts with core question, then details response fields, finishes with limits. Every sentence adds value, though could be slightly more concise.

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

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

No output schema exists, so description thoroughly explains the three response arrays (tracked, expired, snapshot_dates) with field details. Parameters fully covered, annotations cover safety. Complete for the tool's complexity.

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

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

Schema coverage is 100% with descriptions. The description adds default values (14 days, '1wk') and explains that 'window' is the snapshot family. This provides meaningful 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 states the tool's purpose: edge persistence and decay telemetry, answering specific questions about edge age and shrinkage. It distinguishes from sibling tools like polymarket_edges by focusing on historical persistence and decay.

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

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

Provides context on when to use (e.g., 'a fresh wide edge and a 3-week-old wide edge are different trades'), but lacks explicit when-not-to-use or alternative tools. Mentions limitations like 60-day TTL and daily closes, guiding appropriate usage.

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

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

Annotations (readOnlyHint, idempotentHint, destructiveHint=false) indicate a safe, read-only operation. The description adds rich behavioral context: it walks the order-book ladder, returns specific fields (top_of_book, vwap_fill_price, slippage_pp, shares_filled, etc.), warns about forced directional risk from partial basket fills, and explains the implications of thin legs. No contradiction with annotations.

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

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

The description is well-structured with clear sections (REQUIRES, SINGLE-MARKET, BASKET, USE THIS) and front-loaded with the main purpose. While it is lengthy, every sentence adds value for a complex tool. Minor verbosity could be trimmed, but it remains efficient for the information density.

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 return fields, no output schema), the description thoroughly explains all return values and edge cases (thin legs, forced directional risk). It covers both single-market and basket modes in detail, providing enough context for correct use. The explicit warning about partial basket fills and the dominant loss mode makes 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?

The input schema covers all four parameters with descriptions, achieving 100% coverage. The description adds further meaning: it explains defaults (side default buy_yes for single-market, auto-detect for basket), the clamp range for size_usd (10–1,000,000), and the interpretation of size_usd in basket mode as 'settlement notional'. This goes beyond schema to clarify parameter usage in both 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 the tool performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes between single-market and basket modes. It explicitly contrasts with sibling tools like polymarket_arbitrage and polymarket_edges by prescribing when to use this tool before acting on their signals.

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

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

The description provides explicit when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains the rationale (theoretical overround not capturable on thin books, partial fills convert arb to directional risk) and details how to use each mode with required parameters.

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

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

Beyond annotations (readOnly, idempotent, non-destructive), the description discloses critical behavioral traits: compatibility checking, temporal alignment verification, and skipping of non-equivalent leg pairs. It explains the safety fields (compatibility_warning, temporal_alignment) and counters for skipped comparisons, providing transparency into edge cases and limitations.

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 verbose but well-structured with bold key terms and clear sections. It is front-loaded with the main purpose and provides essential detail in a logical order. While not extremely concise, every sentence adds value and the length is justified by the tool's complexity.

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

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

Given the tool's complexity (3 parameters, no output schema, cross-venue comparison with compatibility checks), the description covers all necessary aspects: operation mode, response structure, safety fields, edge cases (non-equivalent shapes, temporal misalignment), and limitations. It explains the spread calculation and warnings comprehensively, leaving no obvious gaps.

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

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

Schema coverage is 100% with descriptions for each parameter. The description adds contextual value by explaining that 'topic' is pre-mapped and 'kalshi_event_ticker'/'polymarket_event_slug' override the topic. However, the schema descriptions already sufficiently document the parameters, so the description provides only marginal additional 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 defines the tool as computing cross-venue spreads between Kalshi and Polymarket for the same resolving question. It distinguishes from siblings like 'polymarket_arbitrage' by focusing on two specific venues. The two modes (topic vs explicit) are explicitly stated, providing a specific verb+resource combination.

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' for 10 pre-mapped macros, 'explicit' for custom pairings. It warns that most pre-mapped topics currently return compatibility warnings, advising users not to assume tradeability. It also explains when spreads are meaningless (temporal misalignment, non-equivalent bet shapes), offering clear when-not-to-use criteria.

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

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

Annotations already declare readOnlyHint and idempotentHint. Description adds scope (identifier-based) and listing behavior when key omitted, providing useful 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?

Description is efficient with front-loaded core action. Every sentence adds value, though slightly verbose with pairing and scoping 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?

Complete for a simple one-param tool. Covers retrieval, listing, scoping, and pairing. No output schema needed as return value is implicit.

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

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

Schema covers parameter fully. Description clarifies that omitting key lists all saved keys, adding semantic meaning beyond schema definition.

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

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

The description clearly states the tool retrieves a saved value or lists all keys, using specific verbs and resources. It distinguishes from siblings by mentioning pairing with remember and forget.

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

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

Explicitly states when to use (look up context) and implies when not (save/delete). Provides concrete examples like user's target ticker, address, research notes.

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 a contradiction with annotations (readOnlyHint=true but mark_read modifies state), the description honestly discloses the side effect of mark_read. It also explains return fields and the availability of the feed via GET. The annotations are misleading, but the description adds transparency.

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

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

The description is concise at 4 sentences, with no redundant information. It is well-structured: purpose, return data, filter/mark_read instructions, and an alternative access method.

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

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

The description covers return fields, filtering options, mark_read effect, and an alternative endpoint. It does not detail error conditions or rate limits, but given the 5 optional parameters and no output schema, it provides sufficient context for 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 description coverage is 100%, so baseline is 3. The description adds value by providing an example for 'type' ('sec_8k') and clarifying mark_read behavior, but does not significantly extend beyond the schema's own parameter descriptions.

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

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

The description clearly states the tool pulls fired events from a subscription feed, specifying the verb 'Pull' and resource 'alerts'. It distinguishes from siblings like 'list_subscriptions' by focusing on events, not subscription management.

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 usage context: filtering by type and since, using mark_read, and mentions that polls work fine. It also notes an alternative GET endpoint for scripts/dashboards. However, it does not explicitly contrast with sibling tools like 'recent_changes' or specify when not to use it.

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

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

Beyond annotations (readOnlyHint, idempotentHint, destructiveHint), the description reveals that the tool fans out to multiple sources in parallel, has a fallback for news, and that USPTO may soft-fail due to API sunset. It also describes the return structure with changes grouped by source and citation URIs.

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

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

The description is a single coherent paragraph that starts with example queries (front-loading usage), then explains the fan-out, parameter details, return structure, and alternative tool. Every sentence adds meaningful information with no redundancy.

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

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

Despite no output schema, the description adequately describes the return ('changes[] grouped by source + total_changes count + pipeworx:// citation URIs'). It covers all aspects needed for an AI agent to select and invoke the tool, including fallbacks, soft-fails, and parameter formats.

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 valuable context: examples for 'since' (ISO date and relative shorthand like '7d', '30d', '3m', '1y'), explanation that 'value' accepts ticker or CIK, and the current limitation that 'type' only supports 'company'. This goes well beyond the schema.

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

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

The description explicitly states 'change feed for a company in the last N days/weeks/months in ONE parallel call' and lists the specific sources (SEC EDGAR, GDELT→GNews, USPTO). It also distinguishes from the sibling tool 'entity_profile' by directing users to use that for 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 provides explicit guidance: 'Use entity_profile instead when you want the static profile' and explains the fallback mechanism (GDELT→GNews when rate-limited or 5xx). It also gives concrete examples for the 'since' parameter, making it clear when and how to use the tool.

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

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

Description adds key behavioral details beyond annotations: key-value scoped by identifier, persistence for authenticated users vs 24-hour retention for anonymous sessions. 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?

Concise and well-structured. Front-loaded with purpose, then usage, then behavioral details. No wasted words.

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

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

For a simple 2-param tool with no output schema, the description covers purpose, when to use, scope, and lifecycle. Complete and self-contained.

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

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

Schema coverage is 100%, description does not add new parameter meaning beyond schema's examples. 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?

Clearly states the tool saves data for reuse later, with specific verb 'save' and resource 'data'. Distinguishes from siblings 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 says when to use: when discovering something worth carrying forward. Also explains pairing with recall and forget for retrieval and deletion.

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

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

Description discloses internal cascading behavior, specific return fields per type (company, drug), and auto-disambiguation. Adds significant value beyond annotations (readOnly, idempotent, etc.), detailing what the tool actually does and returns.

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

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

Well-structured with examples first, then usage guidance, then type details. Each sentence adds value, though slightly verbose in the type descriptions; still efficient overall.

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

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

Compensates for missing output schema by describing return fields in detail. Covers two entity types with specifics on input and output. Lacks error handling or ambiguous input guidance, but overall sufficient for effective use.

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

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

Schema covers both parameters with descriptions; the description enriches them with concrete examples for each type (ticker, CIK, name for company; brand/generic for drug) and explains the output context. Adds substantial meaning beyond the schema.

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

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

The description uses specific verbs ('resolve', 'look up') and resource ('name to ID'), provides clear examples of queries, and positions itself as the primary tool for name-to-identifier 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?

States 'use FIRST whenever you have a name but need an ID,' giving clear when-to-use guidance. Does not explicitly exclude use cases or mention alternatives, but the context is clear.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds internal process details (probes each entity with ai_visibility_check, ranks, returns scores) without contradicting annotations.

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

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

Four concise sentences: main action, internal process, use case, output format. Front-loaded with essential information, no redundant 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 no output schema, description explicitly lists return elements (score, confidence, signal density). Internal methodology explained. Could mention limitation on entity count or uniqueness, but overall 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?

Schema description coverage is 100% with detailed parameter descriptions. The tool description does not add new semantic information beyond schema, but contextualizes the overall purpose. Baseline 3 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?

Specific verb 'Compare' and resource 'AI visibility across multiple entities' clearly states the action. Distinguishes from sibling 'ai_visibility_check' by indicating side-by-side comparison and ranking. Output format described.

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

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

Explicit use case provided ('competitive AI-marketing audits') with concrete example question. Does not explicitly state when not to use or name alternatives, but sibling context implies single-entity alternative.

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

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

Beyond annotations (readOnly, idempotent, etc.), the description discloses important behaviors: partial failure handling, bundlephobia measurement delay (5-30s), and that sources_failed lists timeouts. 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 relatively long but well-structured: purpose first, then usage guidance, output summary, ecosystem scope, and failure behavior. Every sentence adds value, though it could be slightly more concise.

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

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

The description covers all key aspects: what the tool does, when to use, what it returns (list of fields), ecosystem limitations, failure behavior. Given no output schema, the return value description is essential and well provided.

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 minimal new info about parameters; the schema already explains package and version. It mentions default version behavior and scoped packages, but these are already in the schema description.

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

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

The description clearly states the tool's purpose as a composite check for evaluating npm packages, using specific verbs like 'fans out' and naming the services (deps.dev, bundlephobia). It distinguishes itself from siblings by specifying the scope (npm ecosystem) and the exact question it answers ('is X safe/popular/small').

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

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

Explicitly states when to use: 'Use whenever an agent asks...' and provides alternatives for other ecosystems (PyPI, Maven, etc.) to use other tools. This gives clear guidance on when-not-to-use and what alternatives exist.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints. The description adds value by specifying the exact output fields (title, link, snippet, position) and optional geo-targeting behavior, without contradicting annotations.

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

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

Two concise sentences cover purpose, return fields, and key parameters with no unnecessary verbiage. Every sentence adds value.

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

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

For a straightforward search tool with full schema and annotations, the description explains return types and optional parameters adequately. No gaps identified.

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

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

Schema coverage is 100%, so baseline is 3. The description adds moderate context: it clarifies 'result count (max 20)' and states that 'gl' and 'location' are for geo-targeting, but largely restates schema information.

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 performs 'Google web search via Serper' and lists specific return fields (organic results, answer box, knowledge graph). This distinguishes it from sibling tools like 'news' or 'places' which target different domains.

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

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

The description explains what the tool returns and what parameters it accepts, but does not explicitly state when to use it versus alternatives (e.g., 'news', 'places'). The agent must infer usage from context, lacking clear 'when to use' or 'when not to use' guidance.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description adds detailed behavior: embedding model (BGE-base-en), windowing (500-char overlapping), character cap (200K with truncation flag), and return format (passages with offsets and similarity scores). No contradictions with annotations.

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

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

The description is a single paragraph of 3-4 sentences, front-loaded with the core purpose. Every sentence adds unique information with no filler.

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

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

Despite no output schema, the description covers return format (passages with offsets and scores), technical limits, and use case pairing. It provides all necessary context 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?

With 100% schema coverage, baseline is 3. The description adds value by providing example queries for the 'query' parameter and reinforcing natural-language usage, which enhances an agent's understanding beyond the schema.

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

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

The description uses a specific verb ('search') and resource ('a fetched record'), clearly defining the tool's action. It distinguishes itself from siblings by mentioning it works inside a previously fetched record and pairs with ask_pipeworx_grounded.

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 the record is too big to cram into the prompt') and provides an alternative/partner tool ('Pairs with ask_pipeworx_grounded'). This gives clear guidance on 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 indicate idempotentHint=true and readOnlyHint=false, but the description adds important context: subscription creation behavior, requirement for Pipeworx OAuth, delivery channel limits (10 SMS/day, auto-disable after 10 webhook failures), and that webhook secret is returned once. However, idempotency implications are not fully explained (e.g., whether duplicate subscriptions return the same ID or create new ones).

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 purpose, then requirements, types, and delivery channels. It is thorough but somewhat lengthy; however, every sentence serves a purpose, justifying 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?

The description covers requirements, all subscription types with examples, delivery channel options with limits, and notes that webhook secret is returned once. However, without an output schema, it only briefly mentions 'Returns the new subscription id' and could be more explicit about the full response structure.

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

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

Schema coverage is 100%, and the description adds significant value beyond schema definitions: it provides concrete examples for each type (sec_8k with items, polymarket_edge with topics, fred_series with series_id), explains parameters like min_spread_bps, and details delivery sub-parameters for webhook, including HMAC signing and auto-disable behavior.

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: 'Create a proactive monitoring subscription to a live-data event stream.' It distinguishes itself from sibling tools like 'unsubscribe' and 'list_subscriptions' by focusing on creation of subscriptions.

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

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

The description implies usage for monitoring events but does not explicitly contrast with alternatives like 'recent_alerts' for pulling existing alerts or specify when not to use this tool. It provides requirements (Pipeworx OAuth) but lacks exclusion guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds that the tool returns a 'live catalog of thousands of tools' and includes exact tool+argument shapes, which is useful behavioral context beyond the annotations. No contradiction.

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

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

The description is detailed but every sentence adds value. It uses a clear structure with synonyms in the first line, then explanation of output, then usage instructions. Slightly front-loaded with alternative phrasings, but not wasteful. Could be slightly tighter, but overall 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 tool with one optional parameter and no output schema, the description covers everything: purpose, invocation modes, content of return value, and when to use it. It fully equips an agent to understand 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% (one optional string parameter with description). The description reiterates the topic values and adds that omitting gives a cross-category spread. This adds a small semantic nuance, but the schema already does the heavy lifting, so score 3 is appropriate.

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

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

The description clearly states the tool is an onboarding entry point that returns category-bucketed example questions with exact tool and argument shapes. It uses specific verbs like 'returns' and 'learn how to call', and distinguishes it from sibling tools like 'ask_pipeworx' and 'discover_tools' by positioning it as the first-use tool.

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

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

The description explicitly says to use this tool 'FIRST when you do not yet know what Pipeworx can do' and explains the two invocation modes: no arguments for full spread or with a topic to focus. It does not explicitly list when not to use it, but the context is clear enough.

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

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

Annotations indicate mutation (readOnlyHint=false) and non-destructive (destructiveHint=false). Description adds key details: row is deactivated not deleted, ownership enforced, and historical events remain available. 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 concise sentences: first front-loads core action, second adds essential nuance. No redundancy.

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

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

Adequate for a simple, single-parameter mutation tool. References sibling tool 'recent_alerts' for historical data context. Could explicitly mention its role as inverse of subscribe, but overall 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 covers 100% of parameters with description linking id to subscribe. Description reinforces 'by id' and ownership context, adding value beyond schema.

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

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

Clearly states 'Cancel a subscription by id' with specific verb and resource. Explains ownership enforcement and deactivation behavior, distinguishing it from deletion and sibling tools like subscribe.

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

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

Provides clear context on ownership ('you can only cancel your own subscriptions') and mentions historical data persistence via recent_alerts. Lacks explicit 'when not to use' but sufficient for typical use.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds behavioral context: it returns a verdict with specific outcomes, extracts structured form, provides actual value with citation, and explains the efficiency gain. No contradictions.

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

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

The description is information-dense but front-loaded with example queries. Every sentence adds value, though it could be slightly shorter. Still well-structured for an AI agent.

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

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

Given the single parameter, full schema coverage, and no output schema, the description adequately explains the return format (verdict types, structured form, citation, delta). It is complete for the tool's complexity and purpose.

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

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

Only one parameter 'claim' with 100% schema description coverage. The tool description adds meaning by providing example claims and specifying the financial domain, going beyond the schema's 'natural-language factual claim' description.

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

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

The description clearly states the tool's purpose: verifying natural-language claims against authoritative sources. It provides example query patterns ('Is it true that…', 'fact check', etc.) and specifies the domain (company-financial claims via SEC EDGAR + XBRL). It also distinguishes itself from siblings by noting it replaces multiple sequential calls.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' It implies the domain limitation (company-financial) but does not explicitly state when not to use or mention alternative tools for other claim types. Still clear and helpful.

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