guif

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

The description fully aligns with annotations (readOnlyHint, idempotentHint, openWorldHint) and adds behavioral detail: it probes LLMs, returns per-model score/confidence/signals/raw_response plus combined view, defaults to a free model, and notes that Anthropic probes are paid. 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 three sentences, no fluff, front-loaded with the core action, and each sentence provides essential information (action, model/key details, 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?

Given no output schema, the description adequately covers return format (per-model fields + combined view). It covers parameters, models, key handling, and use cases. Annotations handle safety and idempotency, completing the context.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the role of _apiKey (only needed for Anthropic, passed directly), the default model, and the output structure. This goes beyond simply repeating schema descriptions.

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

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

The description clearly states the action (probe, score), the resource (LLMs), and the subject (business/brand/product/topic). It differentiates from siblings by specifying visibility scoring per model with a combined view, and lists use cases like AI-marketing audits, which distinguishes it from similar tools like scan_competitor_ai_presence.

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

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

The description provides clear context: default model is free, Anthropic requires a BYO key with direct payment. It lists specific use cases (audits, pre-launch checks, monitoring). However, it does not explicitly exclude alternative tools or state when not to use this tool, 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 already provide readOnlyHint, openWorldHint, etc. The description adds value by explaining the internal routing across 3,751 tools and 886 sources, filling arguments, and returning citations with stable URIs, which the annotations do not cover.

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

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

The description is slightly long but well-structured: starts with key instruction, lists domains, explains mechanism, and gives examples. Every sentence adds value, though could be trimmed slightly.

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, no output schema, and many siblings, the description covers purpose, usage, behavior, and examples well. Missing details about error handling or empty results, but overall complete for the complexity.

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

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

Schema description coverage is 100% with aliases and description. The description adds example questions and context for what constitutes a valid query, which is more than baseline.

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

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

The description states a specific verb ('ask') and resource ('pipeworx'), distinguishes from web search by explicitly preferring it over web search for factual questions, and lists extensive domains (SEC filings, FDA drugs, etc.) and examples.

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

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

The description explicitly says 'PREFER OVER WEB SEARCH' and provides explicit when-to-use indicators like 'for questions about...', 'Use whenever the user asks...', and lists example queries, leaving no 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?

Beyond annotations (readOnly, openWorld, idempotent), the description details the refusal mechanism, return format, and extra LLM call cost, adding significant behavioral context.

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

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

The description is moderately lengthy but all sentences are informative and front-loaded with the core purpose. Minimal waste.

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

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

Covers return format, refusal reasons, and usage trade-offs. Despite missing output schema, the description compensates fully, given the complexity.

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

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

Schema coverage is 100% with brief descriptions for each parameter alias. The description reiterates the natural language question but does not add deeper semantic meaning beyond the schema.

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

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

The description clearly states the tool's purpose as a hallucination-resistant answer mode for high-stakes reads, and it distinguishes itself from the sibling tool ask_pipeworx by emphasizing grounded extraction and explicit refusal.

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 (high-stakes, quoted/cited answers) and when to prefer ask_pipeworx (casual lookups), including a cost trade-off.

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

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

Annotations already indicate non-destructive, idempotent, read-only behavior. The description adds extensive behavioral details beyond annotations: resolution logic, fan-out patterns, response shapes, resolver contract, parent event extractor, news fallback fields, safety checks (low_confidence_match, market_closed_or_inactive, illiquid_wide_spread), and cancellation rule parsing. No contradiction with annotations.

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

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

The description is comprehensive but verbose. It is well-structured with clear section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.) that improve readability. However, some sections could be more concise; the list of classifiers and fan-out examples is lengthy but informative.

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

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

Given the tool's complexity and the absence of an output schema, the description is exceptionally complete. It covers purpose, inputs, processing (resolution, classification, fan-out), outputs (market, analysis, evidence, resolver contract, parent event, news fields), and multiple safety/edge cases (low confidence, closed markets, wide spreads, cancellation rules). No gaps.

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

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

Schema coverage is 100% with all parameters adequately described. The description adds extra context beyond the schema: depth enum is clarified ('quick = 2-3 evidence sources, thorough = full fan-out. Default thorough.'), market parameter is expanded with more input types, and include_raw includes size implications. This adds meaningful 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 explicitly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It lists inputs (slug, URL, question text) and outputs (evidence packet, market-vs-model comparison). Includes classifiers, fan-out examples, and distinguishes from sibling tools like polymarket_edges and polymarket_arbitrage.

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

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

Provides clear use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' Also gives explicit when-not-to-trust guidance: 'ALWAYS inspect these before trusting the analysis block, because medium/low matches can still surface other fields.' Includes safety notes on low-confidence resolutions, closed markets, wide spreads, and cancellation rules.

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 read-only, idempotent, non-destructive. The description adds rich behavioral details: exact data sources (SEC EDGAR/XBRL, FAERS), metrics (revenue, net income, cash, debt; adverse events, approvals, trials), handling of off-calendar fiscal years, sorting by primary metric, and citation URIs. No contradictions.

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

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

The description is front-loaded with common user queries, then explains functionality in a structured manner. Every sentence adds value, and it is concise (around 100 words) 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's complexity (two types, data from multiple sources, sorting, citations), the description covers all essential aspects: what data is returned, how results are sorted, number of entities, and citation URIs. No output schema exists, but the description adequately explains return values.

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

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

Schema coverage is 100%, but the description adds meaning beyond the schema: it explains that type='company' pulls specific financial data and type='drug' pulls specific regulatory and trial data, and that values are tickers/CIKs or drug names. This context is not in the schema descriptions.

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

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

The description clearly states the tool performs side-by-side comparison of 2-5 companies or drugs in one parallel call, using natural language triggers like 'Compare X and Y' and distinguishing from sequential lookups. It differentiates from siblings like entity_profile.

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 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' providing strong guidance on when to use this tool. It implies the alternative (sequential lookups) and recommends this tool over that.

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

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

The description adds significant behavioral context beyond the annotations: it explains the parallel decomposition, the return of gaps for unanswered facets, the guarantee of never inventing facts, the citation format ('pipeworx://'), and the pre-verification of facts. The annotations already indicate read-only, idempotent, and open-world behavior, and the description aligns without contradiction.

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

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

The description is front-loaded with the key benefit ('Grounded multi-source research in ONE call') and efficiently packs details like decomposition, tool routing, evidence structure, usage guidelines, and prerequisites. Each sentence serves a distinct purpose 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 complexity of the tool and no output schema, the description thoroughly explains the output format (structured findings packet with evidence, confidence, source, fetched_at, citation, and gaps). It covers all aspects: purpose, usage, input semantics, behavioral notes, prerequisites, and expected time. 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?

The input schema already provides 100% coverage with descriptions for both parameters ('question' and 'depth'). The description adds explicit mapping for depth values ('quick=3, standard=5, thorough=8 (paid plans)'), which is not in the schema. This adds value, but the schema already covers the core semantics well.

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

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

The description explicitly states the action ('Grounded multi-source research in ONE call'), the decomposition approach, and distinguishes from sibling 'ask_pipeworx' which handles single lookups. It clearly identifies the resource (multi-source research) and the specific verb ('decomposes', 'routes', 'extracts').

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 specifies when to use this tool ('Use for broad or multi-part questions') and when to use an alternative ('use ask_pipeworx for single lookups'). It also notes prerequisites (Pipeworx account, paid plan for 'thorough' depth) and expected response time (15-60s).

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds value by explaining the return format (top-N tools with schemas and examples) and that no second lookup is needed, providing clear behavioral context.

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

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

The description is front-loaded with the primary purpose and usage context. It includes a detailed list of domains which, while helpful, makes it slightly longer than necessary. Overall it is well-structured and informative.

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

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

Despite lacking an output schema, the description fully explains the return value (top-N relevant tools with names, descriptions, and schemas) and its role as a first-step discovery tool. This is complete and actionable 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% with all parameters described. The description adds meaningful examples ('look up FDA drug approvals', 'analyze housing market trends') and explains the query's natural language purpose, 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 explicitly states 'Find tools by describing the data or task' and lists numerous domains (SEC filings, FDA drugs, etc.), making the purpose unambiguous. It distinguishes from sibling search tools by focusing on tool discovery rather than data retrieval.

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

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

The description clearly advises 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It implies when not to use (when you need a single answer) but does not explicitly name alternative tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds context about data sources fanned out, sunset of USPTO PatentsView API (soft-fail), and return fields including 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?

Dense but well-structured: example queries first, then usage preference, then data sources and return fields. Every sentence adds value. Slightly long but justified by complexity.

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

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

Covers multiple data sources, limitations (USPTO sunset, name not supported), and return structure (cik, filings with URIs, fundamentals, patents, news, LEI). No output schema, but description adequately informs agent of return content.

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

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

Schema coverage is 100% with descriptions for both params. Description adds value with example patterns (ticker like 'AAPL' or CIK like '0000320193'), instruction not to use names, and reference to resolve_entity. Baseline 3, but extra context raises 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 uses specific verbs like 'research', 'brief me', 'profile' and clearly states it provides a full cross-source profile of a US public company. It distinguishes from sibling tools like resolve_entity (name resolution) and compare_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?

Explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' when user asks for holistic view. Also notes names not supported, advising to use resolve_entity first. Provides clear when-to-use 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?

Description states it deletes a memory, aligning with destructiveHint=true, but does not clarify behavior if key doesn't exist or if deletion is irreversible. Annotations are somewhat contradictory (destructive vs idempotent) but description does not address these nuances.

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 with no fluff: purpose first, then usage guidance. Every sentence adds value.

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

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

For a simple one-param tool with no output schema, description covers purpose, usage, and context. Could mention error handling but sufficient for selection.

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

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

Schema coverage is 100%, and description repeats that 'key' is the memory key to delete without adding new semantics, meeting baseline expectations.

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 'Delete a previously stored memory by key' with specific verb and resource, distinguishing from siblings like 'remember' and 'recall'.

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

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

Provides specific scenarios for use (stale context, task done, clear sensitive data) and mentions pairing with 'remember' and 'recall', though lacks explicit when-not guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint. The description adds behavioral context: fetches page, extracts title/description/links, emits standard markdown. No contradictions.

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

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

Two sentences with no wasted words. First sentence states action and audience, second explains process and output format. Front-loaded.

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

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

Given only 2 parameters and no output schema, the description is fully sufficient. It covers purpose, process, output, and 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?

Schema description coverage is 100%, so baseline is 3. The description does not add new parameter information beyond what's in the schema (e.g., default max_links is already in schema description).

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

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

The description uses specific verb 'generate' and resource 'llms.txt file', clearly distinguishing it from siblings like ai_visibility_check or scan_competitor_ai_presence. It states the purpose and target audience.

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 explicit use cases (getting client's site indexed, drafting for own project, auditing competitor), but does not explicitly state when not to use or suggest 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, idempotentHint, and destructiveHint, so the safety profile is clear. The description adds context that records include 'coordinates, dates, and sources,' but this is basic behavioral detail. 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 two concise sentences: the first defines the tool's purpose, and the second provides a practical filtering example. No redundant information, front-loaded, and every sentence adds value.

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

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

Given the tool's simplicity (3 parameters, no nested objects, output schema present), the description adequately covers purpose and key usage. Return values are explained by the output schema, so no need to elaborate further. Complete for the tool's complexity.

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

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

Schema coverage is 100%, so the input schema already documents all parameters (key, limit, country). The description reinforces the country filtering purpose with examples, but adds minimal additional meaning beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states 'Get georeferenced observation records for a species with coordinates, dates, and sources,' which is a specific verb-resource pair. It distinguishes from sibling tools like 'get_species' and 'search_species' by focusing on occurrence records.

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 filtering example ('Filter by country code'), indicating when to use the country parameter, but does not explicitly state when to use this tool versus alternatives or when not to use it. The usage guidance is implied rather than explicit.

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

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

Annotations already declare read-only and non-destructive behavior. Description adds that it returns all ranks and accepted name status, and requires a taxon key, augmenting the annotation information.

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

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

Two sentences: first states core function, second states prerequisite and return summary. No redundant information, highly efficient.

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

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

Tool has one required parameter, rich annotations, and output schema exists. Description covers purpose, prerequisite, and return summary, leaving no gaps for an agent to misinterpret.

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

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

Schema coverage is 100% with parameter description. The tool description adds value by explaining the key is from search_species, enhancing understanding beyond schema.

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

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

The description clearly states the tool retrieves complete taxonomic classification from kingdom through subspecies, and distinguishes itself from search_species by specifying it requires a taxon key from that sibling 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?

Explicitly mentions prerequisite: taxon key from search_species, and implies this tool is for retrieving full details rather than searching. Lacks explicit 'do not use when' but provides sufficient context.

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

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

Annotations already provide readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true. Description adds value by listing returned fields (id, type, params, etc.), enhancing transparency 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 sentences, front-loaded with core action, no redundant information. Every sentence earns its place.

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

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

Given the tool's simplicity (one optional param, no output schema), the description lists return fields adequately. Missing details like pagination or ordering, but not critical for a list tool with good annotations. Could be slightly more complete.

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

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

Schema coverage is 100% with one parameter (include_inactive) described. Description mentions 'active subscriptions' which relates to the parameter's default, but does not add significant meaning beyond the schema. 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?

Description clearly states 'List the caller's active subscriptions', specifying verb (list), resource (subscriptions), and scope (caller's active). This distinguishes it from sibling tools 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?

Explicitly says 'Use this to review what you're monitoring before adding more or to find an id to cancel', providing clear context and implying alternative actions. Could be improved by stating when not to use, but adequate.

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

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

Discloses key behavioral traits beyond annotations: rate-limited to 5 per identifier per day, free, doesn't count against quota, and team reads digests daily. No contradictions with annotations.

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

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

The description is a single, well-organized paragraph that front-loads the core purpose, then provides usage guidance and constraints. Every sentence is informative and earns its place.

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

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

Given the tool's complexity (3 parameters, nested objects, no output schema), the description covers all necessary aspects: feedback types, context usage, message format, rate limits, and how the feedback is processed.

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 significant meaning: explains the enum values (bug, feature, etc.), advises on message specificity, and clarifies the optional context structure.

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

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

The description states a specific verb-resource combination: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly differentiates from sibling tools like ask_pipeworx or discover_tools by focusing solely on feedback submission.

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 (bug, feature/data_gap, praise) and provides anti-patterns: 'don't paste the end-user's prompt.' The description also notes rate limits and that it's free, guiding appropriate use.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds value: explains data source (CF analytics-engine), privacy (no PII), and caching (5min-1h). No contradiction.

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

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

Description is concise (5 sentences), well-structured with numbered list for use cases. Front-loaded with main function. No redundant 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 read-only tool with one optional parameter and no output schema, the description covers purpose, usage guidance, data provenance, privacy, and caching. Complete without needing extra details.

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

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

Schema has 100% coverage for the single parameter 'window'. Description adds semantic guidance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This goes beyond the schema's enum description.

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

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

The description clearly states it returns top tools, top packs, and total call volume over a recent window. It distinguishes from sibling tools like 'discover_tools' by emphasizing that this is about what other AI agents are calling on Pipeworx right now, not generic discovery.

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

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

Explicitly lists three use cases (discovering hot data sources, confirming canonical choice, aligning use case). Provides clear context, though no explicit when-not-to-use or alternatives.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false) are consistent. Description adds extensive behavioral details: parameter requirements, monotonicity and partition checks, semantic anchor with Jaccard similarity, partition filter, fill check, and response structure. No contradictions.

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

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

The description is dense and informative, with every sentence contributing value. It is front-loaded with the requirement. Slightly verbose due to complexity, but justified; could be slightly more concise while retaining all detail.

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

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

Given the tool's complexity (two modes, multiple checks, fill interaction), the description covers all behavioral aspects, response structure, and links to sibling tools. No output schema is provided, but response fields are explained. Complete and self-sufficient.

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

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

Schema coverage is 100% with descriptions, but the description adds significant meaning: explains the difference between event and topic modes, provides examples, and gives usage guidance. It enriches understanding beyond the schema.

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

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

The description clearly states it finds arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes two modes (event and topic) with specific use cases and examples, differentiating it from siblings like polymarket_edges and polymarket_fill_risk.

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

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

Explicitly states requirement: one of event or topic, with failure message for no args. Provides clear guidance on when to use each mode (event recommended for specific market, topic for cross-event scanning) and mentions sibling polymarket_fill_risk for custom sizing.

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 extensive behavioral traits beyond the annotations. It explains caching ('Cached 1h at the KV level keyed on all knobs'), the algorithms behind each segment (e.g., 'lognormal barrier from 90d FRED log-returns', 'GDELT 7d/21d article-volume ratio'), and includes a 24h-move warning. It also details the response structure with diagnostics so callers understand why segments are empty. There is no contradiction with annotations (readOnlyHint, idempotentHint, 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?

The description is front-loaded with the core purpose but then includes a very detailed technical breakdown. While every sentence is informative, the length is considerable. It is well-structured with clear segmentation (FIVE MODEL FAMILIES, TRADEABLE-EDGE KNOBS, RESPONSE TOP-LEVEL), but could be slightly more concise without losing essential detail.

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

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

Given the tool's complexity (9 optional parameters, no output schema, no nested objects), the description is remarkably complete. It explains the three response segments, edge calculation formulas, fee and slippage assumptions, caching behavior, and diagnostics for empty results. It provides all necessary context for an AI agent to correctly invoke and interpret the tool.

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

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

Schema coverage is 100%, but the description adds significant meaning beyond the schema. For example, for 'slippage_pp' it explains the reasoning (Polymarket zero fees but bid/ask eats 20-50bp) and provides guidance on when to adjust. For 'min_partition_leg_kelly', it clarifies partition arbs' behavior and why min_kelly doesn't apply. Each parameter receives contextual usage advice that goes far beyond the schema's basic description.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' This is a specific verb+resource combination. It further distinguishes the tool by emphasizing it is built for 'what should I bet on today' and allows discovering opportunities without paging hundreds of markets, which differentiates it from sibling tools like polymarket_arbitrage.

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

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

The description provides explicit context for when to use this tool: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It also offers usage guidance on tradeable-edge knobs (min_liquidity, max_spread_pp) and explains that diagnostics show why a segment is empty. However, it does not explicitly mention when not to use the 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, openWorldHint, idempotentHint, and destructiveHint=false. The description adds value by detailing the return fields (tracked, expired, snapshot_dates) and explaining limits like the 60-day TTL and that decay comes from daily closes, not intraday. 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 comprehensive but somewhat lengthy. It is front-loaded with the key question it answers, and uses formatting (line breaks, underscores) to structure the output explanation. While every sentence adds value, it could be slightly more concise.

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

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

Given the complexity of the tool and absence of output schema, the description thoroughly explains the return structure: tracked[], expired[], snapshot_dates[] with field details and limits. This fully compensates for the missing output schema.

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

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

Schema coverage is 100% with descriptions. The description adds context by explaining 'window' as 'snapshot family' with default '1wk', and 'days' as lookback with clamp to 2-30 and default 14. This enriches the parameter meaning beyond the schema.

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

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

The description clearly states the tool's purpose: edge persistence and decay telemetry from daily snapshots. It distinguishes itself from sibling tool 'polymarket_edges' by focusing on historical trends rather than current edges, using the contrast between a fresh wide edge and a 3-week-old wide edge.

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 the tool by contrasting fresh vs aging edges, implying that it is for assessing edge persistence over time. It does not explicitly mention when not to use it or point to alternatives, but the context of sibling tools suggests 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=true, idempotentHint=true, and destructiveHint=false, so the description adds value by explaining the check behavior, return verdicts (clean|degraded|cannot_fill), and warning about partial basket fills converting arb to unhedged directional position. No contradiction.

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

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

The description is well-structured with clear section headers (SINGLE-MARKET, BASKET) and front-loads the purpose. However, it is somewhat verbose and includes detailed return field listings that could be shortened. Overall, it earns its length but could be more concise.

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

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

Given no output schema, the description thoroughly lists all return values (top_of_book, vwap_fill_price, slippage_pp, etc. for single-market; theoretical_sum, realizable_sum, capture_ratio, etc. for basket). It covers behavioral expectations, usage context, and risk factors, making it complete for a non-destructive check tool.

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

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

Schema coverage is 100% with descriptions for all 4 parameters, but the description adds extra context: explains the role of each parameter in the two modes, default values, and constraints (e.g., size_usd clamp 10–1,000,000). This goes beyond the schema alone.

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

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

The description clearly states it checks 'Realizable-vs-theoretical edge against live CLOB order-book depth', specifies two modes (single-market and basket), and explicitly differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by stating when to use this tool before acting on their signals.

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

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

The description explicitly states when to use the tool: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It also provides context on when not to use and explains risks (partial basket fills converting arb to unhedged directional position).

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 safety fields (compatibility_warning, temporal_alignment), explains skipped comparisons, and notes rarity of real spreads. Goes well beyond annotations, which already indicate read-only, idempotent, non-destructive. 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?

Dense but well-organized: starts with purpose, then two modes, then response format, then safety fields. Every sentence adds value. Could use bullet points for clarity but length is justified by complexity.

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

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

No output schema, but description fully explains response structure (leg prices, spreads, safety fields). Covers edge cases like temporal alignment and skipped comparisons. Comprehensive for a complex cross-venue comparison tool.

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

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

Schema covers 100% of parameters with descriptions. Tool description adds value by listing topic shortcuts, giving examples, and explaining how explicit parameters override topic. Adds meaningful context beyond schema.

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

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

Clearly states it computes cross-venue spread between Kalshi and Polymarket. Describes two modes (topic shortcuts and explicit tickers) and what the response includes, distinguishing it from sibling tools.

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

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

Explains when to use (comparing same resolving question across venues) and when not (when compatibility_warning or temporal misalignment). Warns that most pre-mapped topics are not tradeable. Could explicitly name alternatives like polymarket_arbitrage.

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 scoping detail (anonymous IP, BYO key hash, account ID) beyond annotations which already declare readOnlyHint and idempotentHint. 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?

Three sentences, each substantive: purpose, usage/scope, pairing. No waste.

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 retrieval tool with one optional parameter and no output schema, description covers return behavior (value or list), scoping, and related tools. Complete.

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

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

Schema coverage is 100% and description repeats schema's explanation of 'key' parameter (omit to list all). Adds no new meaning but is clear.

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?

States specific verb 'Retrieve' and resource 'value previously saved via remember' or 'list all saved keys'. Clearly distinguishes from siblings 'remember' and 'forget' by mentioning pairing.

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

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

Explicitly says 'Use to look up context the agent stored earlier' with concrete examples (ticker, address, research notes). Mentions scoping and pairing with remember/forget.

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 states that setting mark_read:true flags returned events as read, which implies a state change. However, annotations include idempotentHint=true and destructiveHint=false, suggesting no side effects. This contradiction could mislead the AI agent about the tool's idempotency and side effects.

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

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

The description is concise (4 sentences), front-loads the purpose, and each sentence adds value: purpose, data contents, filter/mark_read options, and alternative access. No unnecessary words.

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

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

Given the simple nature of the tool (read, optional filters, no output schema), the description covers key aspects: what is returned, filter options, mark_read behavior, and polling suitability. The contradiction slightly reduces completeness but does not omit critical information.

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

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

Input schema has 100% coverage with descriptions for all 5 parameters. The description adds extra context, such as the effect of mark_read on future calls and the ability to filter by type and since, exceeding the schema's detail.

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: 'Pull fired events from your subscription feed.' It specifies the action (pull), resource (subscription feed), and the nature of data returned (recent alerts). This is distinct from sibling tools like list_subscriptions or subscribe.

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

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

The description provides guidance on when to use (polls work fine) and mentions an alternative access method (GET endpoint for scripts/dashboards). It does not explicitly compare to sibling tools but gives sufficient context for typical use cases.

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

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

The description adds significant behavioral context beyond the annotations. It details the fan-out behavior to multiple sources, fallback from GDELT to GNews when rate-limited or 5xx, the USPTO soft-fail due to API sunset, and the return structure including changes grouped by source, total_changes count, and pipeworx:// citation URIs. The annotations (readOnlyHint, openWorldHint, idempotentHint) are confirmed and complemented.

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

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

The description is concise yet comprehensive, with examples front-loaded for easy query matching. Every sentence adds value—explaining sources, fallbacks, parameter usage, and tool differentiation—without redundancy or filler.

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

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

Despite lacking an output schema, the description fully explains the return structure: changes grouped by source, total_changes count, and citation URIs. It also covers edge cases like GDELT/GNews fallback and USPTO soft-fail. For a complex tool with multiple data sources, the description is complete and leaves no gaps.

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

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

Although the schema already covers all three parameters with descriptions, the tool description adds practical guidance: it explains that type is only 'company', gives examples for since (ISO date and relative shorthand like '30d', '1m'), and clarifies value can be ticker or CIK. It also suggests typical monitoring values like '30d' or '1m'.

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

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

The description explicitly states the tool's purpose as a change feed for a company, fanning out to SEC, GDELT/GNews, and USPTO. It distinguishes from the sibling entity_profile tool by specifying that recent_changes is for dynamic updates over a time window, while entity_profile is for static profiles.

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

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

The description provides clear usage scenarios with example queries like "What's new with X" and "latest on Y", and explicitly advises to use entity_profile instead when a static profile is needed regardless of window. This leaves no ambiguity about when to use which tool.

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

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

Annotations provide idempotentHint=true, readOnlyHint=false. Description adds key details: scoped by identifier, 24-hour retention for anonymous, persistent for authenticated. No contradiction. Could mention overwrite behavior for same key, but acceptable.

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

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

Four sentences, front-loaded with purpose, followed by usage and details. No redundant words. Every sentence serves a clear purpose, earning a top score.

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

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

No output schema, but description explains effect (stored key-value). Covers persistence duration, pairing with recall/forget. Sufficient for a simple storage tool. No gaps for intended use.

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

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

Schema covers 100% of parameters with descriptions. Description adds concrete examples ('subject_property', 'target_ticker') and clarifies value is any text. Adds value beyond schema, justifying above baseline 3.

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

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

Description clearly states 'Save data the agent will need to reuse later' and specifies key-value storage. Explicitly distinguishes from sibling tools 'recall' and 'forget' by mentioning them as pairs, fulfilling the specific verb+resource+scope criteria.

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?

Describes when to use: 'when you discover something worth carrying forward'. Notes persistence differences between authenticated and anonymous sessions. Mentions pairing with recall and forget. Lacks explicit when-not-to-use but covers key context.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds valuable context: each call cascades through multiple internal endpoints, and the output includes specific citation URIs. No contradictions with annotations.

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

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

The description is informative but slightly verbose, covering examples, purpose, type details, and internal behavior. While every sentence adds value, it could be tightened to improve readability without losing information.

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

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

Despite lacking an output schema, the description details the return values for both entity types, including citation URIs. It also explains the cascading internal logic. It does not cover error handling or rate limits, but for a lookup tool this is sufficiently complete.

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

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

Schema coverage is 100%, and the description adds practical meaning beyond the schema by showing example inputs for each type (e.g., ticker, CIK, name for company; brand or generic for drug) and specifying the exact return fields (ticker, CIK, company_name, citation URI for company; RxCUI, ingredient, brand, citation for drug).

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

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

The description clearly states the tool resolves user-spoken names to canonical IDs, with explicit examples of queries and supported entity types (company, drug). It distinguishes itself from siblings by emphasizing 'Use FIRST whenever you have a name but need an ID' and noting it replaces multiple manual lookups.

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

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

The description provides explicit usage guidance ('Use FIRST whenever you have a name but need an ID') and explains the supported types and input formats. It does not explicitly mention when to avoid using it versus specific sibling tools, but the directive is strong enough for correct 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 read-only, idempotent, non-destructive. The description adds that it internally calls ai_visibility_check multiple times and what the output contains (ranked list with score, confidence, signal density). This provides useful behavioral context 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?

The description is three sentences: action, mechanism+output, use case. It is front-loaded, every sentence adds unique value, and there is no redundancy. Perfectly concise for a tool with 4 parameters.

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 moderately complex (multiple entities, optional models, API key). The description covers purpose, internal mechanism, output format, and a use case. It does not detail error handling or output schema (none exists), but the mentioned fields are sufficient. Minor gap: could mention that the tool makes N calls to ai_visibility_check.

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 extra meaning: 'First entry treated as the subject for narrative; rest are competitors,' which is not in the schema description for entities. It also clarifies the default model and API key requirement, adding value beyond the structured schema.

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

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

The description clearly states the verb ('compare'), the resource ('AI visibility'), and the specific action ('probes each entity with ai_visibility_check, ranks by score'). It distinguishes itself from sibling tools like ai_visibility_check (single entity) by focusing on side-by-side comparison and ranking.

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

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

The description gives a concrete use case ('competitive AI-marketing audits' and the example question). It implies when to use, but does not explicitly state when not to use or mention alternatives beyond referencing ai_visibility_check. Still, the context is clear.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description discloses that bundlephobia's first measurement can take 5-30 seconds, and that partial failures degrade gracefully with sources_failed listing timeouts. No contradiction with annotations.

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

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

The description is fairly concise for the amount of information conveyed, but it is a bit long. It is front-loaded with the core purpose and structure, earning a 4.

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

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

The description covers return fields, behavior on partial failures, and ecosystem scope. Without an output schema, it provides sufficient detail for the agent to understand what to expect.

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

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

Schema coverage is 100% and parameters are well-described. The description adds context like scoped packages being accepted and default version behavior, but does not add significant new meaning beyond the schema.

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

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

The description clearly states the tool performs a composite check across multiple sources for npm packages, addressing questions about safety, popularity, and size. It distinguishes itself from siblings by focusing on npm ecosystem and aggregating multiple data 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 says to use when an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me'. It also notes that v1 is NPM only and refers to deps.dev for other ecosystems, providing clear context.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, indicating safe, read-only behavior. The description adds that it returns 'matched taxa with rank, classification status, and taxonomic hierarchy,' which is return content but not additional behavioral traits. The description adds marginal value beyond annotations.

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

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

The description is two efficient sentences: first states purpose and return content, second provides guidance to use get_species for details. No wasted words, front-loaded with key information.

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

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

The tool has a simple interface with 2 parameters and an output schema (present but not shown). The description explains the return types (matched taxa with rank, etc.). It does not mention pagination or error handling, but with an output schema present, these may be covered. Overall, it is sufficiently complete for the tool's purpose.

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

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

Schema coverage is 100%, with both parameters well-described in the schema: query (species name or keyword) and limit (max results 1-100, default 20). The description does not add any additional meaning or context for the parameters beyond what is already in the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Search for species by common or scientific name.' It specifies that returns matched taxa with rank, classification status, and taxonomic hierarchy. It also distinguishes from get_species by suggesting using that for full details, which differentiates it from a sibling tool.

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

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

The description provides clear guidance on when to use this tool versus get_species: 'Use get_species with the taxon key for full details.' This implies that search_species is for initial discovery. It does not explicitly exclude other contexts or mention when not to use, but the guidance is sufficient.

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

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

Discloses technical details beyond annotations: uses BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation and flagging. No contradiction with annotations (all readOnly, idempotent, etc.).

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 well-structured: primary function, usage guidance, technical details. Every sentence is informative, no fluff. Front-loaded with key information.

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

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

Covers purpose, use cases, alternatives, technical mechanism, output features (offsets, similarity scores), and constraints. No output schema, but description sufficiently explains return values.

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

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

Schema coverage is 100%, baseline 3. Description adds value: gives examples for query and text, mentions truncation behavior for text, provides default and range for limit. Slightly better than baseline.

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

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

The description clearly states 'Semantic search INSIDE a fetched record' and provides concrete examples like SEC 10-K body and article. It distinguishes itself from siblings by mentioning pairing with ask_pipeworx_grounded and emphasizing internal search.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and contrasts with ask_pipeworx_grounded as an alternative for grounding. Provides clear context and when-not-to-use guidance.

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

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

The description discloses behavioral traits beyond annotations: OAuth requirement, webhook signing secret returned once, SMS 10/day cap, webhook auto-disabled after 10 failures. No contradiction with annotations (idempotentHint is plausible if parameters uniquely identify a subscription, though not explicit).

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

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

The description is well-structured and front-loaded with the core purpose. It includes all necessary details without being overly verbose, though could be slightly more concise by removing redundant phrases.

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

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

Given the complexity and no output schema, the description covers all inputs, return value (new subscription ID), constraints, and delivery nuances, making it fully self-contained for an AI agent to use correctly.

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

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

With 100% schema coverage, the description adds significant value beyond the schema: detailed examples for each type, constraints on delivery channels (phone verification, webhook HTTPS only), and on-time secret delivery info.

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 a new subscription ID, with specific verb and resource. It distinguishes from sibling tools like list_subscriptions and unsubscribe by focusing on creation.

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

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

It provides explicit requirements (Pipeworx OAuth account) and context for when to use (persistent subscriptions). It also details delivery channels and limitations but does not explicitly compare to alternatives like ask_pipeworx or recent_alerts.

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, non-destructive, idempotent. The description adds that it returns category-bucketed example questions with exact tool+argument shape, drawn from live catalog. This complements annotations without contradiction.

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

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

The description is a single paragraph with targeted information, listing categories and explaining use. It is slightly verbose but every sentence adds value. Could be more concise 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?

Given no output schema, the description adequately explains what is returned (category-bucketed examples with tool+argument shape). It also places the tool in the context of sibling tools as the onboarding entry point. Complete for its purpose.

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

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

Schema coverage is 100% with a clear description of the 'topic' parameter (optional, focus area list). The description adds value by clarifying behavior: omit for full spread, pass specific topic to narrow. This goes beyond the schema's enum-like list.

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: onboarding entry point to show what Pipeworx can do, listing example questions across categories. It explicitly distinguishes from sibling tools by recommending use 'FIRST when you do not yet know what Pipeworx can do' and mentions meta-tools.

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

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

The description provides explicit when-to-use guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. It also explains parameter usage: call with no arguments for full spread, or pass topic to focus.

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

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

The description adds significant behavioral context beyond annotations: it clarifies that the row is deactivated (not deleted), preserving historical events via recent_alerts. This aligns with the `destructiveHint: false` annotation.

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

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

Two concise sentences, front-loaded with the core action and key constraints. Every part of the description is necessary and 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 tool with one parameter, no output schema, and clear annotations, the description is complete. It covers purpose, ownership rule, behavioral impact, and side effects (historical data retention).

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 schema already describes the parameter as 'Subscription id (uuid) returned by subscribe.' The description does not add further semantic detail, so it meets the baseline but does not exceed it.

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 identifies the verb ('Cancel') and resource ('subscription by id'), with specific details that distinguish it from siblings like 'subscribe' and 'list_subscriptions', such as ownership enforcement and soft-delete behavior.

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 the ownership constraint ('you can only cancel your own subscriptions'), which guides when to use the tool. While no alternatives are named, the context is clear and sufficient for decision-making.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds detailed output format (verdicts, citation, delta) and explains it consolidates multiple calls, providing rich 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 long but well-structured: opens with user-facing phrases, states purpose, scopes domain, lists output. Each sentence adds information; however, could be slightly more concise.

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

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

Given the tool's complexity and single parameter, the description fully covers how to invoke it, what it returns, and its domain. No output schema exists, but the description details the verdict types and citation, making it self-sufficient.

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

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

Schema coverage is 100% with a clear description. The description supplements with natural-language examples ('Apple's FY2024 revenue was $400 billion') that clarify the expected input format, adding value beyond the schema.

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

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

The description uses explicit natural-language patterns like 'Is it true that…' and clearly states the tool verifies claims. It distinguishes itself by noting it replaces multiple sequential calls, making the purpose 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?

Directly states 'Use whenever the agent needs to check whether something a user said is factually correct.' Also explicitly scopes to company-financial claims and indicates the supported sources, providing clear when-to-use and limitations.

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