Opencages

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

Annotations indicate readOnlyHint, openWorldHint, idempotentHint true, destructiveHint false. The description adds behavioral context: default model is free, Anthropic requires BYO API key (you pay Anthropic), returns per-model and combined results. No contradiction.

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

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

Two sentences, front-loaded with the core action, no redundant words. Each sentence adds essential information (purpose, default, optional key, return format, use cases).

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

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

Despite no output schema, the description specifies return structure (per-model {score, confidence, signals, raw_response} + combined view). All 4 parameters are described in schema and partly in description; the description is complete enough for effective use.

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

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

Schema coverage is 100%. The description adds meaning beyond schema: explains default model usage, the need for _apiKey when using 'anthropic', and the purpose of context for disambiguation. Provides practical cost/usage context.

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

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

The description clearly states the tool probes LLMs for knowledge about an entity and scores visibility (0-100) per model. It names the default model and optional Anthropic integration, distinguishing it from sibling tools like ask_pipeworx which focus on specific entities.

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

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

The description explicitly lists use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It does not provide explicit when-not-to-use guidance but the context is clear enough for appropriate 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?

The description discloses the tool's internal routing behavior ('routes the question to the right one of 5,566 tools across 1462 verified sources'), argument construction, and the return of structured answers with stable pipeworx:// citation URIs. This adds behavioral context beyond the annotations (readOnly, openWorld, idempotent) by explaining how the tool operates and what output to expect, without contradicting the annotations.

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

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

The description is overly long and contains marketing fluff and redundancy (e.g., 'START HERE for most questions', 'one fast call', 'works on every tier'). While well-structured with a bolded lead-in and examples, it could be condensed by half without losing critical info. The multiple parentheticals and exclamations ('*', 'even if web search could also answer it') detract from conciseness.

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

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

For a single-parameter tool with no output schema, the description is exceptionally thorough, covering input format, domain scope, example queries, output characterization (citations), and escalation paths. It even addresses niche edge cases like breaking-news queries, making it comprehensive 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 documents the 'question' parameter and its aliases with 100% coverage and includes example questions. The description offers no additional parameter-level details, so the baseline of 3 applies. While examples provided in the description are useful, they duplicate the schema's examples and add minimal new semantic 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 opens with a clear directive, 'PREFER OVER WEB SEARCH', and immediately states it answers questions about current or historical data across numerous domains with citations. It explicitly distinguishes itself from sibling tools by naming ask_pipeworx_grounded and deep_research as step-up alternatives, making the purpose highly specific and non-tautological.

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

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

Provides explicit when-to-use guidance: 'Use whenever the user asks "what is", "look up", "find"...' and also when not to use, directing users to ask_pipeworx_grounded for hallucination-resistant answers and deep_research for broad/multi-part questions. It also mentions fallback behavior for breaking news, offering a complete picture of applicability.

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

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

Annotations already cover read-only, idempotent, non-destructive. Description adds meaningful context: experimental beta status, candidate routing tests, comparison against stable router, and reassurance that it's a full working router with no fallback. 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?

Every sentence earns its place: describes beta status, current state, usage instruction, and clarification of fallback. Front-loaded with 'Beta version of ask_pipeworx,' compact and no fluff.

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

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

For a universal router with an open-ended question parameter and no output schema, the description sufficiently explains response shape by referencing the stable version, clarifies the absence of active candidates, and states it's a full working router—complete for its 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% (all parameters documented). Description adds no parameter-specific information beyond referencing 'question' in passing; baseline 3 is appropriate since schema carries the full 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?

Clear specific verb 'ask' with resource 'Pipeworx' and scope as beta universal router. Distinct from siblings by explicitly mentioning it's the beta version with candidate routing improvements, differentiating from ask_pipeworx and ask_pipeworx_grounded.

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

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

Explicitly says to use it exactly like ask_pipeworx when wanting the newest routing, and clarifies it currently matches the stable router. Provides clear context for use, though it doesn't name alternatives explicitly or state when not to use it beyond implying preference for experimental routing.

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 goes well beyond by disclosing the grounding mechanism, the exact success return structure, and explicit refusal reasons (not_in_source, no_tool_match, tool_error, data_truncated, llm_error). It also notes the additional LLM call cost, which is critical for agent planning.

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

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

The description is dense but not rambling. Every sentence adds value: purpose, routing behavior, output format, refusal semantics, use cases, and cost tradeoff. It front-loads the key qualifier 'hallucination-resistant' and then systematically elaborates 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 having no output schema, the description fully specifies the return payload and all possible refusal outcomes. It also covers the tool's relationship to ask_pipeworx, the routing detail, and the cost implication. The description is complete enough for an agent to safely invoke it in high-stakes scenarios.

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

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

Schema description coverage is 100% (all params documented as aliases for question). The description doesn't add new parameter-level meaning beyond what the schema provides, but it does clarify that the input is a natural language question. This is sufficient per the baseline rubric for high coverage.

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

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

The description clearly states the tool's purpose: a hallucination-resistant answer mode that extracts answers only from tool results. It distinguishes itself from the sibling ask_pipeworx by emphasizing groundedness and explicit refusal behaviors. The verb 'ask' plus the 'grounded' qualifier makes the function unmistakable.

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

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

The description provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' It also names the alternative: 'prefer ask_pipeworx for casual lookups' and explains the tradeoff (extra LLM call). This is model guidance for tool 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?

The description extensively discloses behavioral traits beyond annotations: low-confidence resolutions short-circuit, closed markets return status, wide spreads flagged, cancellation rules parsed. It also warns about inspecting market_match_confidence before trusting analysis. No contradictions with annotations.

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

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

The description is lengthy and detailed, but the complexity of the tool justifies the length. It is well-structured with clear sections (classifiers, fan-out examples, response shapes, safety). Could be slightly more concise, but every section adds necessary 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?

The description fully covers all aspects: input formats, parameters, behavior for various cases (low confidence, closed markets, wide spreads), cancellation rules, response structure, and safety mechanisms. No gaps given the tool's complexity and absence of output schema.

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

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

Schema coverage is 100%, and the description adds significant value beyond the schema: explains market input flexibility (slug, URL, text), depth levels with defaults and trade-offs, and include_raw effects on response size. Examples further clarify usage.

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

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

Description clearly states the tool researches a Polymarket bet by pulling Pipeworx data. It specifies input formats (slug, URL, question text) and provides example use cases. Distinguishes itself from sibling tools like polymarket_edges and polymarket_arbitrage by focusing on single-bet research.

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

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

The description includes explicit use cases like 'should I bet on X' and explains the tool's workflow (resolve, classify, fan out, return evidence). However, it does not explicitly state when not to use it or compare to alternatives, though context from sibling names provides some differentiation.

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 valuable context: it details the specific data pulled for each entity type (financial metrics for companies, adverse event and approval counts for drugs), handles off-calendar fiscal years, explains result sorting, and mentions citation URIs. No contradiction with annotations.

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

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

The description is a single paragraph that packs substantial information. While it is efficient, it could be more structured (e.g., bullet points for data pulled per type) to improve skimmability. However, it is front-loaded with user-facing queries and gets to the point quickly.

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 the return format (paired data with citation URIs), the data sources (SEC EDGAR/XBRL, FAERS, FDA, trials), and edge cases (off-calendar fiscal years). For a tool with moderate complexity and good annotations, this is complete and sufficient.

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

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

Schema coverage is 100% and already includes enums and constraints. The description adds meaning by explaining that 'values' should be tickers/CIKs for companies and names for drugs, provides examples, and clarifies what data each type returns. This goes beyond the schema's basic descriptions.

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

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

The description starts with natural language triggers ('Compare X and Y', 'X vs Y') and clearly states the action: side-by-side comparison of 2-5 companies or drugs in one parallel call. It distinguishes from sequential single-pack lookups and specifies the resource (SEC EDGAR/XBRL for companies, FAERS/FDA/clinical trials for drugs).

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

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

The description explicitly prefers this tool over sequential lookups and gives example queries. It explains behavior for 'company' vs 'drug' types and mentions result sorting. However, it does not specify when NOT to use it, such as when a detailed individual entity profile is needed (like entity_profile), missing an opportunity for clearer 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 signal read-only/idempotent/discovery behavior. The description adds substantial beyond-annotation context: parallel multi-tool routing, gaps[], contradictions[], hop fields, fetchable citation URIs, semantic excerpting, latency expectations, and account requirements. No contradiction with annotations.

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

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

The description is long and dense, but nearly every clause adds value, including account constraints, output format, successor behavior, and performance expectations. Structure could be improved with paragraph breaks or headers, but it is not wasteful.

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

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

Despite having no output schema, the description fully explains what the return packet contains: verbatim evidence, confidence, source, fetched_at, citations, gaps[], contradictions[], and hop fields. It also covers limitations, latency, and when results will be empty, making it highly complete for a tool of this complexity.

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

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

Schema description coverage is 100%, and the schema already explains both parameters in detail, including depth semantics and question guidance. The description reinforces the same ideas but adds no new parameter-level meaning beyond what the schema provides.

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

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

The description clearly states the tool's function: 'Grounded multi-source research across Pipeworx's 1462 STRUCTURED data sources' in ONE call. It distinguishes itself from siblings by explicitly saying 'this is NOT open-web search' and contrasting with ask_pipeworx for single lookups.

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

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

Usage guidance is explicit: use for 'broad/multi-part questions over structured data', prefer ask_pipeworx for single lookups and 'BREAKING or colloquial CURRENT-NEWS'. It also provides account/tier prerequisites and directs unsigned-in users to ask_pipeworx.

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 behavioral context beyond annotations: returns top-N tools with schemas and examples, each ready to call. Annotations already indicate safety and idempotency.

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

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

Single paragraph, front-loaded with purpose, no redundant sentences, efficient use of language.

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

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

Given 6 parameters (1 required) and no output schema, description adequately covers what the tool does and what it returns. Could mention pagination but not required.

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

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

Schema coverage is 100%. Description adds meaning by explaining the query parameter's role as natural language and listing aliases. Limit parameter is explained.

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 tools by describing data or task, lists explicit domains, and distinguishes it from specific tools in sibling list.

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 'Call this FIRST' for browsing the option set, providing clear usage context. Doesn't explicitly state when not to use but implies it's for discovery.

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. Description adds behavioral detail: fans out across multiple sources, returns specific fields, makes one parallel call, and notes failure mode for patents.

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

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

Description is detailed and well-structured with examples, main purpose, then specifics. Slightly longer than necessary but justifies length with valuable information.

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

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

Despite no output schema, description fully discloses return fields (cik, company_name, recent_filings, fundamentals, patents, news, LEI) and format (URI). Covers limitations and fallback behavior comprehensively.

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

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

Adds meaning beyond schema: explains type only supports 'company', value must be ticker or CIK, and explicitly says names not supported. Schema coverage is 100%, and description fully clarifies parameter constraints.

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?

Explicitly states the tool provides a 'full cross-source profile of a US public company in ONE parallel call' and lists example queries. It clearly differentiates from siblings like compare_entities and resolve_entity by specifying when to prefer this tool.

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

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

Provides explicit guidance: 'ALWAYS PREFER over chaining single-pack ... lookups when the user asks for a holistic view' and instructs to use resolve_entity for names. Also notes patents soft-fails after May 2025.

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

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

Annotations already indicate destructiveHint=true, which the description aligns with ('delete'). The description adds context about clearing sensitive data, but does not contradict annotations. No additional behavioral traits are needed.

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-load the purpose and usage guidance with no wasted words. Perfectly concise for the tool's simplicity.

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 action, when to use it, and how it relates to siblings. No missing context given the tool's simplicity and good annotation coverage.

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

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

Schema coverage is 100% with a single parameter 'key' described as 'Memory key to delete'. The description adds no extra semantics beyond the schema, meeting the baseline expectation.

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 deletes a memory by key (verb 'Delete', resource 'memory'). It distinguishes from siblings like 'remember' and 'recall' by contrasting the action.

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

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

Explicit usage guidance: 'Use when context is stale, the task is done, or you want to clear sensitive data.' It also pairs with siblings 'remember' and 'recall', providing context for alternative actions.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds that the tool fetches the page and emits a text blob, but this is expected given the annotations. No contradiction and adds some context.

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

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

The description is concise (4 sentences) and front-loaded: purpose first, then process, output, and use cases. 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 simple tool with well-documented parameters and annotations, the description covers purpose, process, output format, and use cases. It lacks error handling or prerequisites but is adequate for this level of 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% and both parameters (url, max_links) are already fully described in the input schema with details like default and max. The description adds no additional meaning beyond what the schema provides.

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

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

The description clearly states it generates a production-ready llms.txt file for any URL, specifying the actions (fetch, extract, emit) and the output format. However, it does not explicitly differentiate from siblings like ai_visibility_check or scan_competitor_ai_presence, which have overlapping use cases.

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

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

The description provides clear use case scenarios (getting client's site indexed, drafting, auditing competitor) but does not mention when not to use it or suggest alternative tools.

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

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

Annotations already indicate read-only and idempotent behavior. The description adds context beyond annotations: mentions external API dependency (OpenCage), authentication requirement (API key), and return types (coordinates and structured address components). 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?

Single sentence efficiently conveys the tool's purpose, prerequisite, and key features. Front-loaded with the main action, 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 an output schema exists (as per context signals), the description appropriately omits return value details. However, it could mention rate limits or authentication setup alongside the API key requirement. Overall, sufficiently complete for a geocoding 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 low (29%), with only bounds and countrycode having descriptions. The description broadly mentions supported filters but does not detail each parameter's meaning or format. Many parameters (abbrv, limit, language, no_annotations) lack clarification, and the description does not compensate adequately.

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 ('Forward-geocode'), the resource ('address or place name to latitude/longitude'), and the data source ('OpenCage'). It differentiates from sibling tools like 'reverse' by specifying forward geocoding.

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

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

The description states a prerequisite ('requires API key') and lists supported features (country-code filtering, bounding box, language). It implies when to use this tool but does not explicitly exclude alternatives or provide 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 readOnly, idempotent, non-destructive. The description adds value by specifying the returned fields and optional parameter, without contradicting annotations.

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

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

Two concise sentences front-loading purpose and usage guidance, with no wasted words.

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

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

For a simple list tool with no output schema, the description covers purpose, return fields, usage guidance, and the optional parameter adequately.

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

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

Schema description coverage is 100% for the single parameter; the description does not add additional meaning beyond what the schema provides.

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

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

The description explicitly states 'List the caller's active subscriptions' with a specific verb and resource, and distinguishes from siblings like 'subscribe' and 'unsubscribe'.

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

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

The description advises using this tool to 'review what you're monitoring before adding more or to find an id to cancel', providing clear context for its use.

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

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

Discloses critical behavior beyond the sparse annotations (all false): anonymous filing returns a claim_token, how to use that token later to check status, daily rate limit of 5 per identifier, free usage without quota impact, and that feedback is read daily and affects roadmap. This gives the agent a clear mental model of side effects and stateful behavior.

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 longer than typical (10 sentences) but each sentence earns its place: purpose, use cases, exclusions, claim_token mechanics, rate limit, and business context. It is front-loaded with the key purpose and well-structured. Slightly verbose for a feedback tool, but not wasteful.

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

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

With no output schema and all annotations false, the description carries full burden. It fully covers: what to report, scoping exclusions, how to follow up on a submission, rate limits, cost implications, and when to use which type. Even the nested context object is implicitly covered by 'Describe the issue in terms of Pipeworx tools/packs.' No important behavioral gap remains.

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 value by explaining the claim_token lifecycle (how to pass it back), the meaning of type categories (already in schema but reinforced), and the instruction to reference Pipeworx tools/packs rather than pasting user prompts. This enriches the context/message parameters beyond the raw schema.

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

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

Description opens with a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes from sibling tools (e.g., ask_pipeworx, discover_tools) by scoping exclusively to tools served by this Pipeworx connection and framing feedback categories (bug, feature, data_gap, praise).

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

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

Explicitly states when to use the tool ('Use when a tool returns wrong/stale data, when a tool you wish existed isn't in the catalog, or when something worked surprisingly well') and provides a clear when-not: it is ONLY for tools served by this Pipeworx connection, with instructions to file elsewhere for other MCP servers. Includes specific guidance on what to describe (Pipeworx tools/packs, not end-user prompts).

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds value by explaining the data source (CF analytics-engine), the composition (pack, tool, count), privacy (no PII), and caching behavior (5min-1h). This goes beyond what annotations convey.

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

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

The description is three concise sentences followed by a bullet list of use cases. It is front-loaded with the core purpose and avoids fluff. Every sentence provides meaningful information 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?

While the description covers purpose, usage, and parameter semantics, it lacks explicit detail about the return format (e.g., JSON structure, field types). Given no output schema, this omission leaves the agent uncertain about what to expect. However, the tool is simple enough that most agents can infer the output.

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

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

With 100% schema coverage and a single parameter well-described via enum and description, the description adds additional context about how window choice affects results (short vs long windows) and provides a default, which aids selection 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 returns top tools, top packs, and total call volume over configurable time windows. It includes three specific use cases that differentiate it from any sibling tool, which all focus on different functionalities.

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 choices, aligning use cases) and explains the parameter trade-off (short vs long windows). It does not provide when-not-to-use guidance, but the purpose is sufficiently unique 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?

While annotations declare readOnlyHint=true, the description adds substantial behavioral context beyond this: details of internal checks (monotonicity, partition checks, Jaccard similarity, placeholder filtering, fill check). It explains response structure and limitations (e.g., 'do not trade it' when fill check fails). No contradictions.

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

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

The description is lengthy but well-structured with sections, bullet points, and bold labels. Every sentence adds value, explaining complex logic clearly. However, it could still be slightly more concise without losing essential details.

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

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

Given the tool's complexity (multiple modes, sophisticated checks, and detailed response), the description covers all necessary aspects: modes, parameters, internal logic, response structure, fill check, and references to related tools (polymarket_fill_risk). No output schema is provided but description compensates by detailing response fields.

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

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

Schema description coverage is 100% with clear descriptions. The description adds extra context for each parameter: explains the recommended usage, accepted formats (e.g., 'Full Polymarket URLs also accepted' for event), and the consequences of each choice. With high schema coverage, the extra value earns a 4.

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

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

The description clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes from siblings by specifying the unique methods and multiple modes (event, topic, no-args).

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 when to use each mode: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', 'topic (for cross-event scanning)'. It includes examples and explains when cross-event mode is beneficial over single-event. Also warns when not to trade (if realizable_edge_pp ≤ 0).

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds extensive detail: caching policy (1h KV), three response segments, edge calculation formulas, diagnostics for empty segments, and 24h move warnings. 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?

Highly informative but very long (over 500 words). Structure is logical (purpose, segments, edge details, knobs, response) and front-loaded with purpose, but the density and length reduce conciseness. Not minimal; sentences carry value but could be simplified.

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 9 parameters, no output schema, and complex behavior, the description covers all aspects: response structure with three segments, fed bet handling, diagnostics, edge fields, caching, and parameter effects. Complete enough for an agent to use effectively.

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 9 parameters have schema descriptions (100% coverage). The tool description further explains the 'tradeable-edge knobs' in context, linking them to filtering logic and practical usage (e.g., min_liquidity to avoid thin books). Adds meaningful usage guidance beyond schema.

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

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

Clearly states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price. The purpose is specific and differentiated from sibling tools like polymarket_arbitrage by focusing on Pipeworx data and edge 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?

Implies usage for daily betting decisions ('what should I bet on today') but does not explicitly state when to use versus siblings like polymarket_edge_tracker or polymarket_arbitrage. No exclusion criteria or alternative suggestions.

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

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

Annotations already indicate read-only, open world, idempotent, non-destructive. The description adds rich behavioral details: it uses snapshots, provides time-series, doesn't access intraday data, and limits history by TTL. No contradiction with annotations.

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

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

The description is well-structured with sections for arguments, response breakdown, and limits. Every sentence adds value, no fluff. It's long but necessary for completeness and clarity.

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

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

Despite no output schema, the description thoroughly explains response structure (tracked, expired, snapshot_dates) and limitations (TTL, snapshot start). It fully compensates for missing schema and provides all needed context.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by giving defaults, ranges (max 30 for days), and examples ('1wk' for window). It also explains response fields tied to parameters, enhancing understanding.

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

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

The description clearly states the tool's purpose: providing edge persistence and decay telemetry from daily snapshots. It explicitly answers specific questions ('how long has this edge existed and is it shrinking?') and distinguishes itself from siblings like polymarket_edges by focusing on historical trends.

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

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

The description includes detailed parameter explanations and limits (e.g., lookback bounds, snapshot TTL). It implies when to use (for historical edge analysis) but doesn't explicitly state when not to use or mention alternatives, though siblings provide 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?

The description aligns with annotations (readOnlyHint, idempotentHint, destructiveHint=false), confirming no mutation. It adds significant behavioral context: 'walks the ladder,' returns a verdict (clean|degraded|cannot_fill), and explains partial fill risks. This goes well beyond what annotations provide, disclosing operational details and hazard scenarios.

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

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

The description is long but well-structured with capitalized sections (SINGLE-MARKET, BASKET) and lists of return fields. Every sentence carries information—no filler. It's slightly verbose given the complexity, but the structure aids readability. A minor point prevents a 5.

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 values for both modes (e.g., top_of_book, vwap_fill_price, slippage_pp, verdict for single-market; theoretical_sum, realizable_sum, capture_ratio, profit_usd, thin_legs, forced_directional_risk for basket). It also covers edge cases like partial fills and unhedged risk, making the tool self-contained for an AI agent.

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

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

Schema description coverage is 100%, and the tool description adds substantial meaning: it explains the 'side' parameter's default and basket-specific interpretation, clarifies that 'size_usd' is interpreted differently for buys vs sells, and notes clamping range (10–1,000,000). This enriches the schema descriptions significantly.

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 as a 'Realizable-vs-theoretical edge check against live CLOB order-book depth' and specifies two distinct modes (single-market and basket). It distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by explicitly stating when to use it ('USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500').

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

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

The description provides explicit guidance on when to use the tool (before arbitrage signals or trades above $500) and warns about risks of partial basket fills converting an arb into an unhedged directional position. It indirectly specifies when not to use it (for small trades below $500) and references alternative tools as sources of signals that should be pre-checked.

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 provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds significant behavioral detail: it explains that compatibility_warning indicates non-equivalent bet shapes or semantically unrelated events, temporal alignment issues, and skipped cross counters. This goes well beyond the annotations.

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

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

The description is well-structured with sections for modes, response, and safety fields. It is front-loaded with the core purpose. However, it is quite lengthy; some redundancy (e.g., repeating 'pre-mapped ≠ tradeable' at the end) could be trimmed for conciseness.

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

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

Despite no output schema, the description fully details response fields (leg-by-leg prices, top_spreads_pp, compatibility_warning, temporal_alignment, skipped counters). It covers error cases and interpretation, making the tool's behavior completely transparent for an agent.

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

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

Schema coverage is 100% (all 3 params documented), baseline 3. The description adds value by enumerating the 10 topic shortcuts and providing explicit examples for kalshi_event_ticker and polymarket_event_slug, enhancing understanding beyond the schema.

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

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

The description clearly states the tool calculates cross-venue spreads between Kalshi and Polymarket. It distinguishes from siblings by focusing on spread analysis between two venues, unlike polymarket_arbitrage which is single-venue. The two modes (topic shortcuts and explicit tickers) are explicitly listed.

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

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

The description explains when to use each mode and warns that most pre-mapped topics return compatibility_warning, guiding the agent not to assume tradeability. However, it does not explicitly tell the agent when to prefer this over a sibling like polymarket_arbitrage, though the context is clear enough.

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

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

Annotations declare readOnlyHint, idempotentHint, and destructiveHint. Description adds scoping detail ('to your identifier') and relationship to remember/forget, which annotations do not cover. No contradiction.

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

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

Two sentences, front-loaded with the core action. No wasted words. Every sentence contributes meaningful information.

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

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

For a single-parameter, read-only tool with rich annotations, the description covers purpose, usage, scoping, and pairing. No gaps remain.

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

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

Schema coverage is 100%. Description adds meaning by explaining that omitting the key lists all keys, which goes beyond the schema's description. Examples in schema complement this.

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

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

Clearly states verb 'retrieve' and resource 'value saved via remember', with the alternative action of listing all keys when the argument is omitted. Distinguishes from sibling tools remember and forget by 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?

Explicitly says when to use ('look up context the agent stored earlier') and how (omit key to list). Pairs with remember and forget. Lacks explicit 'when not to use' or alternatives beyond 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?

The description fully discloses the side effect of mark_read:true (flags events as read so subsequent calls show only newer ones), which goes beyond the annotations (readOnlyHint=true, idempotentHint=true). It explains the returned fields and the feed behavior, adding behavioral context that annotations alone do not 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 packed into five concise sentences, with the main action front-loaded. Every sentence adds value—no redundancy or filler. It efficiently covers purpose, parameters, return data, side effects, and alternatives.

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

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

Despite having no output schema, the description covers return format, filtering options, pagination via limit, and the read-flagging mechanism. It is complete enough for an agent to invoke correctly without external documentation.

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

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

With 100% schema coverage, the description adds meaning beyond the schema: clarifies that mark_read affects next call results, that since expects an ISO timestamp, and that type filters subscription types. It also mentions typical response fields (source, citation_uri, payload), which is not in the schema but aids understanding.

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

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

The description opens with a clear verb+resource ('Pull fired events from your subscription feed'), specifies the return type (recent alerts with source, citation_uri, payload), and mentions filtering by type and since. This differentiates it from siblings like list_subscriptions or recall which operate on different entities.

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

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

The description explicitly states that polling works fine and provides an alternative endpoint for scripts/dashboards. While it doesn't exhaustively cover all sibling alternatives, it gives practical guidance on when to use this tool versus a direct HTTP call.

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

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

Annotations already declare readOnly, idempotent, openWorld hints. Description adds details about multiple data sources, fallback behavior, USPTO soft-fail reason, and return format including citation URIs.

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

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

Every sentence adds value. Front-loaded with usage examples. No redundant or unclear phrasing. Efficiently covers all necessary aspects.

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

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

Despite no output schema, description explains return format (grouped changes, total count, citation URIs). Covers behavioral aspects, fallbacks, and failure modes completely 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 covers all 3 parameters. Description adds examples for 'since' (ISO date and relative shorthand) and suggests '30d' or '1m' for monitoring. Clarifies 'value' can be ticker or zero-padded CIK.

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

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

Description clearly states tool provides a change feed for a company, combining multiple sources. Explicitly distinguishes from sibling 'entity_profile' by stating when to use each.

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 guidance with example queries and a clear condition for when to use entity_profile instead of recent_changes. Also suggests typical monitoring window values.

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

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

Beyond annotations (readOnlyHint, idempotentHint, destructiveHint), description adds key behavioral traits: key-value scoping by identifier, persistence differences for authenticated vs anonymous sessions, and 24-hour retention limit. 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?

Four sentences with no wasted words. Front-loaded with main purpose, followed by usage guidance and behavioral details. Every sentence contributes essential information.

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

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

For a simple 2-param tool with no output schema, the description thoroughly covers usage, persistence, scoping, and relationship to sibling tools. Complete and self-contained.

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

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

Schema coverage is 100% with clear descriptions for both parameters. Description adds value by providing naming conventions and examples ('subject_property', 'target_ticker'), making parameter intent clearer.

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 'Save data the agent will need to reuse later' with a specific verb and resource. Distinguishes itself from siblings 'recall' and 'forget' by mentioning them explicitly in usage guidance.

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 describes when to use ('when you discover something worth carrying forward') and pairs with sibling tools ('Pair with recall to retrieve later, forget to delete'), providing clear usage context and alternatives.

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

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

Annotations already declare readOnly/idempotent/openWorld; the description adds graceful degradation if GLEIF/OpenFIGI are unavailable, explicit handling of unresolved identifiers, and continuous cascading lookup behavior. This is substantial non-redundant behavioral context beyond annotations.

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

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

The description is verbose but well-structured, front-loading example queries. Every sentence adds technical content (supported types, fallback, output format), though length is at the upper bound. Not a 5 due to slight redundancy and marketing phrases like 'cross-source identity spine'.

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 two entity types, multiple identifier sources, and no output schema, the description covers input formats, output structure (labeled sources, unresolved field), fallback behavior, and internal cascading. Return types for drugs are specified, making it complete for an agent to select and 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 the baseline is 3. The description enriches semantics by explaining ISIN-to-LEI mapping for non-US issuers, acceptance of ticker/CIK/name, and drug RxCUI details, going beyond schema's brief descriptions. This lifts the score to 4.

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

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

The description clearly defines the tool as resolving user-spoken names to canonical identifiers, with specific verbs ('resolve', 'look up') and resource types. It distinguishes from siblings by stating 'Use FIRST whenever you have a name but need an ID', implying a prerequisite role. The supported types (company, drug) are enumerated, providing unambiguous purpose.

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

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

Explicitly instructs 'Use FIRST whenever you have a name but need an ID', giving a clear trigger condition. It also explains the tool replaces multiple manual lookups, and mentions that ISIN inputs resolve to legal entities, guiding when to use which input format. The directive is strong enough to guide 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 indicate readOnly, idempotent, and non-destructive behavior. The description adds that it uses an external API (OpenCage) and requires an API key, which is beyond annotation info. It does not mention rate limits or potential errors, but overall adds useful context.

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

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

The description is a single sentence that is action-front-loaded, providing the core purpose, dependencies, and key output fields. No extraneous words.

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

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

An output schema exists but is not detailed here. The description covers the main inputs and outputs but omits explanation of optional parameters. Given the tool has 5 parameters and 0% schema coverage, the description is incomplete for full parameter 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 0%, so the description must compensate. It explains the input lat/lon and lists return fields, but does not describe the optional parameters (abbrv, language, no_annotations). This leaves the agent without understanding the optional parameters' meaning.

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

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

The description clearly states the tool performs reverse geocoding (converting lat/lon to address) using OpenCage. It specifies the tool's action, resource, and distinguishes from sibling 'geocode' which is forward geocoding.

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 mentions 'requires API key,' indicating a prerequisite. The sibling list includes 'geocode,' implying this is for reverse geocoding. However, it does not explicitly state when to use or when not to use this tool versus alternatives, leaving some ambiguity.

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

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

Annotations indicate read-only, non-destructive, idempotent behavior. The description adds valuable context: it probes each entity with 'ai_visibility_check' and returns a ranked list with score, confidence, signal density. No contradictions with annotations.

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

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

Two concise sentences that front-load the purpose and include context and output format without unnecessary words.

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

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

For a tool with 4 parameters, no output schema, and moderate complexity, the description adequately explains behavior, output format, and use case. Could mention limitations like max entities, but not essential.

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 parameters are well-documented. The description adds meaning beyond schema by stating the first entity is treated as the 'subject' for narrative, which aids agent understanding of how to use entities.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, using specific verbs like 'probes', 'ranks', and 'surfaces'. It distinguishes from sibling 'ai_visibility_check' by focusing on multiple entities together.

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') with an example question. It does not explicitly mention when not to use or compare to alternatives like 'compare_entities', but the context is well-defined.

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 read-only, idempotent, non-destructive, open-world. Description adds behavioral details: fans out across two services, returns specific summary fields, per-advisory detail, links, alternatives. Warns about bundlephobia latency and sources_failed field for timeouts.

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

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

Description is informative but slightly lengthy; however, every sentence adds value. Front-loaded with 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?

No output schema, but description fully explains return fields (summary block, per-advisory detail, links, alternatives) and handles partial failures. Covers input, output, behavior, and failure modes for a composite tool.

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

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

Schema has 100% description coverage. Description adds that scoped packages (@types/node) are accepted and that version defaults to latest published when omitted, which adds value beyond the schema.

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

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

Clearly states it's a composite check for npm packages combining deps.dev and bundlephobia, with specific use case 'should I add this npm package to my project'. Distinguishes from siblings by noting NPM only in v1 and alternatives for other ecosystems.

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

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

Explicitly says 'Use whenever an agent asks is X safe/popular/small' and provides guidance on partial failures. Mentions ecosystem limitation and fallback to deps.dev:version for other ecosystems.

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

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

Annotations already indicate readOnlyHint, idempotentHint, etc. The description adds valuable details: the algorithm (BGE-base-en embeddings + cosine overlap), windowing (500-char overlapping windows), character cap (200K chars with truncation/flagging), and verification mechanism (character offsets). 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 concise (three sentences) and front-loaded with the core purpose, then usage, then technical details. Every sentence adds essential information 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 tool has no output schema, the description adequately explains the return values (top-N passages with character offsets and similarity scores) and mentions truncation flag. It covers usage context, behavioral traits, and parameter constraints, leaving little ambiguity for an agent.

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

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

Schema description coverage is 100%, so the schema already documents all parameters adequately. The description adds some context (e.g., the cap of 200K chars for 'text' and examples for 'query') but does not significantly extend 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 performs semantic search inside a provided text, with specific verb 'search inside' and resource 'fetched record'. It distinguishes itself from siblings by focusing on searching within a pre-fetched text rather than external sources.

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

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

The description explicitly states when to use this tool ('when the record is too big to cram into the prompt') and mentions a complementary sibling tool (ask_pipeworx_grounded). It does not provide explicit when-not scenarios, but the guidance is clear.

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

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

The description discloses behavioral traits beyond annotations: it requires an OAuth account, explains that anonymous/BYO cannot persist subscriptions, details delivery channel specifics (SMS cap, webhook signing, auto-disable), and states the return value (subscription ID). No contradiction with annotations.

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

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

The description is well-structured, front-loading the core purpose and output. It then proceeds logically to account requirements, supported types with examples, and delivery channels. While it is quite detailed and somewhat verbose, every sentence adds value, and the structure aids readability.

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 moderately high complexity (3 parameters, one with enum, nested objects), the description fully covers account prerequisites, type-specific parameters, delivery options, and constraints. It also states the return value despite no output schema, making it complete for most use cases.

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?

Despite 100% schema coverage, the description adds significant meaning: it explains each subscription type in detail (e.g., parametrized examples for sec_8k, polymarket_edge, fred_series), describes delivery channel semantics (email validation, SMS verification, webhook restrictions and signing), and clarifies constraints not fully captured by the schema (e.g., webhook URL HTTPS-only, localhost rejected).

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 creates a proactive monitoring subscription to a live-data event stream and returns the subscription ID. The verb 'Create' and resource 'subscription' are specific, and it distinguishes from siblings like list_subscriptions and unsubscribe.

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

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

The description specifies the account requirement (Pipeworx OAuth) and provides detailed guidance on supported subscription types with examples (e.g., sec_8k for SEC filings, polymarket_edge for mispricings). It also explains delivery channel options and their restrictions, though it does not explicitly state when not to use this tool or list alternatives.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, etc. Description adds that the tool draws from a live catalog and returns example questions. No behavioral surprises. Adequate transparency beyond annotations.

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

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

The description is relatively long but well-structured with alternative queries, output explanation, and usage instructions. It earns its length by being informative; minor trimming possible but not necessary.

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

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

For a simple tool with one optional parameter and no output schema, the description covers all necessary aspects: purpose, parameters, output, use case, and context. It is complete for an agent to decide when to invoke.

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

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

Schema coverage is 100%. Description adds value by listing example values for 'topic' (e.g., finance, pharma) and explaining behavior when omitted (cross-category spread). This enriches the schema-only 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 the tool returns category-bucketed example questions with tool calls, and positions it as the onboarding entry point. It distinguishes from sibling tools by specifying its role: 'Use this FIRST when you do not yet know what Pipeworx can do for you.'

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

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

Explicitly tells when to use: when the agent doesn't know what Pipeworx can do. Also gives optional 'topic' parameter to focus. Lacks explicit 'when not to use' but the context sufficiently guides usage.

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

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

Discloses beyond annotations: cancellation is a state change rather than deletion, ownership constraint, and historical data remains available via 'recent_alerts'. Complements idempotentHint and destructiveHint.

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

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

Two sentences, no filler, front-loaded with essential information. Every word contributes to understanding.

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 fully covers purpose, behavior, ownership, side effects, and connection to related tools.

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

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

The only parameter 'id' is described as 'Subscription id (uuid) returned by subscribe.', adding context beyond the schema. Schema coverage is 100%, and the description adds useful linkage.

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' with the resource 'subscription', and uses the verb 'cancel' and resource 'subscription by id'. It distinguishes from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

Explicitly states ownership enforcement ('you can only cancel your own subscriptions') and the effect ('row is deactivated, not deleted'), providing clear guidance on when and how to use the tool.

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

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

The description adds substantial context beyond the annotations: it explains the two-tier routing (fast path vs grounded pipeline), return structure (verdict, citation, reasoning), and critically clarifies the semantics of 'could_not_verify' (check did not happen, with error field) versus 'unsupported' (no source coverage). This is exactly the kind of behavioral nuance needed for correct interpretation.

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

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

The description is dense but well-organized: it opens with trigger phrases and a definition, then outlines usage, processing paths, return values, and a highlighted IMPORTANT note. Every sentence adds value, and the structure flows logically from purpose to details to caveats. No filler or redundancy.

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

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

The tool is complex (two processing paths, six possible verdicts, error semantics), yet the description covers all essential aspects: when to use, what routes, what it returns, and how to handle the critical could_not_verify vs unsupported distinction. Annotations cover safety, and no output schema exists, so the description carries the full burden—and it does so completely.

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

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

Schema coverage is 100%, so the schema already fully documents both parameters (claim and tolerance_pct) with examples and defaults. The description adds minimal parameter-specific information beyond what the schema provides—it references 'exact percent-delta math' but does not elaborate on tolerance usage. Therefore, the baseline of 3 is appropriate.

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

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

The description clearly states a specific verb+resource: natural-language claim verification. It provides trigger phrases and explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' It also outlines the two distinct processing paths (SEC EDGAR/XBRL for company financials, grounded pipeline otherwise), which distinguishes it from generic search or QA 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 gives clear usage context ('Use whenever the agent needs to check whether something a user said is factually correct') and explains how different claim types are routed. However, it does not name specific alternatives or state explicit exclusions (e.g., 'do not use for open-ended research'). This is strong but not fully explicit about when-not-to-use.

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