Worldbank Projects

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

Annotations already declare the operation read-only, open-world, idempotent, and non-destructive. The description adds cost-related behavior (free default vs. BYO Anthropic key with direct payment to Anthropic) and result structure (per-model score/confidence/signals/raw_response + combined view). It doesn't mention failure modes or rate limits, but the added context 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?

Three sentences, each with a distinct job: what it does, model options/cost, and return format/use cases. No filler or repetition. Front-loaded with the core purpose.

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

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

The tool has 4 parameters (1 required), no output schema, and good annotations. The description explains return values, use cases, model defaults, and cost. It doesn't detail scoring methodology or pagination, but for this simple read-only probe, the description is largely complete. It could briefly mention that signals are contextual, but overall it's sufficient.

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

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

Schema descriptions cover all 4 parameters (100%), so the baseline is 3. The description adds extra meaning for `models` by specifying the exact default model (Workers AI Llama-3.3-70b) and for `_apiKey` by clarifying the payment relationship. It doesn't add to `entity` or `context`, but the additional default/cost detail pushes it 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 uses a specific verb ('probe') and resource ('one or more LLMs') with a clear outcome ('score visibility (0-100) per model'). It also mentions return format and use cases, making the tool's function unmistakable. However, it does not explicitly contrast with sibling tools like 'scan_competitor_ai_presence' or 'ask_pipeworx,' so it stops short of full sibling differentiation.

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: 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also explains when to pass `_apiKey` (to probe Anthropic) and that workers-ai is the free default. It does not mention when to avoid this tool or name alternative tools, so it's clear but lacks exclusions.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral context: it routes to diverse sources, returns citations, makes 'one fast call', and works 'on every tier'. It also mentions the escalation path to grounded/deep_research. No contradictions with annotations.

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

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

The description is long but well-structured: it leads with a strong preference instruction, then scope, examples, and escalation. Every sentence adds value, though the example list could be trimmed slightly without loss. The front-loading is effective.

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

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

Given that there is no output schema, the description appropriately explains the return type: 'the structured answer with stable pipeworx:// citation URIs'. It also covers tool scope, source diversity, trigger phrases, examples, tier compatibility, and when to use alternatives. This is a complete picture 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% and the 'question' property is fully described, including aliases (query, q, prompt, text, input). The description only reinforces the notion of a natural-language question via examples, but adds no new parameter semantics beyond what the schema already conveys. Baseline 3 is appropriate.

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

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

The description clearly states the tool's function: 'Routes the question to the right one of 5,529 tools...' and returns a structured answer with citations. It distinguishes itself from siblings by naming ask_pipeworx_grounded and deep_research as alternatives for more specific use cases, making it unambiguous which tool to choose.

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

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

The description provides explicit usage guidance: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and 'Step up only when needed' with named alternatives. It lists concrete trigger phrases ('what is', 'look up', 'find', etc.) and even gives realistic examples, making when-to-use clear and actionable.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds useful context beyond these: it is a full working router with no fallback, candidate routing improvements may be active or retired, and it currently matches ask_pipeworx exactly. This helps the agent understand the tool's experimental nature and behavioral equivalence without contradicting annotations.

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

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

The description is three sentences long and front-loads the beta/experimental context, then covers current state, usage, and functionality. It is slightly verbose but every sentence contributes meaningful information, and the structure is logical.

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

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

The description covers the tool's purpose, current behavior, usage guidance, and notes that the response shape is identical to ask_pipeworx. Given the simple single-parameter schema, existing annotations, and absence of an output schema, this is sufficiently complete for an agent to select and 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?

The input schema has 100% description coverage, documenting all six parameters as aliases for 'question'. The description mentions 'same arguments' but adds no additional parameter semantics beyond what the schema already provides. With full schema coverage, baseline 3 is appropriate.

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

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

The description clearly identifies this as the beta version of ask_pipeworx, a universal router with identical tools, arguments, and response shape. It distinguishes itself from the stable ask_pipeworx by emphasizing the experimental 'candidate routing improvements' and the fact that it is the experimental edge. This is specific and avoids tautology.

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

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

The description explicitly states, 'Use it exactly like ask_pipeworx when you want the newest routing,' and explains that results are compared against the stable router to decide what merges. It also clarifies the current state (no active candidate, matches ask_pipeworx exactly), giving clear when-to-use guidance relative to the stable sibling.

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

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

The description goes well beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint). It discloses the exact behavior of extracting only from tool results, details the success response structure with fields like evidence and confidence, and enumerates specific refusal reasons (not_in_source, no_tool_match, tool_error, data_truncated, llm_error). It also exposes the cost tradeoff (one extra LLM call).

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

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

The description is dense but efficiently structured. It opens with the core value proposition, then explains the mechanism, return format, refusal cases, ideal usage, and cost tradeoff. Every sentence contributes unique, actionable information 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?

Even without an output schema, the description fully specifies the return fields and refusal reasons, which is critical for an agent to interpret results. It also covers when to use and when to avoid, the routing mechanism, and the cost difference. This is comprehensive for a complex AI routing tool.

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

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

The input schema already provides 100% coverage with descriptions for all six parameters, including aliases. The description adds minimal parameter semantics beyond noting that the tool 'fills arguments' automatically during routing. This is useful context, but the schema carries the main semantic burden, so a baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Hallucination-resistant answer mode for high-stakes reads.' It uses a specific verb ('EXTRACTS the answer') and explicitly differentiates from the sibling ask_pipeworx by noting it uses 'ONLY what the tool result contains.' The title 'Grounded' reinforces the purpose.

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

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

The description provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' and lists example domains (financial verdicts, legal claims). It also gives a clear exclusion: 'prefer ask_pipeworx for casual lookups' due to the extra LLM call cost.

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 only declare readOnly/idempotent/non-destructive. The description adds extensive behavioral disclosure: resolver contract, low-confidence short-circuit, closed-market handling, wide-spread tradeability warning, cancellation-rule risk, news fallback fields. This goes far beyond what annotations provide.

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

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

Long but highly structured with clear section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.). Every section adds unique, non-redundant information required for correct invocation. 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?

No output schema exists, so the description carries full burden of explaining return values. It does so in detail (result.market, analysis, evidence, parent_event, resolver contract) and covers edge cases (low-confidence, closed markets, wide spread, cancellation rules). The completeness is exceptional for a tool of this complexity.

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

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

Schema already covers all 3 parameters with 100% coverage. The description adds the classifier list and fan-out examples that clarify how the 'market' string is interpreted, which is helpful context beyond schema syntax. Depth and include_raw semantics are already fully described in the schema, so only modest additional value.

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

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

The first sentence clearly states the verb (research), resource (Polymarket bet), and scope (pulling Pipeworx data in one call). It distinguishes from siblings by focusing on a single bet with fan-out to category-specific data packs, which polymarket_arbitrage and polymarket_edges do not 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 lists use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') and provides fan-out examples per bet type. It does not explicitly name alternative tools to exclude, but the context is clear enough for an agent to select this over sibling tools.

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

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

Annotations already declare readOnly/openWorld/idempotent/destructive hints, but the description adds behavior not captured by annotations: sourcing from SEC EDGAR/XBRL, handling off-calendar fiscal years (AAPL Sep, NVDA Jan), sorting by primary metric, and returning citation URIs. No contradiction with annotations.

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

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

The description is dense but purposeful. It front-loads the core purpose and usage trigger phrases, then adds data source specifics, sorting behavior, and return format. Each sentence earns its place, though the long list of example phrasings makes it slightly verbose compared to a minimal 'Compares entities' statement.

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

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

With only 2 parameters and no output schema, the description fully covers the tool's context: what data is pulled for each type, how results are sorted, what is returned (paired data + citation URIs), and the advantage over sequential lookups. It leaves no significant gaps for the agent to invoke 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% (2 params well-described via enum and array details), but the description adds meaning beyond the schema: type='company' pulls specific financial metrics from latest 10-K, type='drug' pulls FAERS/trial counts, and values clarification for tickers/CIKs vs drug names. This enriches parameter understanding without duplicating schema.

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

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

The description uses a clear verb ('compare') with specific examples of user phrasing ('X vs Y', 'which is bigger') and explicitly states the resource (2–5 companies or drugs). It distinguishes from sibling tools like entity_profile by emphasizing side-by-side comparison in ONE parallel call vs sequential lookups.

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

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

It explicitly states when to prefer this tool: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and quantifies the benefit ('Replaces 8–15 sequential lookups'). It also gives context for when to use it (comparing entities) without ambiguity.

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

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

Beyond the annotations (readOnlyHint=true, openWorldHint=true, etc.), the description richly discloses behavioral traits: it requires an account, uses parallel routing, returns gaps[] for unanswered facets ('never invented'), includes a hop field, only provides citation_uri when fetchable, semantically excerpts large records, and gives time estimates. No contradictions with annotations.

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

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

The description is lengthy but every sentence carries operational value—account prerequisites, alternative tools, decomposition mechanics, output structure, and time expectations. It is front-loaded with the critical account requirement and uses semicolons to compact dense info, though it could be trimmed slightly for easier skimming.

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 thoroughly explains the return format (findings packet with verbatim evidence, confidence, source, fetched_at, citation_uri, gaps[], contradictions[], hop). It covers prerequisites, timing, paid tiers, and edge cases like unreachable citations, making the description complete for a complex tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds extra meaning beyond the schema by explaining how depth levels affect behavior (e.g., 'standard adds a gap-recovery hop', 'thorough adds a full iterative hop') and by noting the question can be broad/multi-part. This incremental guidance justifies 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 explicitly states the tool performs 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' in a single call, clearly distinguishing it from sibling tools like ask_pipeworx. The verb 'research' plus resource ('STRUCTURED data sources') and scope ('1455 sources, 5,529 tools in parallel') make the purpose unmistakable.

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

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

The description gives explicit when-to-use guidance: 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. It also specifies account requirements and which depth levels require payments, providing clear contextual direction for choosing between this tool and alternatives.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds valuable context about return format (top-N tools, names, descriptions, full schemas with curated examples) and positional usage ('ready to call directly, no second schema lookup needed'). No contradictions with annotations.

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

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

The description is moderately long but efficiently structured: it front-loads the core purpose, then gives use cases, return behavior, and positional guidance. Every sentence carries meaningful content 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?

Since there is no output schema, the description appropriately explains the return value: top-N relevant tools with names, descriptions, full input schemas, and curated examples, ready to call directly. Combined with usage guidance and schema examples, this is complete for the tool's complexity.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces that 'query' is a natural-language description and lists example domains, but the schema already documents aliases and provides examples. No additional parameter semantics are added beyond the schema.

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

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

The description uses a specific verb ('Find') and resource ('tools'), clearly states the mechanism ('describing the data or task'), and enumerates numerous data domains. It distinguishes itself from siblings by instructing to 'Call this FIRST' to see the option set.

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

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

Provides explicit when-to-use guidance: 'Use when you need to browse, search, look up, or discover what tools exist for...' and 'Call this FIRST when you have many tools available'. It implies when not to use (seeking a single answer) but does not name specific alternative tools, so it falls short of a full 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?

Even with annotations indicating readOnly/nullable/idempotent, the description adds valuable behavioral detail: it fans out across multiple sources (SEC, XBRL, USPTO, news, GLEIF), returns specific fields in a structured manner, notes the USPTO patent API sunset with soft-fail behavior, and specifies input limitations (CIK format). No contradictions with annotations.

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

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

The description is long (~150 words) but front-loaded with user query examples that instantly signal intent. It then lists return elements in a compact format. Each sentence carries information; minor redundancy with schema details slightly prevents a perfect score.

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

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

Despite lacking an output schema, the description fully enumerates the returned data (cik, company_name, recent_filings with URIs, fundamentals, patents, news, LEI) and includes caveats (patent API sunset, name limitation). It is complete given the tool's multi-source complexity.

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

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

The input schema already provides 100% coverage for both parameters, including descriptions for 'type' and 'value'. The description adds practical examples (e.g., 'AAPL', '0000320193') and reiterates the resolve_entity alternative, but this is largely redundant with the schema's existing descriptions. Baseline of 3 is appropriate.

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

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

The description clearly states the tool produces a 'full cross-source profile of a US public company in ONE parallel call' and provides explicit user query examples ('Tell me about X', 'research Acme'). It distinguishes itself from sibling tools like resolve_entity and compare_entities by focusing on holistic company profiling.

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 instructs to 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' and provides an alternative for names: 'use resolve_entity first if you only have a name.' This gives clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the description's 'Delete' wording adds little beyond those. It does add useful context about clearing sensitive data, but does not disclose additional behavioral traits such as irreversibility or behavior for missing keys beyond what annotations imply.

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 concise sentences: the first states the action, the second gives usage triggers, and the third links to related tools. There is no redundant content; every sentence earns its place.

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

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

For a one-parameter memory deletion tool with destructive and idempotent annotations, the description fully covers purpose, usage triggers, and the parameter is documented in the schema. No output schema is present, and none is needed for this simple operation.

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 key parameter clearly described as 'Memory key to delete.' The description's 'by key' adds no additional meaning or format details beyond the schema, so baseline 3 is appropriate.

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

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

The description opens with a specific action and resource: 'Delete a previously stored memory by key.' This clearly distinguishes the tool from sibling tools like remember and recall, which store and retrieve memories respectively.

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

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

Explicitly states when to use the tool: 'when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also mentions pairing with remember and recall, providing context for how it fits into the broader memory workflow.

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 the safety and side-effect profile. The description adds valuable process details: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format' and notes the output is a 'single text blob.' This goes beyond the annotations without being exhaustive.

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 and front-loaded, starting with the primary purpose and then adding process, output format, and use cases in just a few sentences. Every sentence contributes meaningful information, with no redundancy or filler.

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

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

For a simple tool with two parameters, comprehensive annotations, and full schema descriptions, the description adequately covers purpose, behavior, output format, and use cases. The absence of an output schema is mitigated by the explicit statement that the output is a 'single text blob' in standard llms.txt markdown.

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 input schema fully documents both parameters (url and max_links). The description provides overall context about generating llms.txt but does not add any additional meaning to the individual parameters beyond what the schema already specifies, hence the baseline score 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 states the tool's function with a specific verb ('Generate') and resource ('llms.txt file'), and clearly differentiates it from sibling tools by focusing on generating this specific file for any URL. The 'Useful for' list adds concrete context, making the purpose unmistakable.

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

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

The description provides explicit use cases ('getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor'), giving clear context for when to use the tool. However, it does not explicitly mention when not to use it or name alternatives, so it falls short of a 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 readOnly, openWorld, idempotent, and non-destructive behavior. The description adds 'Keyless' (no authentication needed) and enumerates the fields returned, which helps set expectations. No contradictions with annotations 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?

A single, well-structured sentence that front-loads the purpose, provides examples, lists the fields returned, and adds the keyless note. No redundant or filler 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 single-parameter get-by-id tool with strong annotations and no output schema, this description is complete: it specifies inputs, output fields, and safety profile. The tool is simple enough that no more context is 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?

Schema coverage is 100%: the parameter 'id' is fully described with examples and a pointer to search_projects. The description's mention of 'project id' and examples adds no additional semantic value beyond the schema, so the baseline of 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?

The description clearly states the tool retrieves the full record for a single World Bank project by ID, listing specific fields (financing breakdown, agency, borrower, etc.). The verb 'Get' and resource 'World Bank project' are precise, and the examples distinguish it from list/search siblings like search_projects and projects_by_country.

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 a workflow: use search_projects to find IDs, then get_project for the fuller record. The schema explicitly says 'Find ids via search_projects,' and the word 'fuller' signals it's for detailed lookups. However, it does not explicitly state when NOT to use it or name alternative tools for similar purposes.

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, so the safety profile is covered. The description adds value by specifying the caller scope, default active status, and exact fields returned, which is useful behavioral context beyond annotations.

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

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

Two sentences front-load the core action and return fields, then add high-value usage guidance. No filler, redundancy, or unnecessary detail.

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

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

For a simple read-only list tool with one optional parameter and no output schema, this description plus annotations give a complete picture: what it does, what it returns, and when to use it.

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 fully describes the only parameter include_inactive with 100% coverage, so the description doesn't need to add parameter details. It doesn't provide extra semantic value beyond the schema's existing description.

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

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

The description uses a specific verb 'List' with a clear resource: 'the caller's active subscriptions.' It also enumerates return fields (id, type, params, created_at, last_fired_at, fire_count), and the 'active' scope distinguishes it from subscription mutation siblings like subscribe/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 gives explicit use cases: 'review what you're monitoring before adding more' (implying before subscribe) and 'find an id to cancel' (implying before unsubscribe). It provides clear context but doesn't name alternative tools explicitly or state 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?

Despite annotations having all false hints, the description adds rich behavioral context: the claim_token flow, reading resolution status later, rate limit of 5 per day, free/no quota, and the team's daily digest process. No contradiction with annotations.

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

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

The description is long but information-dense. Every sentence provides valuable guidance, yet it could be slightly tightened without losing meaning. It front-loads the core purpose and then elaborates on edge cases and workflow details.

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

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

Given no output schema, the description adequately covers return behavior (claim_token, later status reads), rate limiting, the scope of acceptable feedback, and exclusions for other MCP servers. It is complete for a feedback tool with this complexity.

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

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

Schema has 100% parameter coverage, but the description adds extra semantic guidance: instructions on how to phrase feedback (avoid pasting user prompts), how claim_token works as a return value, and the context object's role. This exceeds the schema descriptions.

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

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

The description clearly states the tool's purpose: to tell the Pipeworx team about something broken, missing, or needed. It provides specific triggers (bug, feature, data_gap, praise) and distinguishes itself from sibling tools by being the dedicated feedback channel for Pipeworx 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 instructs when to use the tool (for bugs, feature requests, praises) and when not to (for tools from other MCP servers), directing users to file with the appropriate server. This goes beyond mere context and gives clear decision criteria.

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

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

The description adds significant behavioral context beyond the readOnly/idempotent annotations: caching behavior (5min-1h), data provenance (CF analytics-engine), and privacy guarantees (no PII). This informs the agent about freshness, reliability, and data sensitivity.

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 purpose, followed by concise use cases and a brief explanation of how the signal works. Every sentence earns its place; no filler or redundancy.

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

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

For a single-parameter read-only tool with no output schema, the description fully explains the return values (top tools, top packs, total call volume), window options, caching, and data provenance. It is complete for an agent to decide and invoke correctly.

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

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

Schema coverage is 100%, with the window parameter fully described (24h/7d/30d and their tradeoffs). The description merely repeats the window options without adding new semantic detail, so baseline 3 is appropriate.

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

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

The description clearly states the tool's function with a specific verb ('Returns') and resource ('top tools, top packs, and total call volume over a recent window'). It distinguishes from siblings by focusing on aggregate AI-agent calling patterns, not individual tool discovery.

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

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

The description provides three explicit use cases (discovering hot data sources, confirming canonical tool choice, checking alignment with agent needs), giving clear when-to-use guidance. However, it does not explicitly name alternatives or when-not-to-use scenarios.

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

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

The description goes far beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false) by explaining the internal logic: monotonicity checks, partition-sum validation, the 3pp deviation threshold, semantic similarity anchor (Jaccard ≥0.30), placeholder filtering, and the fill check that warns against trading if realizable edge ≤ 0. It also discloses return structure. This is rich behavioral context.

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

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

Although long, the description is tightly organized with clear section headers (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loaded with the core purpose. Every sentence earns its place by explaining a distinct behavior or mode, and there is no redundancy or filler.

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

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

The tool has optional parameters, no output schema, and considerable complexity, but the description covers all essential aspects: usage modes, input formats, algorithmic filtering, output fields, and a critical warning about fill checks. It also points to a sibling tool for additional functionality, making it complete for an agent to invoke and understand the result.

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?

Both parameters already have good schema descriptions (100% coverage), but the main description adds substantial value: it explains the difference between event slugs and topics, gives concrete examples ('fed-decision-may-2026', 'Strait of Hormuz traffic returns to normal'), and describes the behavior for each mode. This goes well 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 opens with a specific, multi-part purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly identifies the tool's resource (Polymarket) and mechanism, and the detailed mode breakdown (trending_scan, event, topic) further distinguishes it from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

Usage guidance is explicit and actionable. It states when to call with no args, when to pass `event` (recommended for a specific market), and when to pass `topic` (for cross-event scanning). It also explicitly points to a sibling tool: 'For custom sizing use polymarket_fill_risk.' This meets the highest bar for usage 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?

Beyond the readOnly/idempotent annotations, the description discloses caching behavior ('Cached 1h at the KV level keyed on all knobs'), response diagnostics, and important caveats like the 24h-move warning and the unreliable Fed signal. It also explains subtle design decisions such as partition arbs always returning kelly_fraction_half=0 at the parent level. This goes far 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 long and dense, but it is well-structured with sections (model families, opportunity fields, knobs, response structure, diagnostics) and front-loaded with the core purpose. Some details like per-sport α values and placeholder-slug filters are arguably excessive for tool selection, but they do provide transparency. It is not concise, but it is organized and purposeful.

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

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

With no output schema, the description thoroughly covers the response shape: by_segment, fed_candidates/fed_note, and _diagnostics. It also explains fields like edge_pp_net, kelly_fraction, and the 24h-move warning. All knobs and their effects are described, making the tool's behavior clear even in the absence of a formal 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?

The schema covers 100% of parameters, but the description adds cross-parameter meaning: 'TRADEABLE-EDGE KNOBS: min_liquidity / max_spread_pp drop opportunities where edge isn't realizable' and explains that min_kelly doesn't apply to partition arbs. It also clarifies the purpose of min_partition_leg_kelly. This enhances understanding beyond the individual 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 opens with a specific verb+resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' This clearly states the tool's function and distinguishes it from siblings by emphasizing the Pipeworx data signal. The phrase 'Built for "what should I bet on today"' further clarifies the intended use.

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

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

The description gives a clear context: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It also explains when to adjust knobs like min_liquidity and max_spread_pp. However, it does not explicitly name alternative tools or state when NOT to use this tool, so it lacks full exclusion/alternative guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, but the description adds substantial behavioral context: history depth limited by 60-day TTL, snapshots written on cache-miss creating gaps, decay from daily closes not intraday, and the meaning of expired opportunities. No contradiction with annotations.

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

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

The description is long but well-structured with clear sections (Args, RESPONSE, LIMITS). Each sentence carries useful information, and the organization aids readability, though it is denser than strictly necessary.

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

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

With no output schema, the description fully discloses the response structure (tracked[], expired[], snapshot_dates[]) and all major limitations (TTL, snapshot gaps, daily closes). It provides enough detail for an agent to understand what the tool returns and how to interpret it.

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

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

The input schema already provides full descriptions for both parameters (days and window) with defaults and clamps. The description merely repeats these defaults and adds no new semantic meaning beyond what the schema offers, so the baseline score of 3 is appropriate.

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

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

The description clearly states 'Edge persistence and decay telemetry' and answers a specific question: 'how long has this edge existed and is it shrinking?' It uses a specific verb and resource, distinguishing it from sibling tools like polymarket_edges by focusing on persistence/decay rather than just current edges.

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

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

The description provides clear context for when to use the tool (e.g., comparing a fresh wide edge vs a 3-week-old wide edge) but does not explicitly name alternatives or state when not to use it. It implies usage for historical edge analysis but lacks explicit exclusions.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive, but the description adds substantial behavioral context. It reveals that the tool 'walks the ladder,' interprets size_usd differently per mode, returns per-leg fill details, and importantly discloses the risk of partial basket fills leaving an unhedged directional position. It even names the dominant loss mode and the forced_directional_risk output. No contradictions with annotations.

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

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

The description is lengthy but extremely well-structured. It uses clear sections (SINGLE-MARKET, BASKET) and all-caps for critical requirements. Every sentence contributes unique information—no fluff. The length is appropriate given the tool's complexity and the absence of an output schema. It front-loads the purpose and then systematically details modes.

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?

This tool is complex (two modes, many outputs) and has no output schema, so the description carries the full burden of explaining return values. It does this comprehensively: it lists all key outputs for both modes (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict; theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg fill detail, thin_legs[], max_clean_notional_usd, forced_directional_risk). It also explains the interpretation of these outputs and the decision context. Nothing essential is missing.

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

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

Schema coverage is 100%, so baseline is 3. The description goes far beyond by providing mode-dependent meanings: size_usd as 'max spend' on buys, 'target proceeds' on sells, and 'settlement notional' in basket mode. It also explains the auto-detection of side in basket mode and the default values. This adds interpretive semantics that the schema alone does not convey.

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

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

The description opens with a clear, specific purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It explicitly distinguishes two modes (single-market vs basket) and explains the core outputs. Crucially, it differentiates itself from siblings by naming the exact tools and signals it supports (polymarket_arbitrage and polymarket_edges).

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

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

Guidelines are exceptionally clear. It states 'REQUIRES one of market or event' and provides explicit direction: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains when the tool is necessary (theoretical overround on thin books is not capturable) and the risk of partial fills. This covers both when-to-use and why.

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?

This description goes far beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint). It discloses exactly when compatibility_warning fires (two distinct cases), what temporal_alignment.aligned:false means mathematically, and how skipped_cross_type/subtype counters reveal dropped comparisons. There is no contradiction with annotations.

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

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

The description is long but every section earns its place: core purpose, mode explanation, response format, safety fields with warning semantics, and a closing caveat. It is front-loaded and uses clear labels (TWO MODES, RESPONSE, SAFETY FIELDS). The length is justified by complexity, but it's not as tight as a two-sentence ideal.

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

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

Despite having no output schema, the description provides sufficient context: it names response fields (leg-by-leg prices, spread[].top_spreads_pp), explains compatibility_warning in both scenarios, describes temporal_alignment, and warns about interpretability. For a tool with this many edge cases, the description is remarkably complete.

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

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

Schema coverage is 100% and the schema already describes each parameter including the override behavior. However, the description adds a collective 'TWO MODES' framing and clarifies the relationship between topic and explicit overrides, helping the agent understand parameter combinations. It doesn't add new syntax details beyond the schema, hence 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 opens with a specific verb+resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly distinguishes this tool from siblings like polymarket_arbitrage by emphasizing the cross-venue nature, and further clarifies via TWO MODES what resources are acted upon.

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 explicit when-to-use guidance for both modes (topic shortcuts vs. explicit tickers/overrides) and an explicit when-not: 'Real cross-venue spreads are rarer than the macro-shortcut list suggests — most pre-mapped topics return compatibility_warning today; pre-mapped ≠ tradeable.' It stops short of naming alternative sibling tools, so it doesn't earn a 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 cover read-only, idempotent, and non-destructive behavior. The description adds valuable behavioral context beyond annotations: keyless access, return shape ('compact project shape with financing, sectors, and dates'), and sort order ('newest board-approval first'). It omits pagination or error details, but the added context is sufficient for a safe read operation.

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

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

The description is two concise, front-loaded sentences with no redundant words. It efficiently conveys the verb, resource, key options, and return shape.

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

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

For a simple list tool with no output schema, the description adequately explains return shape, ordering, authentication (keyless), and filtering. It lacks explicit pagination behavior, but the schema documents default and max limits, and the tool's simplicity makes this omission acceptable.

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

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

Schema covers all parameters with full descriptions, defaults, and examples (100% coverage). The description adds only minimal parameter-related context, such as 'filtered by status', which is already inferable. Therefore, a baseline score of 3 is appropriate.

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

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

The description clearly states a specific action ('List') and a precise resource ('a country's World Bank projects') with ordering and filtering context ('newest board-approval first', 'filtered by status'). It stands apart from broader tools like search_projects by emphasizing country-scoped listing.

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

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

The description implies usage when you need projects for a specific country, but it does not explicitly mention when to use this tool versus alternatives like search_projects or get_project. No when-not guidance or alternative names are provided, so the guidance remains implicit rather than explicit.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds the key behavioral trait that the memory is 'Scoped to your identifier (anonymous IP, BYO key hash, or account ID),' which is crucial for agents to understand visibility. It also clarifies the list-all behavior when the key is omitted. No contradictions with annotations; the description supplements them well.

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

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

The description consists of three concise sentences: the first defines the core functionality, the second explains when to use it with examples, and the third covers scoping and complementary tools. Every sentence adds value without redundancy.

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

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

For a simple tool with one optional parameter, no output schema, and robust annotations, the description covers what the tool does, when to use it, how the key parameter behaves, and the scope of memory. It could mention behavior for a missing key, but given the simplicity and natural semantics of retrieval, the description is sufficiently complete.

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

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

The schema's 100% coverage of the single 'key' parameter already documents its semantics. The description enriches this by providing concrete examples of key contents (user's target ticker, address, prior research notes) and restating the omit-to-list behavior, giving agents a better sense of what keys are appropriate. This goes beyond mechanical schema details.

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

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

The description explicitly states the action ('Retrieve a value previously saved via remember, or list all saved keys') and differentiates from sibling tools by naming 'remember' and 'forget' as companions. It provides concrete examples of use cases (target ticker, address, research notes), making the purpose unmistakable.

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

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

The description gives clear guidance: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also explicitly mentions pairing with 'remember' to save and 'forget' to delete, establishing when to use this tool versus 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?

Despite annotations indicating read-only, the description discloses that mark_read:true mutates the feed's read state, a side effect beyond what annotations imply. It also explains polling behavior and the persisted-feed nature, providing valuable behavioral context that annotations do not cover.

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

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

Four sentences, each earning its place: purpose, return payload details, filtering options, and mark_read/alternative access. Information is front-loaded and there is no 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?

For a tool with no output schema, the description explains return content (source, citation_uri, raw payload), filtering, the side effect of mark_read, and alternate access via URL. All parameters are documented in the schema, and annotations cover safety. The description is complete for effective use.

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

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

Schema descriptions cover 100% of parameters, so baseline is 3. The description adds semantic value by giving a concrete example for type ('sec_8k'), explaining that since uses ISO timestamps, and clarifying mark_read's effect on subsequent calls. It does not over-explain what the schema already covers.

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

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

The description opens with a specific verb and resource: 'Pull fired events from your subscription feed.' It clearly distinguishes this tool from siblings by focusing on alerts/events from the persisted feed, with details about return payloads and filtering that set it apart from generic list or change tools.

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

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

The description implies usage context (polling for recent alerts, filtering by type/time) but does not explicitly state when to use this tool versus alternatives like list_subscriptions or recent_changes. It provides an alternative URL for scripts/dashboards, but no direct when/when-not guidance relative to sibling tools.

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

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

Beyond the readOnlyHint/idempotentHint annotations, the description discloses fan-out to multiple sources, the GDELT→GNews fallback chain, USPTO soft-fail due to PatentsView API sunset, and the return structure (changes[] grouped by source, total_changes count, pipeworx:// citation URIs). No contradictions with annotations.

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

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

The description is dense but well-structured, front-loaded with query examples. Every sentence adds value—sources, fallback, parameter formats, output summary, and alternative are all covered. It is longer than ideal but 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?

The tool is complex (multiple sources, fallback, soft-fail, parameter formats, output shape), and the description covers all essential aspects without an output schema. It states what the output contains, how to specify the time window, and when to choose a sibling tool, making it complete for correct invocation.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds meaningful detail: `since` accepts ISO dates or relative shorthand with examples ('7d', '30d', '3m', '1y'), and `value` can be a ticker or zero-padded CIK. This exceeds schema descriptions and helps agents format parameters correctly.

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

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

The description clearly states the tool provides a 'change feed for a company in the last N days/weeks/months in ONE parallel call,' enumerating specific sources (SEC EDGAR, GDELT/GNews, USPTO). It also distinguishes itself from the sibling entity_profile by contrasting dynamic changes with static profiles.

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

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

Explicitly gives trigger query examples ('What's new with X', 'latest on Y', etc.) and names an alternative: 'Use entity_profile instead when you want the static profile ... regardless of window.' It also explains source fallback behavior, which helps set expectations for when GNews is used instead of GDELT.

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

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

Annotations already indicate non-read-only, idempotent, non-destructive behavior. The description adds valuable context not in annotations: key-value scoping, persistence differences between authenticated and anonymous sessions (24 hours), and cross-session reuse. This goes beyond what annotations alone convey.

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

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

The description is compact and front-loaded with the primary action, followed by contextual use cases and pairing instructions. Every sentence earns its place 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?

Given the simple 2-parameter schema, strong annotations, and absence of an output schema, the description fully covers the necessary context: what is stored, why, persistence rules, and how it fits with sibling tools. No significant gaps remain.

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

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

Schema coverage is 100% with clear descriptions for 'key' and 'value'. The description adds conceptual meaning by explaining the key-value pair is 'scoped by your identifier' and that the value can be any text. This enriches understanding beyond the schema's basic examples.

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

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

The description states a specific verb and resource: 'Save data the agent will need to reuse later' across conversations/sessions. It clearly distinguishes itself from sibling tools 'recall' and 'forget' by defining its role as the storage operation.

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

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

It provides explicit when-to-use guidance with concrete examples ('a resolved ticker, a target address, a user preference, a research subject') and notes when not to use it by pairing with recall and forget. This is exemplary usage guidance.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description adds valuable behavioral context: cascading internal lookups, graceful degradation when GLEIF/OpenFIGI are unavailable, explicit handling of unresolved identifiers, source labelling, and ownership data inclusion for LEI. These details significantly enhance understanding of tool behavior and edge cases.

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

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

The description is well-structured with clear sections (SUPPORTED TYPES, sub-bullets) and front-loaded examples. It is somewhat long but justified given the tool's complexity in handling two entity types and multiple identifier sources. A few redundant phrases could be trimmed, but overall it remains focused and informative.

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

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

With no output schema, the description carries full responsibility for explaining return values. It does so thoroughly: for companies it lists CIK, ticker, company name, LEI, FIGI, ownership data, source labels, and unresolved handling; for drugs it lists RxCUI, ingredient, brand, and citation. It also covers failure modes (graceful degradation), making the description complete for this tool's scope.

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 schema already provides 100% coverage of both parameters, including enum values and example formats. The description adds some extra nuance (e.g., exact input forms for company type) but largely repeats schema information. Since schema does the heavy lifting, the baseline of 3 is appropriate; the description adds minimal novel 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's core function: resolving user-spoken names to canonical/official identifiers required by other tools. It lists supported entity types (company, drug) with specific identifier outputs (CIK, ticker, LEI, FIGI, RxCUI) and explicitly differentiates itself from siblings by noting it resolves names to IDs rather than profile or validation.

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 explicit 'Use FIRST whenever you have a name but need an ID' guidance, which is clear and actionable. It also notes it replaces 2-3 manual lookups, providing a strong use-case signal. However, it does not explicitly mention when not to use it or name alternative sibling tools, so it stops short of a perfect 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 readOnly, idempotent, and non-destructive behavior. The description adds useful context: it probes each entity, ranks results, and returns specific metrics (score, confidence, signal density). It does not contradict annotations and enriches understanding of the tool's behavior.

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

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

The description is concise (four short sentences), front-loaded with the primary purpose, and every sentence adds value: purpose, method, use case example, and return format. No redundancy or filler.

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

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

For a tool with no output schema, the description adequately explains the output (ranked list with score, confidence, signal density). It also conveys the use case and relationship to ai_visibility_check. Minor gap: it could explicitly mention the singular alternative for single-entity checks, but this is not critical.

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

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

Schema coverage is 100% and parameter descriptions are comprehensive, including the special role of the first entity in the 'entities' array. The tool description does not add additional parameter semantics beyond what the schema already provides, so baseline 3 is appropriate.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, with specific details on probing via ai_visibility_check, ranking, and surfacing most/least recognized. It is clearly distinct from sibling tools like ai_visibility_check (single entity) and compare_entities (generic comparison).

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 implies when to use this tool (for multi-entity comparison) vs alternatives. However, it does not explicitly state when not to use it or name alternatives, so it falls short of the highest bar.

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

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

Beyond the annotations (readOnly, idempotent), the description discloses fan-out behavior across multiple services, partial failure degradation (sources_failed), and timing variability (5-30s on first measurement). It also clarifies the NPM-only constraint, which is not evident from the schema. No contradiction with annotations.

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

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

The description is well-structured and front-loaded with the core purpose. Every sentence adds value: use cases, return fields, ecosystem limits, partial failure behavior. Despite its length, it avoids redundancy and each detail supports agent decision-making.

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

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

With no output schema, the description compensates by enumerating return fields (is_latest, license, bundle_kb_gz, etc.), per-advisory details, links, and alternative versions. It also covers partial failure and timing, making it sufficiently complete for a complex, composite tool.

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

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

Schema description coverage is 100% for both parameters (package and version). The description does not add new input semantics beyond what the schema already states—it only gives usage examples and output context. Baseline 3 is appropriate.

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

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

The description opens with a specific verb+resource+scope: "Composite 'should I add this npm package to my project' check in ONE call," and names the exact sources (deps.dev and bundlephobia). It clearly distinguishes from sibling tools by focusing on npm dependency evaluation and explicitly stating NPM ecosystem only.

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 ties usage to user intents: "Use whenever an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me'." It also provides a when-not via "NPM ecosystem only in v1" and directs non-NPM cases to "deps.dev:version directly," which serves as an 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?

Annotations already declare readOnly, openWorld, and idempotent. The description adds 'Keyless' (no authentication required), which is useful operational context beyond annotations. It also states the data fields returned, which is valuable since no output schema exists. 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, front-loaded with the action and key filters. The second sentence lists return fields and keyless access. Every clause 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 search tool with 4 optional parameters and no output schema, the description provides a good summary of behavior and return fields. It lacks explicit mention of pagination or limit defaults, but schema covers limit. Given the moderate complexity and strong annotations, this is adequately 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?

Input schema has 100% coverage with descriptions for all four parameters (limit, query, status, country_code). The description adds marginal guidance ('Provide query and/or country_code') but mostly reinforces schema content. Baseline 3 is appropriate because schema carries the 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?

Description states a specific action ('Search') with resource ('World Bank development projects') and modifiers (free text, country, status). It also enumerates return fields (financing, sectors, lending instrument, dates, status), distinguishing it from sibling tools like get_project (single project) and projects_by_country (country-based listing).

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?

Implied usage is clear: use for searching projects by text/country/status. However, there is no explicit comparison to sibling tools (e.g., 'instead of get_project use this for broad searches') or exclusions. The phrase 'Provide query and/or country_code' gives minimal usage direction but lacks explicit context for when to prefer this over alternatives.

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

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

The description adds substantial behavioral context beyond the annotations: it reveals the embedding model (BGE-base-en), windowing strategy (500-char overlapping windows), and input cap (200K chars with truncation flagged). It also notes that every passage includes an offset for quote verification, which is critical trust information. 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 dense but every sentence earns its place: it starts with the core action, then usage recommendation, then complementary tooling, then technical details. It's a single coherent paragraph with no redundancy, and the key use case 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?

Given the tool's complexity and the absence of an output schema, the description is remarkably complete. It covers what the tool does, when to use it, what it returns (passages, offsets, similarity scores), and its technical constraints (embedding model, window size, truncation). The agent has enough information to invoke 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%, so the baseline is 3. The description augments the schema by clarifying the 'text' parameter as the fetched record, providing concrete query examples, and explaining that 'limit' controls top-N passages. It does not deeply elaborate beyond the schema but adds enough context with the 'text' cap and passage-level results to merit 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 opens with 'Semantic search INSIDE a fetched record,' which is a specific verb+resource combination that immediately clarifies the tool's scope. It distinguishes itself from siblings by explaining how it pairs with ask_pipeworx_grounded, emphasizing that it searches within already-fetched content rather than fetching anew.

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

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

Explicitly states 'Use when the record is too big to cram into the prompt,' giving a clear condition for deployment. It also mentions the alternative/complement ask_pipeworx_grounded, explaining how to combine tools for grounding over relevant passages, which tells the agent when to prefer 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?

The description is exceptionally transparent, disclosing: authentication requirements, phone verification step, 10/day SMS cap, webhook HMAC signing and one-time secret return, auto-disable after 10 consecutive failed runs, and the always-on feed behavior. These go far beyond annotations (readOnlyHint=false, idempotentHint=true, etc.) and provide critical operational context. No contradiction with annotations, including the idempotentHint, since the description does not explicitly state whether repeated subscribes create duplicates.

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

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

The description is dense but well-structured and front-loaded. It starts with the core purpose and return value, then breaks down supported types and delivery channels. Each sentence adds meaningful information—no filler, repetition, or fluff. Despite its length, it earns every word for a tool with nested objects and multiple behaviors.

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

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

With no output schema, the description appropriately states 'Returns the new subscription id.' It also covers authentication prerequisites, all delivery channels (feed, email, sms, webhook) with specific details like phone verification and signing secrets, and operational limits (10/day cap, auto-disable). For a moderately complex tool with nested params, this description is completely sufficient 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?

Schema description coverage is 100%, so baseline is 3. The description adds value by giving concrete examples for type-specific params (e.g., items:["5.02"] = officer change for sec_8k, topic:"fed" for polymarket_edge) and clarifes delivery semantics (email templated alert, sms must match verified phone, webhook signing secret returned once). This goes beyond a mere restatement of schema properties.

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

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

The description opens with 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' This clearly identifies the verb (create), resource (subscription), and output. It distinguishes from siblings like list_subscriptions and unsubscribe by focusing on creation and returns. The enumeration of supported subscription types further clarifies 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 states the prerequisite 'Requires a Pipeworx OAuth account (anonymous + BYO cannot persist subscriptions)' and explains delivery channels including the always-on feed as an alternative to pull via recent_alerts. It does not explicitly name alternative tools for when not to subscribe, but the context is clear enough that the agent can decide appropriately. Lacks explicit exclusions, hence 4.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, providing a safe, read-only profile. The description adds behavioral details: returns category-bucketed examples, all from the live catalog, and varying output based on the optional topic parameter. No contradictions with annotations. It could have added more about potential response size, but the annotations cover the critical safety aspects.

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

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

The description is dense but every sentence earns its place. It front-loads with natural language examples, then states the core function, return format, and parameter behavior. It could be split into cleaner sentences, but it is not bloated or repetitive. The structure supports quick scanning by an AI agent.

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 no output schema, the description fully covers what the agent receives (category-bucketed examples with tool+argument shape), how to use the parameter, and when to invoke it. It also explains how it relates to meta-tools like ask_pipeworx. Given the tool's simple scope, this is complete and self-sufficient.

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

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

Schema coverage is 100% for the single optional 'topic' parameter, which already lists valid focus areas. The description adds real value by explaining that omitting the argument gives a full cross-category spread versus passing a topic to focus, and gives concrete examples ('finance', 'pharma', 'betting'). This clarifies the parameter's effect beyond the schema's static list.

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

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

The description clearly identifies the tool as the onboarding entry point for an agent, with a specific verb (suggest questions) and resource (what to ask Pipeworx). It distinguishes itself from siblings by stating it returns category-bucketed example questions with the exact tool+argument shape, and by framing itself as the 'FIRST' tool to use when unfamiliar with Pipeworx. This is far more specific than a generic 'suggest ideas'.

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

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

The description explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' This provides clear when-to-use guidance. It doesn't explicitly name alternatives like discover_tools, but the context strongly implies this is the initial discovery mechanism. A small deduction for not explicitly stating 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 the annotations (which already indicate mutation and non-destructive), the description adds critical behavioral context: ownership enforcement and the deactivation-vs-deletion distinction, pointing to recent_alerts for historical data.

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

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

Two sentences, front-loaded with the core action in the first sentence. Each sentence adds value: the first says what it does, the second explains the behavioral nuance.

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

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

The description explains the ownership constraint, the non-destructive behavior, and where historical data remains. For a simple cancellation tool with annotations, this is sufficiently complete. It does not describe the return value, but that's not essential here.

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 schema already fully documents the single 'id' parameter with a meaningful description (returned by subscribe). The tool description adds little parameter semantics, but given 100% schema coverage, this is acceptable per 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 uses a specific verb ('Cancel') and a clear resource ('a subscription by id'), distinguishing it from 'subscribe' and 'list_subscriptions' siblings. It also clarifies the outcome (deactivated, not deleted), which eliminates 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?

The context is clear: it's the tool to cancel a subscription you own. It doesn't explicitly mention alternatives, but the ownership constraint and the note about historical events provide sufficient guidance. Lacks explicit 'use when' but is evident from the title and description.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description adds critical behavioral nuance: it explains that 'could_not_verify' means the check did not occur and must not be treated as evidence, and it distinguishes 'unsupported' as a coverage gap. It also details the two verification paths and the return structure (verdict, value, citation, reasoning), providing rich behavioral context beyond the annotations.

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

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

The description is a single dense paragraph but every sentence carries weight: trigger phrases, usage directive, routing logic, return values, and critical caveats. It is appropriately sized for the tool's complexity, though it could benefit from slight restructuring (e.g., separating the 'IMPORTANT' caveat into a distinct note) to improve scannability.

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

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

Given the tool's complexity (two pipelines, multiple verdict types, error semantics), the description is exceptionally complete. It explains what the tool returns, how it handles failures (could_not_verify vs. unsupported), and why it is valuable (replaces multiple steps). No output schema exists, so the description correctly carries the full burden of explaining return values and 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?

The schema covers 100% of the parameters with descriptions, so the baseline is 3. The description does not add parameter-specific details beyond what the schema already provides (e.g., tolerance_pct is only implied via 'percent-delta math'), and it does not explain how the 'claim' string should be formatted beyond examples in the schema. Thus it meets but does not exceed the baseline.

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

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

The description clearly identifies the tool as a natural-language claim verification tool, with explicit trigger phrases and a specific verb+resource framing ('verify the claim'). It distinguishes itself from siblings by detailing the two distinct verification paths (structured SEC EDGAR for company financials vs. grounded pipeline for all other claims), making its purpose and scope unmistakable.

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

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

The description gives a direct usage directive: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains the routing to different pipelines and notes that it replaces 4–6 sequential calls, implying efficiency. However, it does not explicitly name alternative tools or state when NOT to use this tool, so it falls short of the highest bar.

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