Opencellid

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

Annotations (readOnlyHint=true, idempotentHint=true) are consistent. Description adds key behavioral details: default model is free, Anthropic requires BYO key, and it describes the return structure. No contradictions.

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

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

The description is concise (4 sentences), front-loaded with the core purpose, followed by default details and use cases. No wasted words.

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

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

Despite no output schema, the description adequately describes the return format (per-model objects with score, confidence, signals, raw_response + combined view). Parameter count 4 with 100% schema coverage means no gaps.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond schema: explains default model behavior, how _apiKey works only when anthropic is in models, and context disambiguation purpose. This elevates the score.

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

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

The description clearly states the tool probes LLMs for knowledge about an entity and scores visibility (0-100) per model. It specifies the default model and distinguishes itself from sibling tools like compare_entities or scan_competitor_ai_presence.

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 mentions use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. It implies when not to use (e.g., for detailed entity profile, not here), though doesn't explicitly name exclusions.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds value by explaining the routing to 3,745 tools, argument filling, and stable citation URIs. No contradictions.

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

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

The description is front-loaded with the important usage preference, lists domains concisely, explains routing, and ends with examples. Every sentence serves a purpose; it is not bloated.

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 (6 parameters, no output schema), the description sufficiently covers what the tool does, when to use it, and what to expect (structured answer with citations). It is complete for effective 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 description coverage is 100%, so the schema already documents all parameters. The description does not add additional meaning beyond the schema, but it provides useful examples of questions. 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 that the tool routes questions to a vast set of verified sources and returns structured answers with citations. It provides a specific verb+resource (route question, return structured answer) and distinguishes from web search by preferring its use for authoritative structured data.

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

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

The description explicitly says 'PREFER OVER WEB SEARCH' for a wide range of factual queries and lists trigger phrases like 'what is', 'look up', 'find', etc. While it does not exclude sibling tools like ask_pipeworx_grounded, the clear preference for this tool over web search provides strong usage 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?

Discloses extra LLM call cost, refusal reasons, and that it only uses tool result content. Annotations already indicate readOnlyHint true, but the description adds significant behavioral context beyond that.

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

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

The description is relatively long but well-structured, with the main purpose front-loaded. Every sentence adds value, though slightly more conciseness could be achieved.

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

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

Given no output schema, the description clearly explains the return structure (answer, evidence, refusal etc.) and covers the complexity of routing among many tools and data sources.

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

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

Schema coverage is 100% with each parameter described. The description does not add further semantic meaning beyond what the schema provides, 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 states the tool is a 'Hallucination-resistant answer mode for high-stakes reads' and clarifies it extracts answers using only tool results, distinguishing it from the sibling 'ask_pipeworx' for casual lookups.

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

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

Explicitly states when to use ('when an answer will be quoted, cited, or acted on') and when to prefer the alternate 'ask_pipeworx' for casual lookups, providing clear decision 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?

The description goes far beyond annotations by detailing behavioral traits: low-confidence resolutions short-circuit with status:'low_confidence_match', closed/dead markets return 'market_closed_or_inactive', wide-spread markets carry tradeability notes, and RESOLUTION-RULE RISK explains cancellation rules. It also describes response shapes and resolver contract, providing deep 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 quite long but well-organized into capitalized sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.). Every sentence adds value, though some redundancy exists (e.g., repeated mention of low-confidence paths). It is front-loaded with the core purpose and usage.

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

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

Given the tool's complexity (3 params, no output schema), the description is exceptionally complete. It covers classification, fan-out examples, response shapes, resolver contract, parent event extractor, news fallback logic, safety checks, wide-spread handling, and resolution rule risk. No gaps evident.

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

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

The description adds significant meaning beyond the input schema: it explains how market accepts slug, URL, or question text; depth controls quick vs thorough fan-out; include_raw controls summary vs full payloads with size implications. Since schema coverage is 100%, the description elevates context with concrete examples and usage notes.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It lists typical use cases like 'should I bet on X' and distinguishes from sibling tools by offering a comprehensive single-call research endpoint vs specialized edge/arbitrage tools.

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

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

The description provides explicit usage scenarios (e.g., 'Use for "should I bet on X"') and explains what the tool does (resolves market, fans out, returns evidence). However, it does not explicitly contrast with sibling tools like polymarket_edges or polymarket_arbitrage, though the extensive description implies its all-in-one nature.

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 OpenCellID caps results per call, which is a behavioral trait beyond the structured 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, followed by format and a tip. 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?

Given the presence of an output schema and full annotation coverage, the description is concise but omits example usage and assumes coordinate order understanding. Still adequate for the tool's simplicity.

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

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

Schema coverage is 100% with descriptions for all parameters. The description restates the bbox format already in schema, adding no new semantics beyond the schema.

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

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

Description clearly states 'List cell towers inside a bounding box', specifying the verb (List) and resource (cell towers) with a clear scope (inside a bounding box). This distinguishes it from sibling tool 'get_cell' which retrieves a single cell.

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

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

The description implicitly advises when to use by warning about server cap and suggesting narrowing the bbox for detail, but does not explicitly state when not to use or provide alternatives among siblings.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds valuable behavioral context: data sources (SEC EDGAR for companies, FAERS for drugs), handling of off-calendar fiscal years, result sorting by primary metric, and citation URI returns. No contradiction with annotations.

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

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

The description is a single paragraph that is front-loaded with natural language triggers and efficiently packs all key details without redundancy. Every sentence adds value, covering purpose, usage preference, data sources, 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 only two parameters (type and values) and no output schema, the description fully explains the behavior, data sources, sorting, and return of citation URIs. It is complete for an agent to invoke correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond the schema by specifying that for company type, it pulls latest 10-K data, and for drug type, it pulls adverse-event counts, FDA approvals, and trial counts. It also gives examples for values (tickers/CIKs, names).

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

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

The description states it provides a side-by-side comparison of 2–5 companies or drugs in one call, with explicit examples like 'compare X and Y'. It distinguishes from siblings like entity_profile by emphasizing parallel comparison over sequential lookups.

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

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

The description advises to always prefer this tool over sequential single-pack lookups when comparing entities, and gives clear usage examples. However, it does not explicitly state when not to use it or mention alternatives for single entity lookups.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true. The description adds behavioral details: parallel decomposition, never invents (explicit gaps[]), returns citations with verbatim evidence and stable pipeworx:// links. No contradictions. Rich 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 structured well, front-loading the core capability and then detailing features, requirements, and latency. It is longer but each sentence adds value; could be slightly tighter but overall efficient.

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

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

Despite no output schema, the description fully explains return format: findings packet with verbatim evidence, confidence, source, fetched_at, stable citation, and gaps[]. Also covers prerequisites, account requirements, expected latency (15-60s), and comparison to sibling. Complete for a complex research 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%, both parameters have descriptions. The description adds extra context about depth meanings (quick=3, standard=5, thorough=8) and that question can be broad/multi-part. However, the schema already documents the enum and text. Adequate but not exceptional.

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

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

The description clearly states the tool performs 'grounded multi-source research in one call', decomposing questions into sub-questions and routing to many sources. It distinguishes from sibling ask_pipeworx by explaining the difference in scope and number of LLM 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?

Explicitly advises using for 'broad or multi-part questions' and provides a sibling alternative: 'use ask_pipeworx for single lookups'. Also mentions prerequisites like needing a Pipeworx account and that 'depth:"thorough" requires a paid plan.'

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is clear. The description adds valuable behavioral context: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' This informs the agent about return format and immediacy.

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

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

The description is somewhat verbose but efficiently conveys purpose, usage, return format, and examples. It front-loads the key message ('Find tools...') and each sentence earns its place. Minor improvement could be trimming the list of domains, but it's not excessive.

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

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

Given the parameter count (6, mostly aliases), one required parameter, and no output schema, the description sufficiently explains what the tool does and returns. It covers the return structure and usage context. Some details like pagination are omitted but are not critical for this 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% with all parameters described. The description supplements by clarifying that the query parameter accepts multiple aliases (task, q, search, description) and providing example natural language queries. This adds meaning beyond the schema definitions.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists specific domains and explains that it returns top-N relevant tools with names, descriptions, and full input schemas. This distinguishes it from sibling tools (e.g., search_within, deep_research) which perform actual data tasks rather than tool discovery.

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

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

The description explicitly says 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It also provides context on when to use it (browse, search, look up, discover tools). While it does not explicitly state when not to use it or offer alternatives, the guidance is clear and actionable.

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

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

Annotations indicate readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds rich behavioral context: fans out across multiple data sources (SEC, XBRL, USPTO, news, GLEIF), details return fields, and notes that patents soft-fails until May 2025. 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 packed with examples, purpose, and detailed return info in a compact paragraph. Every sentence adds value; no fluff. Efficiently structured with examples front-loaded.

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

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

Despite no output schema, the description thoroughly lists all return fields (cik, company_name, recent_filings, fundamentals, patents, news, LEI) and describes the data sources and ordering. Covers all necessary context for the complexity of this multi-source 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 covers 100% of parameters. Description adds extra meaning: for type, clarifies only 'company' is supported; for value, explains ticker or zero-padded CIK and explicitly says names not supported, directing to resolve_entity. This significantly augments schema descriptions.

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

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

Description immediately states 'full cross-source profile of a US public company in ONE parallel call' and provides numerous example queries like 'Tell me about X' and 'company profile for Microsoft'. It clearly identifies the resource (US public company) and the action (profile), distinguishing from siblings like resolve_entity.

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

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

Explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' and instructs to use resolve_entity if only a name is known. This provides clear when-to-use and when-not-to-use guidance.

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

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

Annotations already indicate destructive and idempotent behavior. Description adds no additional behavioral context beyond 'delete'. Acceptable but not extra 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 fluff. Front-loaded with purpose, then usage context. Every sentence earns its place.

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

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

Simple tool with one parameter and good annotations. Covers when to use and related tools. Lacks error handling details but appropriate for 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 a clear description for 'key'. Description only reiterates 'by key', offering no semantics 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?

Clearly states 'Delete a previously stored memory by key' with specific verb and resource. Mentions pairing with remember and recall but doesn't explicitly differentiate, though the purpose is 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?

Provides explicit use cases: 'when context is stale, the task is done, or you want to clear sensitive data'. Suggests pairing with siblings but lacks 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds that it fetches page, extracts content, and emits markdown. 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?

Three sentences plus bullet list, front-loaded with purpose. Every sentence provides distinct 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?

Covers input (url), process (fetch, extract), output (single text blob), and use cases. No missing details given simple tool with two params.

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 params with descriptions. Description repeats url and max_links info without adding new semantics. Baseline 3 for 100% coverage.

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

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

Clearly states verb 'generate' and resource 'llms.txt file' with specific target audience (AI crawlers). Distinguishes from sibling tools like ai_visibility_check by focusing on file 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 three use cases (client indexing, own project drafting, competitor auditing). Does not mention 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, idempotentHint, and openWorldHint, but the description adds value by specifying return fields (lat/lon, range, samples, radio type). No contradictions; description complements annotations well.

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: one sentence with bullet-like breakdown of parameters. No fluff, well-structured, and front-loaded with the core purpose.

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

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

Given the presence of both input and output schemas, the description is complete enough. It mentions return fields, and the output schema provides further detail. No missing crucial context like error conditions or limits.

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

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

Schema covers all parameters with descriptions (100% coverage). The description adds contextual explanations (e.g., MCC = Mobile Country Code) and examples, providing additional clarity 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 the tool's purpose: 'Geolocate a cell tower by mobile network identifiers.' It enumerates the required parameters and their meanings, and mentions return values. It distinguishes itself from the sibling 'cells_in_area' which likely returns multiple cells in an area.

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 parameter definitions but lacks explicit guidance on when to use this tool versus alternatives like 'cells_in_area'. It implies usage by listing what the tool does, but no when/when-not or context for selection.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint as safe. The description adds that it returns active subscriptions by default and the include_inactive parameter changes this. It also lists all return fields, giving clear behavioral insight beyond annotations.

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

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

The description is two sentences: first presents the core functionality and return data, second gives actionable usage guidance. No superfluous words, highly efficient.

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

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

For a simple list tool with one optional parameter and no output schema, the description covers purpose, return fields, default behavior, and usage scenarios. It does not mention ordering or limits, but these are not critical for this tool's completeness.

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

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

Schema coverage is 100% with a description for include_inactive. The tool description implicitly explains the default (active only) but does not add new meaning beyond the schema's boolean and description. Baseline 3 is appropriate as the schema already carries the burden.

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

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

The description clearly states the tool lists the caller's active subscriptions and enumerates the returned fields (id, type, params, etc.). It distinguishes from siblings like subscribe/unsubscribe by focusing on listing existing subscriptions, providing a specific verb-noun resource.

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

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

The description explicitly advises when to use the tool: 'review what you're monitoring before adding more' and 'find an id to cancel'. It does not specify when not to use it, but the context of sibling tools (e.g., subscribe, unsubscribe) implies alternatives for 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?

Discloses rate limiting (5 per identifier per day), cost (free, no quota impact), and processing (team reads digests daily, affects roadmap). Annotations are all false, so no contradiction; 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?

Six sentences, front-loaded with purpose, then usage, then constraints. Every sentence adds value without redundancy. Structure is logical and easy to parse.

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 all necessary aspects: purpose, input types, usage scenarios, behavioral constraints, and what to avoid. Completely sufficient for an agent to use this tool correctly.

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

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

Schema covers 100% of parameters with descriptions. The description adds extra guidance for the 'type' enum and advises being specific in 'message', but most parameter meaning is already in the schema. Slight added value.

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 for sending feedback to the Pipeworx team, listing specific categories (bug, feature, data_gap, praise). It distinguishes itself from sibling tools by emphasizing it's for messages to the team, not queries or data retrieval.

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 a tool returns wrong data (bug), when a desired tool is missing (feature/data_gap), or for praise. Also gives a clear exclusion: 'don't paste the end-user's prompt,' preventing misuse.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds valuable context: self-aggregating signal, no PII, cache timing (5min-1h). No contradictions.

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

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

The description is concise with three sentences, each adding value. Front-loaded with the core purpose, followed by use cases and additional details. No wasted words.

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

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

Given the tool has no output schema, the description sufficiently explains what is returned (top tools, top packs, total call volume). It is complete for a simple read-only tool with few parameters.

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

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

Only one parameter (window) with full schema coverage (100%). The description adds semantic value by explaining that shorter windows surface hot trends and longer windows show steady-state demand, beyond the schema's enum 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 returns top tools, top packs, and total call volume over a recent window, using specific verbs and resource description. It distinguishes itself from sibling tools by focusing on trending data.

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

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

The description lists three explicit use cases (discovering hot data sources, confirming canonical tools, aligning use cases) which helps an agent decide when to use it. It lacks explicit 'when not to use' guidance, but the use cases are 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?

Discloses internal logic: walks child markets, checks ordering, computes partition check with similarity threshold, partition filter, and fill check against live CLOB depth. This adds significant value beyond annotations which only indicate read-only/idempotent.

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

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

Well-structured with sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). Front-loaded with requirement. Dense but efficient; every sentence adds value without unnecessary verbosity.

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?

Explains response structure (opportunities[], partition_check) and fill check behavior despite no output schema. Covers edge cases (placeholders, similarity threshold) and references sibling tool for completeness.

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

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

Schema already provides full descriptions for both parameters. Description adds examples, mode recommendations, and clarifies that event is a slug while topic is a seed question, providing extra context beyond the schema.

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

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

Description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes from sibling tools like polymarket_edges and polymarket_fill_risk by focusing on arbitrage detection.

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

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

Explicitly states required arguments (one of event or topic) and when to use each mode. Recommends event for specific markets and topic for cross-event scanning. Also mentions alternative tool for custom sizing (polymarket_fill_risk).

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 readOnly, openWorld, idempotent, non-destructive. The description adds extensive behavioral detail: caching (1h at KV level), five model families, response structure (by_segment), edge calculation methods, tradeable-edge knobs, and diagnostics. 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 very long and dense with technical details, making it less concise. While the first sentence front-loads purpose, the subsequent details could be streamlined for quicker agent parsing. Some verbosity is justified given complexity, but conciseness is sacrificed.

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

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

Given the tool's complexity (9 parameters, no output schema), the description is highly complete. It covers all parameters, response structure (by_segment with diagnostics), caching, edge calculations, and even explains why Fed bets are excluded. Without an output schema, it provides sufficient return-value 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 description coverage is 100% (baseline 3). The description adds meaning beyond schema by explaining the context of each parameter (e.g., 'tradeable-edge filters'), providing defaults, and offering usage tips (e.g., 'Bump for very thin partitions; drop to 0 if you have a smarter fill model').

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

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

The description clearly states the tool scans top Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. It specifies the action ('scan', 'return') and the resource (Polymarket markets), and distinguishes from sibling tool 'polymarket_arbitrage' by focusing on Pipeworx disagreement.

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

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

The description provides clear context for use ('Built for 'what should I bet on today''), explains that agents discover opportunities without paging hundreds of markets, and details categories and knobs. However, it does not explicitly state when not to use it or provide direct alternatives to sibling 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?

The description adds significant behavioral context beyond the annotations: it explains reliance on daily snapshots, 60-day TTL, snapshot gaps on cache-miss, and that decay is computed from daily closes (not intraday). This complements the readOnlyHint and idempotentHint 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 thorough but somewhat lengthy. It is front-loaded with purpose and explains args, response structure, and limitations in a logical order. However, it could be more concise without losing key information.

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

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

With no output schema, the description adequately details the response fields (tracked, expired, snapshot_dates) and their contents. It also covers key limitations like history depth and computation methods. Slight lack of detail on trend enumeration type, but overall 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?

The input schema has 100% description coverage; the description mainly repeats the parameter info (defaults, ranges) but adds the concept of 'snapshot family' for the window parameter, which provides 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 provides 'edge persistence and decay telemetry' and answers a specific question about edge longevity. It distinguishes itself from sibling tools like polymarket_edges by focusing on historical time-series analysis rather than current snapshots.

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

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

The description implies when to use the tool (e.g., comparing fresh vs. old edges) but does not explicitly state when not to use it or mention alternatives like polymarket_edges or polymarket_arbitrage. Usage context is provided but not exclusions.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, consistent with the check. The description adds rich behavioral context: walks the ladder, returns top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict for single-market; theoretical_sum vs realizable_sum, capture_ratio, profit_usd, per-leg fill detail, thin_legs, max_clean_notional_usd, forced_directional_risk for basket. It warns about partial fills and directional risk, going well 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 front-loaded with purpose and uses bold for emphasis. It is somewhat lengthy but well-organized into sections for single-market and basket. Some redundancy (e.g., explaining verdict types) could be trimmed, but overall it earns its length given 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 has no output schema, the description fully explains return values for both modes, including edge cases (thin_legs, forced_directional_risk). It also addresses prerequisites (using before arb/edge signals) and failure modes (partial baskets, unhedged directional risk). This is complete for a complex tool.

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

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

Schema coverage is 100%, baseline 3, but the description adds significant value: it explains the two modes (event vs market), clarifies side defaults (auto for basket), and describes size_usd meaning per mode (spend vs proceeds vs settlement notional). This provides context not in the schema.

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

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

The description clearly states it is a 'realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes two modes (single-market and basket) and explicitly ties usage to sibling tools like polymarket_arbitrage and polymarket_edges, making it highly specific and differentiated.

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

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

The description explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains why: theoretical overround on thin books is not capturable and partial basket fills convert an arb into an unhedged directional position. This is excellent when-to-use and 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?

Annotations already provide safety hints. Description adds rich behavioral context: compatibility warnings, temporal alignment, skipped counters, and response structure. No contradictions.

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

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

Well-structured with front-loaded purpose, modes, response, and safety. Slightly long but every sentence adds value. Could be more concise on skipped counters.

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?

Comprehensive for a complex multi-venue tool with no output schema. Covers modes, response fields, compatibility conditions, temporal alignment, and limitations.

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

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

Schema has 100% coverage with parameter descriptions. Description adds context on mode switching and override behavior, but schema already documents parameters well.

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

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

The description clearly states the tool computes the price spread between Kalshi and Polymarket for equivalent outcomes. It distinguishes from siblings by focusing on cross-venue spreads and details two modes of operation.

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

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

Explicit guidance on two modes (topic shortcuts and explicit tickers) and warns that pre-mapped topics often yield warnings rather than tradeable spreads. Missing explicit references to alternatives when spread is not sought.

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 and idempotent. Description adds scoping (anonymous IP, BYO key hash, account ID) and behavior when key is omitted. 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, each earning its place: core function, use case, scoping, pairing. Front-loaded with main action.

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 1-param read tool, description covers purpose, usage, scoping, and pairing. No output schema, but return format is implied. Adequate for agent 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 coverage is 100% with parameter description. Description repeats the same info without adding new parameter-level meaning. Baseline 3 applies.

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

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

Description clearly states retrieving a saved value or listing keys. Distinguishes from siblings 'remember' and 'forget' by explicitly naming them.

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

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

Provides explicit when-to-use context: look up stored context without re-deriving. Mentions pairing with remember/forget and scoping to identifier.

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 behavioral details like mark_read functionality, the returned fields (source, citation_uri, raw payload), and filtering options, which goes beyond the annotations without contradiction.

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

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

The description is concise with three well-structured sentences. The first sentence captures the core purpose, and subsequent sentences add value without redundancy.

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

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

Despite no output schema, the description explains what each returned event carries and provides guidance on polling and an alternative API. Filtering parameters are covered, and the mark_read feature is explained. This is complete for a read-only polling tool.

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

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

Schema coverage is 100% with descriptions for each parameter. The description adds further context by mentioning 'ISO timestamp' for since and explaining the mark_read behavior in more depth, enhancing the schema's utility.

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 the subscription feed and returns recent alerts with specific fields like source and raw payload. It distinguishes from sibling tools like list_subscriptions by focusing on alert events rather than 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 by mentioning polling works fine and provides an alternative REST endpoint. It implicitly suggests when to use this tool for querying alerts, but does not explicitly state when not to use it, which is a minor gap.

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 annotations already stating readOnlyHint=true, idempotentHint=true, etc., the description adds significant behavioral context: it fans out to multiple sources (SEC EDGAR, GDELT→GNews fallback, USPTO), discloses the PatentsView API sunset issue, and explains the use of relative date shorthand. This goes well beyond what annotations provide.

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

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

The description is a dense single paragraph that packs a lot of information efficiently. It is front-loaded with example queries and covers all key aspects. However, it could benefit from bullet points or clearer structuring for even faster parsing, but it remains concise and well-organized.

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

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

The tool has no output schema, so the description rightly explains the return format: structured changes[] grouped by source, total_changes count, and pipeworx:// citation URIs. It also covers fallback behavior, limitations (USPTO soft-failure), and parameter details. The description is fully complete despite the 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?

All three parameters are fully described in the schema (100% coverage). The description adds extra meaning: 'since' accepts both ISO dates and relative shorthand with examples, 'value' accepts ticker or CIK with examples, and 'type' is limited to 'company'. The description enhances understanding beyond the schema.

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

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

The description explicitly states the tool provides a change feed for a company (SEC filings, news, patents) in a time window, and distinguishes itself from the sibling 'entity_profile' which provides static profiles. The verb 'get changes' is implied by the examples, and the resource is clearly defined.

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 query examples ('What's new with X', etc.) and directs users to use 'entity_profile' instead for static profiles. It also explains the fallback behavior between GDELT and GNews, giving clear context on when each is used.

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

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

Description adds context beyond annotations: scoping by identifier, persistence duration for anonymous sessions (24 hours). No contradictions with annotations (readOnlyHint false, idempotentHint true, destructiveHint false).

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 primary purpose. Each sentence adds unique value (purpose, usage timing, scoping/retention, pairing). 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 memory tool with 2 params and no output schema, description covers purpose, usage, behavioral details, and integration with sibling tools. 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 descriptions for both parameters. Description adds example key patterns and value types, but baseline is 3; no significant additional semantic value beyond schema.

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

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

The description states 'Save data the agent will need to reuse later' with specific verb and resource, and distinguishes from sibling tools 'recall' and 'forget' by mentioning them.

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

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

Explicitly tells when to use ('when you discover something worth carrying forward') with examples, mentions pairing with recall/forget, and distinguishes behavior for authenticated vs anonymous sessions.

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

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

Annotations already indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds behavioral context such as cascading through multiple endpoints, auto-disambiguation for companies, and specific return fields with citation URIs. It does not contradict annotations.

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

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

The description is well-structured and front-loaded with examples and a summary. It contains useful detail without being overly verbose, though slightly longer than necessary. Every sentence earns its place.

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

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

For a tool with no output schema, the description sufficiently explains return values (ticker, CIK, RxCUI, URIs). It covers two entity types and mentions internal cascading. Minor omissions like error handling on ambiguous inputs prevent a perfect score, but it is largely 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 basic descriptions. The description adds substantial value by explaining accepted input formats (ticker, CIK, name for company; brand/generic for drug) and the corresponding output for each type, far exceeding 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 that the tool resolves user-spoken names to canonical identifiers (ticker, CIK, RxCUI). It provides specific examples and distinguishes itself as a first-step tool for obtaining IDs required by other tools.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID,' providing a clear usage directive. It also details supported entity types and what each returns, leaving no ambiguity about when to invoke this tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds beyond this: it explains that the tool probes each entity with ai_visibility_check, ranks results, and returns score, confidence, and signal density. It also describes the narrative role of the first entity.

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

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

The description is five sentences with no redundancy. It front-loads the core purpose and efficiently covers process, example, and output format. 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 4 parameters, no output schema, and comprehensive annotations, the description fully explains the tool's functionality and usage. It clarifies the relationship with sibling ai_visibility_check and provides enough 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 key semantics: the significance of the first entity in the 'entities' array, the default model ('workers-ai'), and the dependency between models and _apiKey. This enriches understanding beyond the schema.

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

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

The description uses specific verbs ('Compare', 'probes', 'ranks', 'surfaces') and clearly identifies the resource: AI visibility across entities. It distinguishes from sibling ai_visibility_check by stating it probes multiple entities and performs ranking.

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

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

The description provides a clear use case ('competitive AI-marketing audits') and indicates that the first entity is treated as subject. It does not explicitly contrast with alternatives like ai_visibility_check, but the usage context is well implied.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds important behavioral details: fans out across two services, partial failures degrade gracefully, and bundlephobia's first measurement can take 5-30s. 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 comprehensive but slightly verbose. It is well-structured, front-loading the main purpose and usage, then detailing return values, scope, and behavior. Each sentence adds value.

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

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

Despite no output schema, the description fully explains the return value structure (summary block with fields, per-advisory detail, links, alternative versions). It also covers error handling (partial failures, sources_failed). Complete for a composite tool.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds minimal extra info beyond the schema (e.g., example of scoped packages and version format), but essentially repeats what's already in the schema.

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

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

The description clearly states it's a composite check for npm packages, answering questions like 'is X safe/popular/small' or 'what does adding lodash cost me'. It distinguishes from siblings because no other tool in the list provides this specific composite analysis.

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

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

Explicitly states when to use: when an agent asks about safety, popularity, or size of an npm package. Also specifies scope (NPM ecosystem only in v1) and directs other ecosystems to deps.dev:version directly.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, etc. The description adds critical behavioral details: returns character offsets and similarity scores, uses BGE-base-en embeddings with cosine over 500-char windows, caps input at 200K chars with truncation flag, and notes every passage carries an offset for verification. This goes well 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 short (4 sentences) but packs substantial detail. The first sentence clearly states the core function. Subsequent sentences add usage context, pairing suggestion, and technical specifics. Slightly dense but 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, the description thoroughly explains return values (passages, offsets, scores), input constraints (200K chars, truncation), and underlying model behavior. It also addresses the tool's role in a broader workflow with ask_pipeworx_grounded, making it complete for an agent's understanding.

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 minor value: provides natural-language query examples and states the default limit (5) and range (1-20). However, it does not significantly expand on the schema descriptions already present.

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 'Semantic search INSIDE a fetched record' with concrete examples (SEC 10-K body, article). It uses strong verbs and clearly distinguishes the tool's purpose from siblings like ask_pipeworx_grounded, which is mentioned as a complementary 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 advises when to use: 'when the record is too big to cram into the prompt — search_within saves context'. It also suggests pairing with ask_pipeworx_grounded for grounding. However, it does not explicitly state when not to use or list alternative tools beyond the pairing.

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

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

Discloses many behavioral traits (auth, caps, auto-disable, phone verification) beyond annotations, but contradicts the idempotentHint annotation by stating 'Returns the new subscription id' without clarifying idempotency. IdempotentHint=true suggests safe retries, but description implies creation of a new resource each time, which is inconsistent.

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 front-loaded purpose, prerequisites, types, and delivery details. Dense but informative; a minor trim could improve conciseness without losing essential context.

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

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

Covers the tool's complexity: multiple subscription types, parameter combinations, delivery channels with constraints, auth requirements, and return value. No output schema exists, but return of subscription ID is stated. Adequate for a complex creation tool.

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

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

Schema covers all 3 parameters, but description adds substantial value: examples for each type, detailed constraints (phone verification, 10/day SMS cap, webhook auto-disable, HMAC signing). This greatly aids correct parameter construction 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 states 'Create a proactive monitoring subscription to a live-data event stream' with a specific verb and resource. It differentiates from siblings by implying creation vs. listing (list_subscriptions) or removal (unsubscribe), and includes return of a subscription ID.

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

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

Provides clear context: requires Pipeworx OAuth account, lists supported types and delivery channels with constraints. However, does not explicitly contrast with alternatives (e.g., 'list_subscriptions' for existing subscriptions) or state when not to use, though it's generally inferable.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description adds context about returning example questions with tool+argument shapes. No contradictions, but the description does not go deep into behavioral traits beyond what annotations cover.

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

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

The description is slightly long but front-loaded with the key purpose. All sentences contribute value; could be a bit more concise but still effective.

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

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

The description fully covers the tool's purpose, usage, and return format (category-bucketed example questions with argument shapes). No output schema needed, so completeness is high.

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

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

Schema coverage is 100% with description of the 'topic' parameter. The description adds examples of allowed values and usage context (e.g., 'finance', 'pharma'), providing extra clarity 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 is an onboarding entry point that returns example questions by category. It uses specific verbs and resource (onboarding, suggest questions) and distinguishes from sibling tools like ask_pipeworx, entity_profile, etc.

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 this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' Also mentions alternatives and 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 indicate modify operation (readOnlyHint false), non-destructive (destructiveHint false), idempotent (idempotentHint true), and open world. The description adds valuable context: ownership enforcement, deactivation (not deletion), and preservation of historical events for recent_alerts. This goes beyond annotations, though idempotency behavior is not explicitly described.

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

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

Three sentences with no wasted words. The main action is front-loaded, and each sentence adds distinct value (action, ownership, deactivation effect). Perfectly 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 simple one-parameter tool with no output schema, the description covers the key behavioral aspects: what the tool does, ownership constraint, and database effect. It could be improved by mentioning error cases (e.g., invalid id) or confirming idempotency explicitly, but overall it is fairly 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 the parameter 'id' already described as 'Subscription id (uuid) returned by subscribe.' The description reiterates 'by id' and adds the origin hint ('returned by subscribe'), which is helpful but not essential 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 action ('Cancel a subscription by id'), the resource (subscription), and important constraints (ownership enforcement, deactivation vs deletion). It distinguishes from siblings like 'subscribe' and 'list_subscriptions' by clarifying the cancellation semantics.

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

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

The description implies when to use (to cancel a subscription you own) but does not explicitly state when not to use or mention alternatives. The sibling context includes 'subscribe' and 'list_subscriptions', but no direct guidance on switching between them is provided.

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 rich behavioral context: returns a verdict (confirmed/approximately_correct/etc.), extracted structured form, actual value with citation, and percent delta. It also mentions it replaces 4-6 sequential calls, providing insight into its internal pipeline.

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 trigger phrases and examples. Every sentence contributes: trigger phrases, usage guidance, domain specification, source, and return fields. It is concise yet comprehensive without redundancy.

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

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

Given the simple input schema (one parameter, no output schema), the description is fully complete. It explains what the tool does, when to use it, its domain limitations, and what it returns. Annotations cover safety, so no additional behavioral disclosure needed.

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

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

The single parameter 'claim' has 100% schema coverage with a clear description. The tool description adds significant value by providing examples, explaining the natural-language nature, and clarifying the domain constraints 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 the tool's purpose: claim verification against authoritative sources. It provides trigger phrases like 'Is it true that…' and specifies the domain (company-financial claims). It distinguishes from sibling tools by noting it replaces multiple sequential calls, making its value proposition clear.

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' and limits the domain to company-financial claims. While it doesn't explicitly state when not to use it, the domain restriction provides clear context for appropriate usage.

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