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 cover read-only, idempotent, open-world, and non-destructive behavior. The description adds useful behavioral context: it routes to the right sub-tool, fills arguments automatically, returns structured answers with stable citation URIs, and is a single fast call. It does not detail failure modes or rate limits, but the annotation safety profile lowers the burden.

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 sentence earns its place: it front-loads the primary directive, gives trigger phrases, provides six concrete examples, and includes step-up routing to siblings. The structure moves from priority claim to scope to invocation guidance to alternatives, making it easy for an agent to act on.

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-required-parameter default tool, the description is nearly complete: it explains what kinds of questions to send, what the tool does internally, what output shape to expect (structured answer + citation URIs), and when to escalate to siblings. It stops short of describing error/fallback behavior for unsupported questions, which would make it fully 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 already documents the one meaningful parameter and its aliases at 100% coverage, so the baseline is 3. The description adds real meaning beyond the schema by defining the acceptable semantic scope: factual questions about real-world entities, events, numbers, and authoritative structured data, plus concrete example phrasings that an agent can pattern-match.

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 a specific verb ('routes'), a resource (5,743 tools across 1,500 verified sources), and a result (structured answer with pipeworx:// citation URIs). It distinguishes itself from web search and from siblings like ask_pipeworx_grounded and deep_research by positioning itself as the default entry point.

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: 'PREFER OVER WEB SEARCH', 'Use whenever the user asks...', and 'START HERE for most questions'. It also names alternatives and exact step-up conditions: ask_pipeworx_grounded for hallucination-resistant single answers, and deep_research for broad/multi-part questions.

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

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

Beyond the annotations (read-only, idempotent, open-world), the description reveals live behavioral variability: candidate routing improvements may be enabled during tests, and as of a specific date no candidate is active, making it identical to ask_pipeworx. This gives useful context about potential future behavior changes without contradicting any annotation.

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

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

The description is composed of four tight sentences, each contributing essential information about the beta status, current parity, usage, and fallback guarantee. It is slightly redundant in mentioning 'identical' and 'same arguments' but remains efficient and well-structured.

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

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

The description covers the tool's relationship to ask_pipeworx, the live-testing nuance, and the absence of fallback, which is sufficient for a single-required-parameter router. The response shape is mentioned as identical to ask_pipeworx but not detailed; since this references a sibling, it's an acceptable minor gap.

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, with all six parameters documented as aliases for the required 'question'. The description adds no additional parameter-specific meaning, but this is fully acceptable given the schema alone is sufficient; 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 explicitly identifies the tool as a beta version of ask_pipeworx, a universal router over 5,743 tools, with identical arguments and response shape. It clearly distinguishes itself from the stable sibling by noting the experimental routing improvements and current parity when no candidate is active.

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 when to use it: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also contrasts with the stable router and clarifies it is a full working router, so an agent knows it can rely on it despite the experimental edge.

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

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

Discloses substantial behavior beyond the annotations: refusal modes, success/refusal return shapes, the constraint that the answer uses only the tool result, and the extra LLM call cost. Annotations already mark it read-only, idempotent, and non-destructive, so the description adds meaningful operational context without contradicting them.

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

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

Dense but purposeful: front-loads the core value, then the mechanism, return contract, usage, and tradeoff. Every sentence earns its place; no filler or repetition of schema or annotation content.

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?

Complete for a complex read-only query tool: it explains what the tool does, how it behaves, what it returns on both success and refusal, when to prefer it, and when to avoid it. With no output schema, the description fully carries the burden of return-value documentation.

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

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

Schema coverage is 100% and the schema already documents the question parameter and aliases clearly. The description does not add further parameter-level meaning, so the baseline of 3 is appropriate.

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

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

States a specific purpose: a hallucination-resistant answer mode that extracts answers only from tool results. Explicitly differentiates itself from ask_pipeworx by naming it and explaining the shared routing plus the added extraction step.

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: for high-stakes, quotable, cited, or acted-on answers where facts must not be invented. Also gives the alternative directly: prefer ask_pipeworx for casual lookups, including the cost tradeoff of one extra LLM call.

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

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

Annotations 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?

Annotations already signal readOnly/idempotent/non-destructive, but the description goes far beyond: it discloses account requirements, paid-plan implications, parallel decomposition, findings packet contents, gap reporting, the 'never invented' guarantee, contradiction detection, semantic excerpting, and expected latency. This is a model of behavioral transparency and does not contradict 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 but information-dense, and it front-loads the critical account requirement and core differentiator. Some redundancy exists around citations and hops (mentioned twice in different forms), but every sentence contributes meaningful operational detail, which justifies the length for such a complex tool.

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

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

Despite having no output schema, the description thoroughly describes the return envelope: findings with verbatim evidence, confidence, source, fetched_at, citation_uri, gaps[], contradictions[], and hop fields. It also covers latency, depth variants, and fallback tools, making the tool fully actionable for an agent without external documentation.

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

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

Schema coverage is 100%: both 'question' and 'depth' are fully described in the input schema. The description adds behavioral nuance about depth levels (e.g., gap recovery, contradiction scan), but the core parameter semantics are already carried by 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 states a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1500 STRUCTURED data sources... in ONE call.' It also explicitly differentiates itself from ask_pipeworx for single lookups and breaking-news scenarios, so an agent can distinguish it from siblings without opening their schemas.

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: best for broad/multi-part questions over structured data, with concrete examples. It names ask_pipeworx as the alternative for single lookups and current-news topics, and even provides an account-level rule ('If you are not signed in, use ask_pipeworx instead'). This is exemplary routing 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 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?

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior, so the bar is lower, but the description adds substantial behavioral context beyond annotations: it fans out across multiple sources, returns specific field structures, soft-fails on the USPTO API sunset, reports sources_used/sources_failed, and clarifies that an empty section means real 'no data'. This gives the agent accurate expectations for both success and failure modes.

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

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

The description is long, but every sentence earns its place by documenting a distinct source, failure mode, or return shape. It is front-loaded with trigger phrases and a clear preference directive, and the detailed enumerations are necessary because there is no output schema.

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 must carry the full burden of explaining return fields and behaviors, and it does. It covers input formats, source coverage, resolution behavior for private companies, expected empty results, failure semantics for the USPTO API, and how sources_used/sources_failed should be interpreted. Nothing an agent needs to invoke this correctly 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%, but the description enriches both parameters with concrete examples ('AAPL', '0000320193', 'Moderna'), explains that names resolve via SEC EDGAR's company-name match, and clarifies that 'type' accepts interchangeable values. This goes meaningfully beyond the schema's own property 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 concrete trigger phrases and a clear verb phrase: 'full cross-source profile of a US public company in ONE parallel call.' It distinguishes itself from chaining single-pack SEC/XBRL/news lookups and from siblings like deep_research and resolve_entity by explicitly stating its single-call holistic 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?

It says exactly when to use it: when the user asks for a holistic view of a US public company, and explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups.' It also covers edge cases: private companies return resolved:false with an explicit notes line, and empty data sections are expected, not failures.

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?

Annotations already declare readOnly/idempotent/openWorld, and the description adds substantial behavioral disclosure: pairing is keyword-based and unverified, compatibility_codes can be non-empty even on returned pairs, temporal_alignment null means unknown rather than aligned, and spreads are gross of Kalshi fees. 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?

The description is long but well-structured with labeled sections (MODES, RESPONSE, SAFETY FIELDS, fees, counters) and a clear front-loaded purpose. There is some redundancy—temporal_alignment_unknown and pairing_unverified are explained multiple times—which prevents a perfect score, but each major section earns its place given the tool's complexity.

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

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

There is no output schema, so the description carries the full burden of explaining return values, and it does so thoroughly: leg prices, top_spreads_pp, compatibility_warning/codes, flags[], skipped_unclassified, temporal_alignment, skipped counters, and fees_note. It also warns about empty/unverified results and what each warning flag means, leaving no essential call-time ambiguity.

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 adds the full topic enum list, explains that explicit ticker/slug values override the topic-mapped side, and stresses that both modes run the identical matching logic. This is meaningful semantic context beyond the schema's simple field 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 opening sentence states exactly what the tool computes: a cross-venue spread between Kalshi and Polymarket for the same resolving question. It names both venues, the object of comparison, and the notion of resolution alignment, distinguishing it from Polymarket-only sibling tools. This is a specific verb+resource statement, not a 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 defines two explicit invocation modes (topic vs explicit kalshi_event_ticker + polymarket_event_slug) and explains when each is appropriate. It gives clear usage context, including that pre-mapped topics are not automatically tradeable, but it does not explicitly name sibling alternatives or exclusion 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?

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 readOnlyHint/idempotentHint annotations, the description richly discloses behavior: graceful degradation if GLEIF/OpenFIGI is unavailable, the figi_candidates behavior when a name matches multiple instruments, explicit unresolved identifiers rather than omission, acceptance of ticker/CIK/ISIN/name inputs, and internal cascading lookups. These details are substantive and align with 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 but front-loaded with the key directive and example queries before diving into details. Every sentence adds useful information, such as edge cases, degredation behavior, and return semantics. It is not as tight as a two-sentence summary, but the density justifies most of the length.

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

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

With no output schema, the description carries the full burden of explaining return behavior. It does so thoroughly: for drugs it lists RxCUI, ingredient, brand, and citation; for companies it covers figi_candidates, unresolved identifiers, and graceful fallback. Given the tool's complexity, the description leaves no critical operational question unanswered.

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 has 100% coverage with descriptions for both parameters, but the tool description adds substantial value: it explains the meaning of supported types (company vs drug), gives examples for the value parameter, warns against passing full noun phrases for bonds, and clarifies input forms like ISIN. This goes well beyond the schema's baseline.

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

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

The description clearly states the verb and resource: resolve a user-spoken name to canonical/official identifiers required by other tools. It includes example queries that make the purpose unmistakable. However, it does not explicitly name sibling alternatives or differentiate itself from tools like entity_profile or compare_entities, 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 gives explicit when-to-use guidance: "Use FIRST whenever you have a name but need an ID," and provides concrete example phrasings. It does not, however, state when not to use the tool or name alternative tools for other situations, so it lacks the full when-not/alternatives coverage.

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.