Worldbank Projects

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 context: default model is Workers AI Llama-3.3-70b (free), passing _apiKey probes Anthropic with BYO key (paid directly), and returns per-model {score, confidence, signals, raw_response} plus combined view. It explains behavioral traits 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 efficiently structured: it opens with the main action and scoring, then details default model and optional API key, then return format, and ends with use cases. Every sentence is necessary and contributes to understanding, with no redundancy.

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

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

Given the tool's complexity (4 parameters, no output schema), the description fully covers functionality, parameter details, return format, and use cases. It explains return fields per model and combined view, making it complete for an AI agent to select and invoke correctly.

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

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

Schema description coverage is 100% for all 4 parameters. The description adds meaning beyond schema: explains default model for 'models' parameter, that '_apiKey' is only needed with 'anthropic' model and is passed straight through, and that 'context' helps disambiguate. 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 probes LLMs for knowledge about an entity and scores visibility (0-100) per model. It specifies the resource (business/brand/product/topic) and the action (probe, score), distinguishing it from siblings like 'scan_competitor_ai_presence' by focusing on visibility scoring rather than scanning presence.

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

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

The description explicitly lists use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. It provides clear context for when to use the tool, though it does not explicitly state when not to use it or mention 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, and destructiveHint false, covering safety. The description adds that the tool routes to sources, fills arguments, returns structured answers with stable citation URIs, and works on every tier with one fast call. This enhances 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?

The description is front-loaded with the main purpose and well-structured with examples and alternatives. However, it is slightly verbose; some redundancy could be trimmed without losing clarity.

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

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

Given the tool's complexity (routing to many sources) and the simple schema (just a question), the description fully compensates. It explains the tool's functionality, output with citations, and usage context, and references sibling tools. No output schema exists, but the description adequately covers 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 description coverage is 100%, so the baseline is 3. The description only repeats the schema's description ('Your question or request in natural language') without adding significant new semantics for the parameter.

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: it answers factual questions by routing to one of 4,774 tools across verified sources. It uses specific verbs like 'what is', 'look up', and 'find', and explicitly distinguishes from siblings ask_pipeworx_grounded and deep_research by specifying when to use each.

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

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

The description provides explicit directives: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and 'Use whenever the user asks...' for specific question types. It also clearly states when to step up to alternatives (e.g., for hallucination-resistant answers or broad multi-part questions).

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false, so safety profile is clear. Description adds the extra LLM call cost, the return structure including refusal_reason field with enumerated reasons (not_in_source, no_tool_match, tool_error, data_truncated, llm_error), and success fields (answer, evidence, confidence, source, fetched_at). This goes beyond annotations by disclosing cost and 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?

First sentence immediately conveys core value proposition. Subsequent sentences logically explain mechanism, return format, and usage guidance. No redundant or filler content. Efficiently packed with high-density information ideal for agent consumption.

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 (routing among 4,774 tools), the description covers all necessary aspects: purpose, trade-off vs sibling, return schema (including refusal reasons), and use cases. No output schema is defined, but the description compensates by detailing return fields. Complete for high-stakes decision-making.

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 6 parameters all described as aliases for question, with 100% coverage. Description complements by explicitly stating 'Your question in natural language. Accepts query, q, prompt, text, input as aliases.' Though schema already covers the aliases, the description consolidates and clarifies that any of these can be used, adding practical clarity.

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 is a hallucination-resistant answer mode for high-stakes reads. Distinct from sibling ask_pipeworx by emphasizing that it extracts answers using only tool results, preventing invention. The verb 'ask' with 'grounded' qualifier plus detailed behavioral description leaves no ambiguity.

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

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

Explicitly specifies when to use: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with concrete examples (financial verdicts, legal claims, medical lookups, public statements). Also advises to prefer ask_pipeworx for casual lookups, providing clear 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, destructiveHint=false, and idempotentHint=true, which the description does not contradict. The description adds substantial behavioral context beyond annotations: resolution contract details (market_match_confidence, suggestions), safety short-circuits for low-confidence and closed markets, parent event extraction, news fallback fields, wide-spread tradeability warnings, and resolution-rule risk analysis. This fully informs the agent of edge cases and limitations.

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

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

The description is long but well-structured with section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.), making it scannable. It front-loads the primary purpose and use cases. Every section adds value for an agent needing exact behavioral rules. Some redundancy could be trimmed (e.g., repeated mention of closed markets), but overall it earns its length.

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

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

Despite lacking an output schema, the description provides detailed response shapes covering result.market, result.analysis, result.evidence, resolution contract fields, parent event, and news fields. It also explains safety mechanisms. For a tool with 3 parameters and no output schema, this is exceptionally complete, leaving no ambiguity about inputs, outputs, or edge 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 coverage is 100% (all three parameters described). The description adds meaning beyond the schema by explaining the market parameter can be a slug, URL, or question text; depth meaning 'quick' vs 'thorough'; and include_raw's impact on response size. The examples further clarify usage. While the schema already covers basics, the description enriches understanding, earning a 4.

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

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

The description starts with a clear verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It then specifies input types (slug, URL, question text) and the core workflow (resolves, classifies, fans out, returns evidence + comparison). The use cases ('should I bet on X') and extensive examples distinguish it from sibling tools like ask_pipeworx or validate_claim by emphasizing its all-in-one, bet-specific nature.

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 for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also covers when not to use it implicitly by describing closed markets and low-confidence matches as blocking paths. However, it does not directly compare to sibling tools or list alternatives, which prevents a score of 5.

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. The description adds behavioral details: off-calendar fiscal year handling, result sorting by primary metric, and return of paired data with citation URIs. These enrich 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 well-structured, front-loaded with example queries, and every sentence adds value. It could be slightly shorter but remains effective and informative 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?

Without an output schema, the description explains return format (paired data + citation URIs) and covers both entity types with detail on metrics. Given tool complexity, it provides sufficient context for an agent to use it 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% with descriptions. The description adds meaning: 'type=company' pulls latest 10-K data, 'type=drug' pulls FAERS counts; 'values' constrained to 2-5 items with examples. This significantly enhances understanding of parameter semantics.

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 a single parallel call, distinguishing it from sequential single-pack lookups. It specifies exactly what data is pulled for each type, making the purpose unambiguous.

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

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

The description includes explicit guidance to prefer this tool over sequential lookups when comparing entities, provides example query phrases, and specifies constraints on type and values. It lacks explicit when-not-to-use cases but overall gives clear usage context.

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

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

Annotations already provide readOnlyHint and idempotentHint. Description adds critical behavioral context: account requirement, paid tier for thorough depth, parallel processing, return format (findings packet with evidence, confidence, source, fetched_at, citations, gaps), expected latency (15-60s), and the caveat about empty gaps for news topics. 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 front-loaded with critical info (account requirement, alternative) and structured logically. Some redundancy could be trimmed, but every sentence earns its place by adding unique value. 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?

Given tool complexity (no output schema), the description fully covers input schema (100%), annotations, output format, expected behavior, and error scenarios (empty gaps). It provides complete guidance for an agent to use this tool correctly.

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

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

Schema covers both parameters with descriptions. Description adds value by specifying that question can be broad/multi-part, and for depth, it explains the meaning of each enum value (quick=3, standard=5 default, thorough=8 paid). This goes beyond the schema's enum listing.

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 multi-source research across 1242 structured data sources, decomposes questions into facets, and returns a findings packet. It distinguishes itself from siblings like ask_pipeworx by specifying its broad/multi-part question scope and structured data focus.

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 when-to-use: for broad/multi-part questions over structured data. Also gives when-not-to-use: for single lookups (use ask_pipeworx), breaking/current news (use ask_pipeworx), and not signed in (use ask_pipeworx). Naming alternatives 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 indicate readOnlyHint=true and idempotentHint=true. The description adds value by explaining that results include full input schemas with curated examples, ready to call without a second lookup, which is 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 highly concise, front-loaded with the core purpose, followed by domain examples and key output characteristics. Every sentence adds value with no redundancy.

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

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

For a discovery tool with 6 parameters and no output schema, the description adequately explains what is returned (tool names, descriptions, schemas). It lacks mention of pagination or error handling, but the annotations cover safety and idempotency, making it acceptably 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%, but the description adds meaning by explaining that 'query' accepts natural language and lists multiple aliases, plus specifies default and max for 'limit'. This supplements the schema definitions.

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

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

The description clearly states that the tool 'finds tools by describing the data or task' and lists extensive domains, directly distinguishing it from sibling tools which are specific-purpose. It is a specific verb+resource with explicit scope.

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 'call this FIRST when you have many tools available and want to see the option set (not just one answer).' While it doesn't include explicit when-not-to-use statements, the context strongly implies direct calls for known tools.

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

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

The description discloses behavioral traits beyond annotations: it fans out across multiple sources (SEC EDGAR, XBRL, USPTO, news, GLEIF), notes a sunset for patents (soft-fails until reactivated), and describes the return structure. Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false; the description adds context 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 relatively long but well-structured with examples at the start and clear separation of return fields. Every sentence adds value; however, it could be slightly more concise by reducing the example list. The front-loading of examples is effective for quick 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?

Given the absence of an output schema, the description comprehensively explains the return fields (cik, recent_filings with URI details, fundamentals with sorting, patents with sunset note, news with fallback, LEI). It also addresses limitations (names not supported, patents sunset). This provides complete context for an agent to invoke the tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by clarifying that 'value' can be ticker or zero-padded CIK, and that 'type' only supports 'company' for now. This extra guidance on allowed inputs and future scope justifies a score above 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 the tool's purpose: producing a full cross-source profile of a US public company in one parallel call. It lists the sources and return fields, and distinguishes from sibling tools by explicitly recommending this over chaining single-source lookups. The examples (e.g., 'Tell me about X', 'research Acme') reinforce the verb 'profile' and resource 'company'.

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 ('ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view') and when not to use it (if only a name is given, use resolve_entity first). This provides clear decision criteria and references a specific sibling alternative.

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

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

Description confirms destructive nature ('delete') but adds little beyond annotations (destructiveHint=true, idempotentHint=true). No new behavioral insight provided.

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

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

Two sentences, front-loaded with purpose, no unnecessary words. Efficient and scannable.

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

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

For a single-parameter tool with annotations and no output schema, the description fully covers usage context, including 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?

Schema coverage is 100% with a clear description of the 'key' parameter. Description does not add additional meaning beyond 'by key'.

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

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

Description clearly states 'Delete a previously stored memory by key' with a 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?

Explicitly states when to use (stale context, task done, clear sensitive data) and suggests pairing with remember and recall. Lacks explicit when-not-to-use instructions.

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 behavior. Description adds valuable context about fetching the page, extracting metadata, and emitting the standard format—transparent about the process 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 well-structured sentences plus a bulleted use-case list. Front-loads the core action, then explains method, then lists applications. Every sentence earns its place with zero fluff.

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

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

For a simple tool with clear annotations and full schema coverage, the description sufficiently covers purpose, process, and output format. Lacks error-handling notes but is adequate for standard use.

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

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

Schema coverage is 100% with descriptions for both parameters (url, max_links). The tool description adds no further meaning beyond what the schema provides, earning the baseline 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?

Clearly states the tool generates a production-ready llms.txt file for any URL, extracting title/description/key links and outputting standard markdown. The purpose is specific and distinguishes it from sibling tools like ai_visibility_check.

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 lists three use cases: indexing a client's site, drafting llms.txt for own project, or auditing competitor visibility. Provides clear context but does not explicitly exclude alternatives or state when not to use this tool.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, etc. The description adds that the tool is keyless and details the returned fields, which supplements the annotations without contradiction.

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

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

The description is two sentences, front-loaded with the action and return fields, and includes 'Keyless' succinctly. 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?

For a simple tool with one parameter and no output schema, the description covers the purpose, input, and output fields. Minor omission: no mention of rate limits or data freshness, but not critical given 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?

The input schema describes the id parameter with examples and referral to search_projects, achieving 100% coverage. The description adds no additional parameter semantics beyond what the schema already provides.

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

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

The description clearly states it retrieves the full record for a single World Bank project by project id, listing specific data fields like financing breakdown, implementing agency, etc. This distinguishes it from sibling tools such as search_projects which find ids.

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

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

The description advises users to find ids via search_projects and notes 'Keyless' for no authentication. However, it does not explicitly state when not to use this tool or mention any prerequisites beyond having an id.

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

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

Beyond annotations (readOnlyHint, etc.), the description adds that it returns specific fields (id, type, params, etc.) and that it lists only active by default but can include inactive via parameter. 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?

Two sentences, direct and to the point. No redundant information, with the purpose 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?

For a simple list tool with one optional parameter and no output schema, the description covers purpose, return fields, and usage context. Annotations already handle safety, so description is complete.

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

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

Schema coverage is 100% with the parameter 'include_inactive' already described. The description doesn't add new semantic meaning for the parameter beyond what the schema provides, so baseline of 3 is appropriate.

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

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

The description starts with 'List the caller's active subscriptions', which is a specific verb and resource. It clearly differs 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?

The description explicitly states when to use: 'review what you're monitoring before adding more or to find an id to cancel'. This provides clear context, though it doesn't include when not to use it.

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

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

Annotations provide no hints (all false), so description alone carries the burden. It discloses rate-limiting (5 per day), free cost, no quota impact, and that feedback directly affects roadmap. No contradictions found.

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?

Front-loaded with purpose, then usage scenarios, then behavioral details. Every sentence adds value without redundancy. Concise yet comprehensive.

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 all necessary aspects: purpose, when to use, parameter guidance, limitations (rate limit), and cost/quota impact. Despite lacking an output schema, the description fully informs the agent about tool 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%, so parameters already have good descriptions. The description adds extra clarity by explaining enum values in more context (e.g., 'bug = something broke or returned wrong data') and outlining the role of the context object.

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 is for sending feedback about broken/missing features to the Pipeworx team. It specifies the resource (Pipeworx team) and action (tell them), and the detailed purpose distinguishes it from sibling tools like ask_pipeworx or discover_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 tells when to use: for bugs, features/data gaps, or praise. Also gives a negative guideline: don't paste the end-user's prompt. It uniquely positions this tool as the feedback channel among siblings.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive nature. The description adds valuable behavioral context: data source (CF analytics-engine), no PII, and caching behavior (5min-1h), going well beyond annotations.

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

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

The description is concise, with three sentences covering purpose, use cases, and behavioral insights. Front-loaded with the main action, 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?

Despite no output schema, the description sufficiently indicates return fields (top tools, packs, volume) and mentions caching. This is complete for a simple trending tool with a single optional parameter.

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 still adds meaningful context by explaining the effect of window sizes: 'shorter windows surface what's hot right now; longer windows show steady-state demand'. This enriches the enum 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 returns trending data: 'top tools, top packs, and total call volume' over a window. It provides three distinct use cases, distinguishing it from other tools like search or research.

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

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

The description explicitly lists three 'useful for' scenarios, guiding when to use the tool. It does not provide explicit when-not-to-use or alternative tools, but the context is clear for a trending discovery tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint. Description adds crucial details: Jaccard similarity threshold, partition filter, fill check against CLOB depth, 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?

Comprehensive but slightly verbose; could benefit from bullet points. However, every sentence is meaningful and the main points are 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?

Covers modes, internal checks, response structure, and fill risk. Lacks error scenarios or rate limits but sufficient for a complex arbitrage tool given annotations cover safety.

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 good param descriptions. The description adds significant value by explaining usage modes, examples, and internal checks, 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?

The description clearly states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks, distinguishing it from sibling tools like polymarket_edges or polymarket_kalshi_spread.

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 explains when to use no args (trending scan), event parameter (specific market), or topic parameter (cross-event scan), with recommendations and warnings like not to trade when realizable edge ≤ 0.

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

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

Annotations (readOnlyHint=true, idempotentHint=true, destructiveHint=false) are consistent. The description adds rich behavioral context: caching ('Cached 1h at the KV level'), response structure (by_segment, _diagnostics), edge calculations (edge_pp_net after slippage, kelly_fraction), and a 24h-move warning. No contradictions; the description enhances 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 long but dense with information. It is front-loaded with purpose, then structured into model families, tradeable-edge knobs, and response sections. Every sentence provides unique value, though some detail (e.g., model family math) could be moved to an output schema. The length is justified by the tool's complexity.

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

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

Given the tool's complexity (9 parameters, no output schema) and rich annotations, the description covers purpose, usage, filters, response fields, diagnostics, and caching. It explains what happens when segments are empty via _diagnostics. No significant gaps; the description is complete for an agent to use effectively.

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

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

All 9 parameters have descriptions in the schema (100% coverage). The description adds extra context: defaults (e.g., min_edge_pp=0.5), usage tips ('Bump for very thin partitions; drop to 0 if you have a smarter fill model.' for slippage_pp), and detailed explanations for complex knobs like min_partition_leg_kelly. This adds value 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's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It uses specific verbs ('scan', 'return'), identifies the resource (Polymarket markets), and distinguishes from siblings like polymarket_arbitrage and polymarket_edge_tracker by focusing on Pipeworx disagreement. The three model families further clarify the scope.

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: it's for 'what should I bet on today' and explains tradeable-edge knobs (min_liquidity, max_spread_pp, etc.) that help filter opportunities. However, it does not explicitly say when not to use this tool or mention alternatives (e.g., polymarket_arbitrage for cross-platform arbitrage). Still, the guidance on when to use and how to adjust parameters 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?

Beyond annotations (readOnlyHint, idempotentHint), the description details the snapshot mechanism, return structure (tracked, expired, snapshot_dates), decay computation, and limitations (TTL, not intraday). This provides extensive behavioral insight.

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

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

The description is front-loaded with purpose and key examples, but is lengthy and could benefit from section breaks. Nevertheless, every sentence adds value, and it is appropriately detailed for 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 no output schema, the description thoroughly explains the return object (tracked, expired, snapshot_dates) with field meanings and caveats. Limitations are clearly stated, making it self-contained for agent understanding.

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

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

Schema coverage is 100%, so baseline is 3. The description repeats schema info for 'days' and 'window' with minor rephrasing (e.g., 'max 30' vs 'clamp 2-30'), adding no significant new meaning.

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

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

The description clearly states the tool's purpose: edge persistence and decay telemetry from daily snapshots. It uses specific verbs ('answers', 'provides telemetry') and distinguishes from sibling tools like polymarket_edges by focusing on historical trend 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?

The description implies when to use the tool via an example comparing fresh vs. old edges, and mentions lookback/depth limitations. However, it does not explicitly specify when not to use it or compare directly to siblings 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?

The description extensively details behavior: walks the order-book ladder, returns top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdicts, basket-specific fields like theoretical_sum, realizable_sum, capture_ratio, thin_legs, forced_directional_risk, and warns about partial fills. This adds significant value beyond the readOnlyHint 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?

The description is relatively long but well-structured with uppercase headers for modes (SINGLE-MARKET, BASKET) and clear bullet-point-like lists. It is front-loaded with the core purpose. While every sentence adds value, it could be slightly more concise for quick parsing, but the complexity 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 covers return values for both modes, including warnings about partial fills and forced directional risk. The schema covers all parameters. The description is self-contained and provides all needed context for agent 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?

The description adds crucial meaning beyond the schema: explains size_usd interpretation in each mode (max spend on buys, target proceeds on sells; settlement notional in basket), clarifies side default auto logic, and provides usage context for event and market parameters. Given 100% schema coverage, the description still enriches understanding.

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

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

The description clearly states the tool performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth' and explains two modes (single-market and basket). It provides a specific verb and resource, and the purpose is distinct from sibling tools like polymarket_arbitrage or 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: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. This provides clear context and differentiates from 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?

Beyond annotations (readOnlyHint, idempotentHint), the description adds extensive behavioral detail: safety fields (compatibility_warning, temporal_alignment, skipped_cross_type), explanation of non-equivalent bet shapes, and that most pre-mapped topics return warnings. No contradiction with annotations.

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

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

The description is relatively long but well-structured with clear sections (purpose, modes, response, safety fields). It is front-loaded with the core purpose. Each sentence adds necessary detail for a complex 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, the description adequately explains the response structure (leg-by-leg prices, top spreads, safety fields) and temporal alignment. It provides enough context for an agent to understand what to expect, though a more explicit output shape would be beneficial.

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

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

Schema coverage is 100% with descriptions for each parameter. The description adds value by explaining the topic list, the two modes, and how explicit overrides work, providing deeper context beyond the schema.

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

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

The description clearly states the tool computes cross-venue spread between Kalshi and Polymarket for the same question. It distinguishes from siblings like polymarket_arbitrage by emphasizing the cross-venue nature and specific modes (topic shortcuts vs. explicit pairings).

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 two usage modes (topic and explicit event tickers) and provides context on when spreads are meaningful (via compatibility_warning and temporal alignment). It does not explicitly name alternatives but the context and warnings 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 declare readOnlyHint and idempotentHint. The description adds valuable behavioral context: sorted by board-approval date, returns compact shape with financing/sectors/dates, and notes 'Keyless' (no auth required). 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, no redundancy. First sentence captures core purpose and filtering; second sentence adds return shape and security context. Every word is meaningful.

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 3 parameters and no output schema, the description covers purpose, ordering, return shape, and authentication. Missing details like error handling or rate limits, but adequate for 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 is 3. The description does not add parameter-specific details beyond what the schema already provides (e.g., defaults for limit and status are in schema). Adequate but no extra 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?

Description specifies verb 'List', resource 'a country's World Bank projects', and includes ordering ('newest board-approval first') and filtering ('by status'). This clearly distinguishes it from sibling tools like search_projects.

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

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

The description clearly states when to use (list projects for a specific country with optional status filter) but does not explicitly mention alternatives or exclusions. However, the context is sufficient for an informed choice.

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

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

Annotations already indicate readOnly, idempotent, non-destructive. Description adds that listing all keys occurs when key is omitted, and mentions scoping to identifier. Adds 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?

Three sentences, front-loaded with core function, then usage context, then scope and pairing. No extraneous words.

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

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

For a simple tool with one optional parameter and no output schema, the description fully explains what it does, how to use it (with and without key), and how it relates to 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?

Schema has 100% coverage for the single optional parameter. Description reinforces the behavior of omitting key to list all keys and provides concrete examples (ticker, address, notes).

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

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

Clearly states the tool retrieves a value saved via 'remember' or lists all keys if key is omitted. Distinguishes from siblings 'remember' and 'forget'.

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

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

Explicitly describes when to use: to look up previously stored context (e.g., ticker, address, notes). Mentions pairing with remember/forget and scope to identifier. No explicit when-not, but context is clear.

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

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

Contradiction: annotations mark readOnlyHint=true, but description says setting mark_read:true flags events as read, which is a state mutation. This inconsistency undermines trust in the description's accuracy.

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, front-loaded with the main action, no redundant information. Every sentence adds meaningful context.

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

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

For a read-only list tool with 100% schema coverage and no output schema, the description adequately covers return fields, filtering options, side effects of mark_read, and even an alternative access method.

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 reinforces parameter usage with examples (e.g., 'sec_8k' for type) and explains the effect of mark_read, 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 clearly states the tool retrieves recent alerts from the subscription feed, listing specific fields returned. It does not explicitly differentiate from sibling tools like list_subscriptions, but the action is unambiguous.

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

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

The description mentions that polling works fine and points to an alternative API endpoint for scripts, implying safe to use for frequent pulls. However, no explicit guidance on when to use this tool vs siblings or when not to use it.

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

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

Beyond annotations (readOnly, idempotent, non-destructive), the description reveals multi-source fan-out (SEC, GDELT→GNews fallback, USPTO), handling of API sunsets, and the parallel execution model. No contradiction with annotations.

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

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

Concise, front-loaded with examples, every sentence adds value. No redundant or unclear phrasing. Structure flows from purpose to details to guidance.

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

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

Given no output schema, the description covers return format (changes[], total_changes, citation URIs). It also explains edge cases (GDELT limit, USPTO soft-fail). For a complex multi-source tool, this is thorough.

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

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

Schema covers all three parameters with descriptions (100% coverage). The description adds useful context for `since` (ISO date or relative shorthand, typical monitoring value). Does not repeat schema text but enhances understanding.

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

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

The description clearly states the tool's purpose: a change feed for a company in a recent time window, with specific examples of queries. It distinguishes itself from the sibling tool entity_profile by contrasting static profile vs. change feed.

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 versus entity_profile. Provides guidance on the `since` parameter with typical monitoring values. The alternative is clearly named and contrasted.

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 reveals persistence behavior (authenticated vs anonymous sessions, 24-hour retention) and write nature, complementing annotations. 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, front-loaded with purpose, no wasted words. 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?

Covers all necessary aspects: when, what, how, persistence, and companion tools. Complete for a simple write tool with 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 description adds naming conventions for keys and examples for values, going 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?

Description clearly states the tool saves data for reuse, with specific verb ('save') and resource ('data'), and distinguishes from sibling tools 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: 'when you discover something worth carrying forward'. Also provides guidance on alternatives: 'Pair with recall to retrieve later, forget to delete.'

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds value by explaining internal cascading lookups, return format (e.g., ticker + CIK for company), and citation URIs, which go 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 front-loaded with example queries, then explains purpose and supported types. It is slightly verbose but each sentence contributes meaningful information. Slight improvement could trim redundant phrasing.

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 2 parameters, no output schema, and moderate complexity, the description covers the tool's behavior, input formats, and return details for each type. It lacks edge-case handling (e.g., multiple matches) but overall is complete for a lookup 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 both parameters. The description adds significant meaning by detailing what each entity type returns and giving example values ('AAPL', 'ozempic'). 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 uses specific verbs like 'resolve' and gives concrete examples ('What's the ticker for...') and distinguishes the tool from siblings by stating 'Use FIRST whenever you have a name but need an ID.' It clearly identifies the resource (names to IDs) and scope (supported types: company, drug).

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 ('Use FIRST whenever you have a name but need an ID') and lists supported types with input formats. It does not explicitly state when not to use or alternatives, but the context makes it clear this is for name-to-ID resolution.

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 description's burden is lower. The description adds valuable behavioral context: it probes each entity with ai_visibility_check, ranks by score, and surfaces most/least recognized. It also mentions optional context disambiguation. 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 long and highly efficient: first sentence states core action, second explains mechanism and output, third provides use case and example. No filler or 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?

Given the tool has 4 parameters, full schema coverage, and no output schema, the description covers all essential aspects: what it does, how it works (calls ai_visibility_check per entity), input parameters with optional fields, and output format (ranked list with score, confidence, signal density). The use case example further clarifies context.

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

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

Schema coverage is 100%, but the description adds semantic nuance beyond the schema, such as 'First entry treated as the "subject" for narrative; rest are competitors.' It also clarifies the models parameter options and the purpose of context. This enhances understanding beyond the parameter descriptions 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 compares AI visibility across multiple entities side-by-side, uses ai_visibility_check, and returns a ranked list. It distinguishes from sibling tools like ai_visibility_check (single entity) and compare_entities (generic comparison) by specifying the mechanism and output.

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

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

The description provides a clear use case ('competitive AI-marketing audits') and an example question, guiding when to use the tool. Although it doesn't explicitly state when not to use it, the context and mention of calling ai_visibility_check for each entity imply that for single-entity queries, one should use ai_visibility_check instead.

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?

Provides rich behavioral detail beyond annotations: fans out to deps.dev and bundlephobia, returns summary block with specific fields, lists alternative versions, handles partial failures with sources_failed. All aligns with readOnly/openWorld/idempotent/not destructive hints. 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?

Front-loaded with core purpose, then expands with relevant details. Every sentence adds information, but the description is somewhat lengthy. Could be slightly more concise while retaining completeness.

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 details the return structure (summary block, per-advisory details, links, alternative versions, sources_failed). Handles partial failures and timing. Two parameters are fully documented in schema. Sufficient for an AI agent to understand inputs and outputs.

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. The description adds minor value: mentions scoped packages are accepted for 'package' and default behavior for 'version'. Does not repeat schema but provides useful context.

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

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

Clearly states the tool's purpose: a composite check for adding npm packages, specifying verb ('scan'), resource ('npm package'), and scope ('in ONE call'). Differentiates from sibling tools by narrowing to npm ecosystem and mentioning alternatives for other ecosystems.

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

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

Explicitly tells when to use ('is X safe/popular/small', 'what does adding lodash cost me') and when not to use ('PyPI/Maven/Cargo/Go fall under deps.dev:version directly'). Also mentions timing caveats (bundlephobia may take 5-30s) and graceful degradation.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds value by confirming keyless access and detailing return fields (financing, sectors, etc.), 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 efficiently convey purpose, usage, and return value. No wasted words; the most critical 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?

For a search tool with 4 well-described parameters, no required fields, and supportive annotations, the description adequately covers return values and access requirements, leaving no obvious gaps. The lack of an output schema is mitigated by listing returned fields.

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

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

All parameters have thorough descriptions in the schema (100% coverage). The description's additional text ('Keyless. Provide query and/or country_code.') provides minimal extra semantic value, so it meets the baseline of 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?

The description clearly states the tool searches World Bank development projects with filters for free text, country, and status. It distinguishes from siblings like 'get_project' and 'projects_by_country' by specifying multiple search dimensions and keyless access.

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

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

The description gives clear usage context ('Keyless. Provide query and/or country_code.') and lists the fields returned, but does not explicitly state when not to use this tool or specify alternatives like 'projects_by_country' for country-only queries.

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 complemented by detailed behavioral traits: embedding model (BGE-base-en), window size (500-char overlapping), cap (200K chars) with truncation flagging, and output features (passages with offsets and similarity scores). 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 compact (~100 words), front-loaded with purpose, then usage, then technical details. Each sentence carries unique value without redundancy or fluff.

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

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

Despite lacking an output schema, the description fully explains the return format (top-N passages with character offsets and similarity scores). It also covers truncation behavior, pairing with a sibling tool, and safety via annotations. The tool's complexity is well-addressed.

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%, providing good parameter descriptions. The description enriches this by adding usage context: query is 'natural-language' with examples, text max size is reiterated, and limit default is mentioned. This goes beyond 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?

The description explicitly states 'Semantic search INSIDE a fetched record' with concrete examples (SEC 10-K, article, long tool result). It distinguishes from sibling tools by mentioning pairing with 'ask_pipeworx_grounded' and clarifying its role after fetching a record.

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 clearly says 'Use when the record is too big to cram into the prompt' and pairs with ask_pipeworx_grounded for grounding. It implies context-saving benefit but does not explicitly state when not to use or list alternatives beyond the paired 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?

Adds behavioral context beyond annotations: requires specific account, has SMS cap (10/day), and mentions auth. No contradiction with annotations (readOnlyHint=false, idempotentHint=true). Not all behavioral traits covered (e.g., rate limits on API), but good overall.

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 lead sentence, followed by details. However, somewhat lengthy; could be tightened without losing essential information.

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

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

Comprehensive given no output schema: covers return value, all parameter details, auth, and delivery constraints. Handles nested objects and enums thoroughly.

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 description adds extensive details: examples for each type's params, delivery options with requirements and constraints (SMS verification, webhook HMAC signing). Significantly enhances understanding.

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

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

The description clearly states the verb 'Create' and the resource 'proactive monitoring subscription', and specifies it returns the new subscription id. This distinguishes it from sibling tools 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?

Provides context on requirement (Pipeworx OAuth account), supported types, and delivery channels. Does not explicitly contrast with alternatives like recent_alerts, but the context implies proactive vs pull. Lacks explicit when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint. Description adds context: returns example questions with exact tool+argument shapes, drawn from live catalog of thousands of tools. 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?

Front-loaded with synonyms and clear purpose. Every sentence adds value, though slightly long due to listing categories. Could be slightly more concise but still efficient.

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

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

Comprehensive for an onboarding tool: describes return content, usage context, parameter behavior, and relation to siblings. No output schema but return values well 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% but description adds significant value: lists possible topic values (finance, pharma, etc.) and explains effect of omitting vs passing topic. 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?

Clearly states the tool returns category-bucketed example questions for onboarding. Distinguishes from siblings by being the entry point when agent doesn't know what Pipeworx can do.

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: FIRST when you do not yet know what Pipeworx can do. Also explains when to pass topic vs omit, and names alternative tools like ask_pipeworx, entity_profile, etc.

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: deactivation vs deletion, preservation of historical events, ownership enforcement. Complements annotations like destructiveHint false and idempotentHint true.

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

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

Three sentences with no fluff: action, constraint, behavioral detail. Front-loaded and 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?

Covers all needed aspects for a simple one-param tool: purpose, ownership, side effects, and relationship to historical data. No output schema needed.

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

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

Only parameter 'id' is well-described in schema (uuid returned by subscribe). Description adds 'by id' but no new constraints beyond schema; baseline 3 applies.

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

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

Clearly states it cancels a subscription by ID, distinguishes from sibling tools like subscribe and list_subscriptions, and explains the outcome (deactivation not deletion).

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

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

Explicitly states ownership enforcement ('you can only cancel your own subscriptions'), guiding appropriate use. Could mention when not to use, but constraint 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 cover safety (readOnlyHint, idempotentHint, destructiveHint). The description adds valuable behavioral context: it specifies the data source (SEC EDGAR + XBRL), the version (v1), the scope of claims supported, and the return fields (verdict, actual value, citation, percent delta). This 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?

The description is rich with information but remains focused. It front-loads trigger phrases and concisely covers use case, domain, output, and efficiency. Every sentence contributes; however, it could be trimmed slightly 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 no output schema, the description adequately explains the return verdicts and actual value with citation. It mentions the supported domain and version, which is important context. It does not cover error cases or limitations beyond the scope, but for a single-parameter tool it is fairly complete.

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

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

Schema coverage is 100% with a clear description for the 'claim' parameter. The tool description further enriches the parameter meaning by providing natural-language examples and clarifying that it expects a factual claim, not arbitrary text. 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: natural-language claim verification against authoritative sources. It provides specific verb-resource pairing and distinguishes the tool by noting it replaces 4-6 sequential calls, implying a specialized capability not present in 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 states when to use: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also defines the domain (company-financial claims for public US companies), but does not provide explicit exclusions or alternative tools. This is clear but lacks when-not-to guidance.

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