exchangerate

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds significant behavioral details: it probes multiple models, returns per-model score/confidence/signals/raw_response plus combined view, explains API key pass-through and billing, and defaults to Workers AI Llama-3.3-70b. 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 a single well-structured paragraph. It front-loads the main action and then provides details, including model options, return format, and use cases. Every sentence is informative with no redundancy.

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

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

Given four parameters (all described), comprehensive annotations, and no output schema but clear description of return format, the description is fully complete. It covers input, behavior, output, and use cases adequately.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by explaining default model behavior, API key purpose, and output structure (per-model + combined view). This goes beyond 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 probes LLMs for knowledge about an entity and scores visibility (0-100). It specifies the verb 'probe' and the resource 'visibility of a business/brand/product/topic'. The purpose is distinct from sibling 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 explicit context for use: AI-marketing audits, pre-launch brand checks, competitive monitoring. It explains when to use default model vs Anthropic (BYO key) and that anthropic requires _apiKey. However, it does not explicitly exclude scenarios or compare to siblings.

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

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

Annotations already indicate readOnly, idempotent, openWorld. The description adds behavioral context: routes to one of 3,745 tools across 884 sources, returns structured answers with pipeworx:// citation URIs, and handles argument filling. No contradiction with annotations.

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

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

The description is front-loaded with the key preference instruction, followed by supporting details and examples. While slightly long, every sentence adds value and the structure is logical.

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 explains the return format (structured answer with citations). All 6 parameters are fully described in schema, and the tool's purpose and usage are thoroughly covered. Sibling tools are listed for 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?

Input schema has 100% coverage, fully documenting the single required parameter and its aliases. The description does not add parameter info beyond the schema, so baseline score of 3 is appropriate.

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

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

The description clearly states the tool answers factual questions about current/historical data from authoritative sources (SEC, FDA, etc.), provides a verb ('ask'), and explicitly differentiates from web search, which distinguishes 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?

Explicitly says 'PREFER OVER WEB SEARCH' and lists specific when-to-use scenarios (e.g., 'what is', 'look up', 'find') with concrete examples, providing clear guidance on when to use this tool instead of 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?

Discloses beyond annotations: explains hallucination resistance, refusal mechanism with specific reasons, and cost of extra LLM call. No contradiction with annotations.

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

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

Single paragraph front-loaded with purpose, then process, output format, and usage guidelines. No fluff; every sentence adds value.

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

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

Given no output schema, description fully specifies return fields (answer, evidence, confidence, source, etc.) and refusal reasons. Provides complete context for usage and behavior.

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

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

Schema coverage is 100% with all six parameters being aliases for the same question parameter, each described. Description adds little beyond schema, but that's acceptable. 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 it's a hallucination-resistant answer mode for high-stakes reads, explains the process (routing, fetching, extracting), and specifies return format with success and refusal cases. Distinguishes from sibling ask_pipeworx by noting extra LLM call and use case.

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

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

Explicitly tells when to use (high-stakes reads, must not invent facts) and when to prefer ask_pipeworx (casual lookups). Provides examples of use cases like financial verdicts, legal claims.

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. Description adds extensive behavioral context: resolver contract (match confidence, alternatives, suggestions), parent event extractor, news fallback mechanisms, safety short-circuits (low_confidence_match, market_closed_or_inactive), illiquid spread handling, and cancellation rule parsing—all 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?

Long but well-structured with clear sections (purpose, classifiers, fan-out, response shapes, resolver, etc.). Front-loaded with main action. Some redundancy (e.g., repeating classifiers), but verbosity is justified by the tool's complexity. A tighter description could be achieved, but not at the cost of clarity.

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

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

Despite no output schema, the description thoroughly explains return fields (result.market, analysis, evidence, market_match_confidence, parent_event, news fields with errors) and safety mechanisms. Covers edge cases like low-confidence matches, closed markets, and wide spreads. An agent can fully understand the response structure and potential pitfalls.

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 meaning beyond schema: explains market input types (slug, URL, question text), depth options with examples, and include_raw usage scenarios. The description compensates for any brevity in 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 researches a Polymarket bet by pulling Pipeworx data in one call. It specifies the verb ('research'), the resource ('Polymarket bet via Pipeworx data'), and scope. It distinguishes from siblings like polymarket_edges or validate_claim by focusing on comprehensive data gathering for a single bet.

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

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

Explicit usage scenarios: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. Fan-out examples illustrate context. No explicit when-not-to-use, but the clear purpose and examples implicitly guide 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 indicate read-only, idempotent, and open-world. The description adds behavioral context: single parallel call, correct handling of off-calendar fiscal years, sorting by primary metric, and return of citation URIs. This goes beyond 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 well-structured with examples first, then behavior details. It is slightly verbose but every sentence adds value. No redundancy.

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

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

For a complex tool with two entity types and multiple data sources, the description is thorough: it explains data pulled, sorting, return format (paired data + URIs), and efficiency benefit. No output schema, but the description adequately covers return information.

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

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

Schema coverage is 100%, but the description adds significant meaning: explains type enum values (company/drug) with specific data sources (10-K, FAERS), clarifies value format (tickers/CIKs or drug names), and notes sorting behavior. This adds value beyond the schema.

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

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

The description clearly states the tool's purpose: side-by-side comparison of 2-5 companies or drugs in one parallel call. It uses specific verbs and examples, and distinguishes from siblings like entity_profile by emphasizing it replaces multiple sequential lookups.

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

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

The description explicitly advises to prefer this tool over sequential lookups for comparisons, and provides example queries and entity types. It lacks explicit exclusions (e.g., when not to use) but the context of comparison vs single entity is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds concrete behavioral details: decomposition into sub-questions, parallel routing, verbatim evidence extraction, confidence scores, sources, gaps array, and never-invented policy. Also discloses expected time (15-60s) and plan requirements.

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

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

Description is detailed but well-structured: purpose first, then mechanism, usage, prerequisites, and timing. Every sentence adds value, though slightly longer than necessary for a simple tool.

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

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

Given no output schema, description compensates by describing the structured findings packet (evidence, confidence, source, fetched_at, pipeworx:// citation, gaps[]). Covers all key aspects: input, process, output, limitations, prerequisites, and timing.

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

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

Schema coverage is 100% with descriptions for both parameters. Description adds clarity by specifying depth's enum values (quick=3, standard=5, thorough=8) and confirming that broad questions are acceptable. Provides more context than 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?

States 'Grounded multi-source research in ONE call' with specific verb (decomposes, routes, extracts) and resource (3,745 tools across 884 sources). Distinguishes from sibling ask_pipeworx by noting it's for broad/multi-part questions.

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

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

Explicitly says 'Use for broad or multi-part questions' and contrasts with ask_pipeworx for single lookups. Also mentions prerequisite (Pipeworx account) and paid plan for 'thorough' depth.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, establishing safety. The description adds valuable behavioral context by stating each result is 'ready to call directly, no second schema lookup needed,' enhancing transparency beyond annotations.

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

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

The description is concise yet comprehensive, front-loading purpose and examples, then usage guidance. Every sentence adds value without redundancy, achieving maximum efficiency.

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 discovery purpose, the description fully explains what it returns (top-N tools with schemas and examples) and when to use it. Despite no output schema, the description sufficiently covers output nature, making it complete for effective agent use.

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

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

With 100% schema description coverage, the schema already documents all parameters. The description adds value by reinforcing alias options (task, q, search, description) and providing natural language examples, plus mentioning default and max limit values.

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 finds tools by describing data or task, listing numerous domains. It explicitly distinguishes itself from siblings by advising 'Call this FIRST when you have many tools available and want to see the option set,' making its unique 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?

The description provides explicit when-to-use guidance: 'when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST... not just one answer.' It includes multiple examples, giving clear context for appropriate usage.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds context: data sources, specific return fields (cik, filings with URIs, fundamentals sorted by period_end, patents with sunset note, news via GDELT→GNews fallback, LEI via GLEIF). No contradictions.

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

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

The description is lengthy but front-loaded with example queries. Every sentence adds value (data sources, limitations, return format). Could be slightly more concise, but the density of information justifies the length.

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

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

Despite no output schema, the description fully explains return values (cik, company_name, filings, fundamentals, patents, news, LEI) and limitations (names not supported, patent API sunset). It is complete for a holistic profile 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%, so baseline is 3. The description reiterates that type is only 'company' and value is ticker or CIK, but doesn't add significant meaning beyond the schema. It does clarify that names are not supported, which is slightly helpful.

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 ('profile', 'brief me', 'give me the rundown') and clearly identifies the resource: a US public company. It lists exact data sources (SEC EDGAR, XBRL, USPTO, news, GLEIF) and distinguishes itself from sibling tools like resolve_entity by stating name support limitations.

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 chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' Also tells when to use a sibling (resolve_entity) if only a name is available, providing clear when-to-use and when-not-to-use guidance.

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

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

The description adds context beyond annotations by explaining when deletion is appropriate, while annotations already indicate destructive behavior. No contradictions.

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

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

Three efficient sentences, front-loaded with the primary action, no redundancy.

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

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

Fully covers the tool's purpose, usage guidance, and relationship to siblings, given the simple schema and annotations.

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

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

Schema coverage is 100% with a clear description for 'key', so the description adds minimal extra value for the parameter, meeting the baseline.

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

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

The description clearly states 'Delete a previously stored memory by key', specifying the verb and resource, and distinguishes from siblings by mentioning 'Pair with 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?

Explicit usage conditions are given: 'Use when context is stale, the task is done, or you want to clear sensitive data', and pairing with siblings is noted.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive. Description adds that it fetches the page, extracts title/description/key links, and outputs markdown. No contradictions.

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

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

Three sentences, no redundant words, front-loaded with purpose, efficient and clear.

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

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

Given simple tool with full schema coverage and rich annotations, description fully explains action, output, and use cases. Output schema absent but output format explicitly described.

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 description adds minimal value beyond schema. Description does not elaborate on 'max_links' default or constraints beyond what schema provides.

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

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

Description clearly states the tool generates an llms.txt file for a URL, specifies the format and use cases. It distinguishes itself from siblings like 'scan_competitor_ai_presence' by focusing on file generation rather than analysis.

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

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

Explicitly lists three use cases (client indexing, personal project drafting, competitor auditing), but does not mention when not to use it or directly compare to sibling tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. Description adds 'current exchange rate' and 'returns conversion rate', aligning with annotations. No contradictions, but little extra 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?

Two concise sentences, front-loaded with purpose, includes example and usage guidance. 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 simple tool with 2 parameters, comprehensive annotations, and output schema (implied), the description is complete enough for correct selection and invocation.

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

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

Schema coverage is 100%, so baseline 3. Description provides example currencies but no additional meaning beyond schema's parameter descriptions and examples.

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

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

Description uses specific verb 'Get' and resource 'exchange rate', gives concrete example 'USD to EUR', and distinguishes from sibling 'get_rates' by stating 'single currency pair lookups'.

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

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

Explicitly states 'Use for single currency pair lookups', implying when to use and that alternatives like 'get_rates' exist for multiple pairs.

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 context about returning 'conversion rates for all major currencies', which aligns with annotations and clarifies the output scope.

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

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

The description is two sentences, concise and front-loaded with the main action. Every word 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?

The tool is simple (one parameter, read-only). An output schema exists, so return values need not be described. The description adequately covers purpose, usage hint, and parameter, making it complete for this tool.

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

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

The input schema covers the parameter fully (100% coverage). The description repeats the examples from the schema, adding no significant new information beyond what the schema already provides.

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

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

The description clearly states the tool gets current exchange rates for a base currency, with specific examples ('USD', 'EUR'). It distinguishes from siblings as no other sibling appears to provide exchange rates.

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 use case ('Use when you need multiple rates at once'), which helps the agent decide when to invoke it. However, it does not explicitly mention when not to use it or reference alternatives.

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

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

Annotations already declare readOnlyHint true, destructiveHint false. The description adds behavioral details such as scoping to the caller's subscriptions and listing specific return fields, which is useful beyond annotations.

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

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

Three sentences covering purpose, return fields, and usage guidance. Each sentence adds value with no redundancy. Front-loaded with the core action.

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

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

For a simple read-only list tool with one optional parameter and no output schema, the description is complete: it explains what is returned and when to use it. No essential information is missing.

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

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

Schema coverage is 100% with the 'include_inactive' parameter well-described. The description adds no extra parameter details, which is acceptable given high coverage; baseline 3 is appropriate.

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

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

The description clearly states the verb 'list' and the resource 'subscriptions', specifies 'active subscriptions' and return fields. It distinguishes from sibling tools like 'subscribe' and 'unsubscribe' by being the listing counterpart.

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 provides usage context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This tells the agent when to invoke it and implies alternatives for actions.

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

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

Beyond the annotations (which already indicate this is not read-only or destructive), the description adds key behavioral traits: rate-limited to 5 per identifier per day, free, and does not count against tool-call quota. This fully informs the agent of constraints 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 a single paragraph that efficiently conveys purpose, usage guidance, behavioral notes, and constraints. While densely packed, it is clear and front-loaded with the key verb 'Tell'. Every sentence adds value, though a slightly more structured format could improve readability.

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

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

Given the tool's simplicity (no output schema, few parameters), the description covers all needed aspects: when to use, how to format feedback, behavioral constraints, and quota info. It is fully sufficient for an agent to correctly invoke this tool.

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

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

The input schema covers all three parameters with full descriptions (100% coverage), meeting the baseline. The description adds additional context on how to frame feedback (e.g., in terms of tools/packs), which enriches understanding beyond the schema alone.

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

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

The description clearly states the tool is for sending feedback to the Pipeworx team about bugs, missing features, praise, etc. It distinguishes this tool from all sibling tools, none of which are feedback-related, making its purpose unique and well-defined.

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

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

The description provides explicit when-to-use guidance for each feedback type (bug, feature/data_gap, praise) and specific instructions (e.g., don't paste the end-user prompt). It also notes rate limits and that the tool is free, offering comprehensive usage context.

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

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

Adds significant behavioral context beyond annotations: explains data source (CF analytics-engine), no PII, caching policy (5min-1h), and that it is self-aggregating. Annotations already indicate safe read operation, but description enriches understanding.

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

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

Four concise sentences. First sentence front-loads the core return value. Each subsequent sentence adds valuable information without redundancy or wordiness.

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, strong annotations), the description fully covers purpose, use cases, data source, caching, and privacy. No gaps remain.

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

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

Schema has 100% coverage with enum and description for 'window'. Description adds nuance: shorter windows show hot trends, longer windows show steady-state demand, providing extra 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?

Description clearly states the tool returns top tools, packs, and call volume over a time window. It provides specific use cases (discovering hot data, confirming canonical choice, aligning use case), distinguishing it from siblings like discover_tools or ask_pipeworx.

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?

Three explicit use cases are given, clarifying when to use the tool. However, no explicit when-not-to-use or alternative tool names are mentioned, so slightly less than perfect.

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 state readOnly, openWorld, idempotent, non-destructive. The description adds extensive behavioral context: parameter requirements, semantic anchor filtering (≥0.30 Jaccard), partition filter, fill check using live CLOB depth, and response structure. No contradiction with annotations. The description significantly enriches the agent's understanding beyond the annotated properties.

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

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

The description is long and dense, burying key info in paragraphs. While structured logically, it could be more concise and better front-loaded. For example, the fill check details could be summarized.

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

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

The tool has no output schema, so the description fully bears the burden of explaining outputs. It clearly describes the response shape (opportunities[], partition_check, fill_check), including conditions like realizable_edge_pp ≤ 0 meaning untradable. The description covers all major behavioral aspects and edge cases, making it highly complete for a complex tool.

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

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

Schema description coverage is 100%, but the tool description adds practical value: it explains the difference between event mode and topic mode, provides example slugs and seed questions, and recommends one mode over the other. This goes beyond the schema's basic descriptions.

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

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

The description clearly states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks, distinguishing two modes (event and topic). It is specific and resource-oriented, but could be more concise. It somewhat distinguishes from siblings, though not explicitly.

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

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

The description provides explicit guidance on when to use each parameter ('use event for a specific market', 'use topic for cross-event scanning') and warns that calling without arguments fails. It also explains when not to trade and directs to polymarket_fill_risk for custom sizing. However, it does not directly compare against sibling tools like polymarket_edges.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is clear. The description adds extensive behavioral context: caching behavior ('Cached 1h at KV level'), internal segmentation ('by_segment'), edge calculation details, tradeable-edge knobs, and diagnostic output. Nothing contradicts 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: it starts with the core purpose, then details each segment, edge metrics, tradeable-edge knobs, and response structure. Every sentence adds value. However, it could be slightly more concise to improve scanning.

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

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

Given the complexity (9 parameters, no output schema, multiple segments), the description is extremely thorough. It explains the response format, caching, diagnostic info, and edge calculations. It fully equips an agent to understand what the tool returns and how knobs affect results.

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

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

All 9 parameters have schema descriptions (100% coverage), so baseline is 3. The description goes beyond schema by explaining the purpose of tradeable-edge knobs (e.g., 'min_liquidity drops opportunities where edge isn't realizable') and providing usage guidance for parameters like slippage_pp ('Polymarket has zero trading fees... but bid/ask + thin depth typically eats 20-50bp').

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 ('scan') and resource ('top Polymarket markets') with a clear outcome ('return opportunities where Pipeworx data disagrees with market price'). It is tailored for a use case ('what should I bet on today'). However, it does not explicitly distinguish from the sibling tool 'polymarket_arbitrage', which might have overlapping functionality.

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

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

The description explicitly says 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets', providing clear context for when to use this tool. It lacks explicit 'when not to use' or alternative names, but the use case is strong.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds substantial behavioral context: snapshot-based reads, gap handling, TTL limits, and decay computation logic, all consistent 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 detailed and front-loaded with the core purpose, but the response structure (tracked[], expired[], etc.) could be more concisely formatted (e.g., bullet points). Still, it is not overly verbose given the tool's complexity.

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

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

Given the tool's complexity (historical tracking with computed trends) and lack of output schema, the description thoroughly explains the response fields, limitations, and snapshot behavior, making it complete for agent usage.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining defaults, clamping, and snapshot behavior beyond the schema descriptions, leading to a higher score.

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

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

The description clearly states it provides 'edge persistence and decay telemetry' from daily snapshots, answering a specific question about edge age and trends. It differentiates from siblings like polymarket_edges by focusing on historical tracking rather than current edges.

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

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

The description implies usage for historical edge analysis but does not explicitly state when not to use it or provide direct comparisons to sibling tools like polymarket_edges. The context is clear but lacks explicit exclusions.

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

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

Annotations already declare readOnlyHint=true, so no contradiction. Description adds detailed behavioral context: walks the order book ladder, returns specific metrics (top_of_book, vwap_fill_price, slippage_pp, etc.), and warns about forced directional risk. Could mention rate limits or data freshness, but overall transparent.

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

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

Well-structured with clear sections (REQUIRES, SINGLE-MARKET, BASKET, usage guidance) and front-loaded with core purpose. Some redundancy with schema descriptions (e.g., side defaults), but every sentence adds value. Could be slightly more concise but still efficient for the complexity.

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

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

With no output schema, the description thoroughly enumerates return fields for both modes (top_of_book, vwap_fill_price, slippage, shares_filled, etc.) and explains edge cases (thin_legs, forced_directional_risk). It covers all required context for an agent to understand inputs, outputs, and failure modes.

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

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

Schema coverage is 100%, so baseline is 3. Description adds significant meaning beyond schema: explains single-market vs basket mode details, default side logic for basket, how size_usd is interpreted in both modes (max spend vs target proceeds vs settlement notional). This adds clarity beyond basic parameter descriptions.

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

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

The description clearly states the tool performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth', with specific verb ('check') and resource ('Polymarket CLOB'). It distinguishes single-market and basket modes, differentiating it from siblings like polymarket_arbitrage and polymarket_edges.

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

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

Explicitly states when to use this tool: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It warns against using it after theoretical edges are computed and explains why alternative approaches fail (thin books, partial fills).

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 behavior beyond annotations: modes, response structure (leg prices, top_spreads_pp), safety fields (compatibility_warning, temporal_alignment, skipped counters). Aligns with readOnlyHint, openWorldHint, and idempotentHint 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?

Thorough but slightly lengthy; every sentence adds value, and the structure is logical (purpose, modes, response details, safety fields). Could be slightly tighter but still effective.

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

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

Despite no output schema, the description comprehensively covers return fields (leg prices, top_spreads_pp) and edge cases (compatibility warnings, temporal misalignment, skipped cross types), making it complete 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?

100% schema coverage with parameter descriptions, but the tool description adds significant context by explaining the two modes, how parameters interact (overrides), and the list of pre-mapped topics.

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: computing cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes from sibling tools like polymarket_arbitrage by emphasizing the dual-venue nature and specific modes.

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

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

Provides explicit guidance on two usage modes (topic shortcuts vs explicit tickers), includes warnings about compatibility (matched_pairs, temporal alignment), and advises that pre-mapped topics are not necessarily tradeable.

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

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

Annotations already declare readOnly, idempotent, non-destructive. Description adds useful context about scoping (by identifier) and pairing with remember/forget, but doesn't detail return format or failure modes.

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 with clear purpose. Front-loaded with main action. No filler.

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

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

Given single parameter, no output schema, and annotations that cover safety, the description fully and efficiently covers what an agent needs to know: how to recall vs list, scope, and pairing with sibling tools.

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

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

Parameter schema has full coverage (100%) and clear description. Description adds value by explaining behavior when key is omitted ('omit to list all keys'), going beyond schema.

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

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

Description clearly states the tool retrieves a saved value or lists keys, and distinguishes from siblings remember and forget by explicitly naming them.

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

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

Explicitly tells when to use: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' Also explains scoping and pairing with siblings.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds behavioral details beyond annotations, such as the effect of setting mark_read:true to flag events as read, and that polling is safe. 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 concise, with three sentences that front-load the core purpose. Each sentence adds distinct value: purpose, key fields, filtering and mark_read behavior, and an alternative access method. No unnecessary 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?

Given the absence of an output schema, the description adequately covers return fields (source, citation_uri, raw event payload) and the mark_read behavior. The unread_only parameter is not explained in the description but is fully described in the schema. Overall, it provides sufficient context for a read tool with five optional parameters.

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

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

Schema coverage is 100% with descriptive parameter names and descriptions. The description adds meaning by providing examples (e.g., 'sec_8k' for type, ISO timestamp for since) and explaining the behavior of mark_read, which supplements 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 pulls fired events from a subscription feed, using a specific verb ('Pull') and resource ('fired events'). It distinguishes itself from sibling tools like list_subscriptions by focusing on reading alert feeds rather than managing subscriptions.

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

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

The description provides clear context on when to use the tool, including filtering by type and since, and mentions that polls work fine. It also offers an alternative endpoint (GET registry.pipeworx.io/alerts.json) for scripts and dashboards, but does not explicitly state when not to use this tool over siblings.

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

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

Annotations already mark it as read-only and idempotent. The description adds detailed behavioral info: fans out to SEC, GDELT, USPTO with fallback logic, notes USPTO soft-fail due to API sunset, and describes the return structure with grouped changes and citation URIs.

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

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

The description is front-loaded with examples and purpose, and every sentence adds value. It is slightly lengthy but remains clear and efficient; minor trimming could be possible without losing meaning.

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

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

Given the tool's complexity (multiple sources, fallbacks, parameter formats), the description is comprehensive. It covers all important aspects: sources, fallback, parameter details, return structure, and sibling distinction, despite no output schema.

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

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

Schema coverage is 100%, and the description enhances parameter understanding by explaining 'since' accepts ISO dates or relative shorthand with examples, and that 'value' can be ticker or CIK. It also suggests typical values for 'since'.

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 with multiple query examples like "What's new with X" and explicitly distinguishes it from the sibling tool 'entity_profile' for static profiles. It specifies that it returns a change feed for a company within a time window.

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

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

Provides explicit when-to-use guidance with example queries and when-not-to-use by directing to 'entity_profile' for static profiles. Also describes fallback behavior from GDELT to GNews, giving clear context for usage.

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

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

Annotations already provide idempotentHint and readOnlyHint. The description adds scoping by identifier, persistence duration (24h vs persistent), which goes 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?

Very concise yet comprehensive; first sentence states purpose, second gives usage context, third details behavior, and ends with paired tools. No redundant words.

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

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

Despite no output schema, the description explains storage, scoping, and retention, making it complete enough for effective use. Could mention return value but not critical.

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 usage examples (e.g., 'subject_property') but doesn't significantly extend meaning 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 'Save data the agent will need to reuse later' with specific verb and resource, and distinguishes itself from siblings by referencing recall and forget.

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

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

Explicitly states when to use (discover something worth carrying forward) and mentions alternative tools (recall, forget), providing clear guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds that the tool 'cascades through several lookup endpoints internally' and describes the format of returned identifiers, providing useful behavioral context beyond annotations.

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

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

Well-structured with front-loaded examples and clear separation of supported types. While slightly verbose, every sentence adds value. Could be trimmed slightly, but overall effective.

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

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

Despite no output schema, the description fully covers return values for both entity types, including specific fields and citation URIs. It even mentions the tool's efficiency (replaces 2-3 manual lookups). Given the tool's complexity (multiple types, input forms), this is highly 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 both parameters described. The description adds substantial context: for company type, it lists accepted input forms (ticker, CIK, name) and notes auto-disambiguation; for drug, it specifies brand or generic name. This goes beyond the basic schema descriptions.

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

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

Description starts with clear examples ('What's the ticker for…') and explicitly states the tool resolves a user-spoken name to a canonical identifier. It distinguishes between two supported entity types (company, drug) and specifies what each returns, leaving no ambiguity about the tool's purpose.

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

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

Explicitly says 'Use FIRST whenever you have a name but need an ID,' providing clear when-to-use guidance. It does not list when not to use or explicitly differentiate from siblings like entity_profile, but the context is strong enough to guide appropriate usage.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds value by describing the probing, ranking, and output structure (score, confidence, signal density), providing behavioral context beyond the annotations.

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

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

The description is extremely concise, consisting of only two sentences. The first sentence front-loads the main purpose and action, and every sentence serves a clear function with no wasted words.

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

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

The description explains the tool's purpose, process (probes, ranks, surfaces), and example use. It mentions output fields (score, confidence, signal density) despite the lack of an explicit output schema. A minor gap is the lack of detail on how models and _apiKey interact, but the schema fills this.

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

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

Schema description coverage is 100%, and each parameter has a clear description in the schema. The tool description adds no additional semantic information about parameters beyond what is already in the schema.

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

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

The description uses a specific verb 'compare' and resource 'AI visibility' across multiple entities. It clearly distinguishes from sibling ai_visibility_check by stating it probes multiple entities side-by-side and ranks them.

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

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

The description provides a concrete use case ('competitive AI-marketing audits') and an example question. It implicitly contrasts with single-entity probes via ai_visibility_check but does not explicitly list when to avoid or name alternatives.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. Description adds that it fans out to two external services, mentions potential 5-30s delay for new versions, and explains graceful degradation with sources_failed list. 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?

Dense, informative single paragraph. Could benefit from bullet points for return fields or better segmentation, but no wasted sentences and key information is 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?

Fully describes return fields (summary block with detailed fields, advisories, links, alternatives), addresses edge cases (partial failures, timeouts), and specifies ecosystem limitation. No output schema, so description carries full burden effectively.

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

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

Schema coverage is 100% with clear descriptions for both parameters (package and version). Description repeats that scoped packages are accepted and version defaults to latest, adding a concrete example but not significantly deeper semantics beyond the schema.

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

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

Clearly states the tool checks if an npm package should be added to a project, combining deps.dev license/advisories and bundlephobia size data. The description distinguishes it from broader search tools and specifies it returns a summary block, advisories, links, and alternatives.

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

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

Explicitly instructs to use when agent asks about safety, popularity, or size (e.g., 'is X safe/ popular/ small', 'what does adding lodash cost me'). Also notes ecosystem limitation (NPM only) and directs other ecosystems to deps.dev directly.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds critical details: returns passages with offsets and similarity scores, uses BGE-base-en embeddings + cosine over 500-char windows, 200K char cap with truncation flag. 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 well-structured sentences: purpose, usage, technical details. Front-loaded with key action. Slightly verbose on technical specifics but highly relevant.

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 semantic search tool with no output schema, the description covers purpose, usage, pairing, limits (200K chars), chunking method, and output format (offsets, scores). No missing critical 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 coverage 100% so baseline 3. Description adds value: for 'text' specifies max 200K chars, for 'query' gives natural-language examples, for 'limit' mentions default 5. Goes 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?

Clear verb-resource: 'semantic search inside a fetched record'. Examples (SEC 10-K, article) and explicit differentiation from sibling ask_pipeworx_grounded, which is mentioned as a paired tool for grounded responses.

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

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

Explicitly states when to use: 'when the record is too big to cram into the prompt'. Also mentions alternative tool and pairing advice: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages'.

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 delivery channel restrictions (10/day SMS cap, phone verification, webhook auto-disable) and idempotent creation. Annotations declare idempotentHint=true, which aligns. Adds context beyond 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?

Single paragraph packs significant detail efficiently. Front-loaded with purpose. Could be slightly restructured for readability, but every sentence adds value.

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

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

Given complexity (nested params, no output schema), description covers tool behavior comprehensively: types, parameters, delivery options, constraints. Sufficient for 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?

Schema coverage is 100%, and description enriches each parameter with detailed type-specific examples and constraints (e.g., sec_8k items, delivery channels). Goes far beyond schema descriptions.

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

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

Description starts with 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' This clearly states the verb (create), resource (subscription), and output (id). Distinct from siblings like list_subscriptions and unsubscribe.

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

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

Explicitly states requirement for Pipeworx OAuth account and lists supported types with examples. While it doesn't say when not to use, sibling tools provide alternatives, and the description implies use when needing to monitor live events.

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. The description adds behavioral context beyond annotations: it explains the output format ('category-bucketed example questions') and invocation options (no args vs. topic). 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 slightly long (4 sentences) but front-loaded with trigger phrases and uses a clear flow. Each sentence adds value, though some inline listing could be formatted more concisely. Still well-structured.

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

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

Given the tool's simplicity (1 optional parameter, no output schema), the description is complete. It specifies return format, invocation options, and intended use case. No gaps remain for the AI agent to infer.

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 optional parameter. The description adds meaning by listing possible values (finance, pharma, etc.) and explaining the behavior when omitted (cross-category spread). This significantly enriches the schema definition.

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

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

The description clearly identifies the tool as an onboarding entry point that returns category-bucketed example questions with tool+argument shapes. It distinguishes from siblings like 'ask_pipeworx' by specifying it is for discovering what is worth asking, not for asking questions directly.

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 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' This gives clear usage context. While it doesn't explicitly name alternative tools for exclusion, the instruction implies when not to use it. Minor improvement could be adding explicit 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?

The description adds crucial behavioral context beyond annotations: it explains that the row is deactivated (not deleted) and historical events remain accessible via 'recent_alerts'. This aligns with the non-destructive annotation and provides valuable transparency.

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

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

Two concise sentences cover the essential points: action, ownership, and behavioral effect. No wasted words, front-loaded with the main purpose.

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

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

For a simple single-parameter tool with no output schema, the description is complete. It covers the action, ownership constraint, and the lifecycle consequence (deactivation), which is sufficient for correct invocation.

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

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

With 100% schema description coverage, the single parameter 'id' is already well-documented in the input schema. The description reinforces that the id comes from 'subscribe' but adds no new semantic value.

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

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

The description clearly states the specific action ('cancel') and resource ('subscription'), and distinguishes from the sibling 'subscribe' tool. It also mentions ownership enforcement, adding clarity.

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

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

The description implies usage for canceling one's own subscriptions but does not explicitly provide when-to-use guidelines or compare with alternatives like 'list_subscriptions' or 'subscribe'.

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

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

Annotations already provide readOnlyHint, idempotentHint, openWorldHint. Description adds return format (verdict categories, actual value with citation, percent delta), supported claim types, data sources (SEC EDGAR + XBRL), and efficiency gains. No contradictions with annotations.

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

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

The description is front-loaded with trigger phrases and a clear usage statement, then efficiently covers domain, output, and benefits. Each sentence adds value without redundancy.

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

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

With no output schema, the description thoroughly explains return types and components. It covers domain limitations, data sources, and replaces multi-step workflows, making it complete for a single-param tool with rich annotations.

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 good description and examples. The tool description adds domain context (company-financial claims) and clarifies the natural-language format, providing additional meaning beyond the schema alone.

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

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

The description clearly states the tool validates natural-language factual claims against authoritative sources, with explicit trigger phrases and examples. It distinguishes its domain (company-financial) and replaces multiple sequential calls, making purpose unambiguous.

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

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

Description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and specifies the supported domain (company-financial). It doesn't explicitly exclude other domains or differentiate from similar sibling tools like 'ask_pipeworx_grounded', but the domain constraint provides clear context.

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