Pdbe

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

Annotations indicate read-only, open-world, idempotent, non-destructive behavior. The description adds that probing is performed on LLMs, results include per-model data, and Anthropic calls require a user-provided key and are paid directly. No contradiction, and it provides useful context beyond annotations.

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

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

The description is front-loaded with the main action and return format. At about 100 words, it is succinct but still informative. Minor redundancy: 'useful for' could be trimmed, but overall no wasted sentences.

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

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

No output schema, but the description fully details the return structure: per-model {score, confidence, signals, raw_response} plus a combined view. It also explains when to use _apiKey and context parameter. The tool has moderate complexity, and the description covers all necessary aspects.

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

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

Schema description coverage is 100% with all 4 parameters described. The description adds meaning by explaining the default model, how _apiKey enables Anthropic probing, and the purpose of context for disambiguation. This adds value beyond schema alone.

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

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

The description clearly states the tool's purpose: probing LLMs for knowledge about an entity and scoring visibility (0-100). It specifies the default model and how to add paid models. This distinguishes it from sibling tools like ask_pipeworx or deep_research which serve different Q&A or research functions.

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

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

The description provides clear usage contexts such as AI-marketing audits, pre-launch brand checks, and competitive monitoring. It explains how to customize probing with models and API keys, but does not explicitly contrast with alternatives like deep_research or compare_entities. The guidance is strong but could be more explicit about when not to use.

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

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

Annotations already mark this as read-only, open-world, and idempotent; the description adds that the tool fills sub-tool arguments automatically, returns structured answers with stable citation URIs, and is grounded with citations. It also discloses the constraint that only one question may be sent per call. No contradiction with the annotations exists.

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-loads the core directive and organizes routing guidance by trigger phrases, examples, sibling alternatives, and exclusions. Some redundancy exists between 'PREFER OVER WEB SEARCH', 'START HERE', and 'When in doubt, use this tool over web_search', but the length is largely justified by the tool's broad routing responsibility.

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 broad meta-tool with no output schema, the description covers applicable domains, trigger language, examples, routing to siblings, exclusions, and a single-question call constraint. It also tells the agent what to expect from the result: a structured answer with stable pipeworx:// citation URIs. This is sufficient for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, so the schema already documents the question parameter and its aliases. The description adds meaning beyond the schema by specifying that the tool fills arguments itself and that calls must contain a single question, not a list. This is useful guidance for how to populate the required parameter.

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

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

The description opens with 'PREFER OVER WEB SEARCH' and names a specific action: routing a natural-language question to one of 5,798 tools across 1,517 verified sources and returning a structured answer with stable pipeworx:// citation URIs. This clearly distinguishes it from generic web search and from related siblings such as ask_pipeworx_grounded or compare_entities.

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

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

The description explicitly states when to use the tool ('Use whenever the user asks...'), provides trigger phrases and concrete examples, and enumerates which sibling tool to choose for alternative cases, including grounded answers, entity comparisons, claim validation, rankings, deep research, exact quotes, and memory-based questions. It also gives an exclusion list for decisions, personal advice, and account requests.

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, the description reveals that this is an experimental edge with candidate routing improvements enabled live, that no candidate is currently active, and that it is a full working router with the same response shape as ask_pipeworx. This is valuable behavioral context not captured in the annotations, especially the live variability and current equivalence to the stable router.

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 longer than strictly necessary but every sentence carries distinct information: beta relationship, tool scope, current state, usage instruction, and non-stub confirmation. It is front-loaded with the key identity and ends with a clarifying fallback statement. The dated retirement detail is mildly extraneous but does not undermine clarity.

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

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

For a beta router, the description provides sufficient context: purpose, relationship to the stable version, current state, and usage directive, with safety covered by annotations. It reasonably references ask_pipeworx for response shape and arguments instead of re-listing them, and no output schema exists. It could be more explicit about when not to use it (e.g., for guaranteed stable routing), so it is not 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 input schema already provides 100% coverage with alias descriptions for all six parameters, so the schema documents the semantics. The description only adds a cross-reference that arguments are identical to ask_pipeworx, which is useful but not essential. Baseline 3 is appropriate given the high schema coverage.

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 beta variant of ask_pipeworx, a universal router over 5,798 tools, and distinguishes it from the stable sibling by its experimental routing edge. It states a specific function (routing a question) and even clarifies the current behavior (matches ask_pipeworx), leaving no ambiguity about what the tool is.

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 says 'Use it exactly like ask_pipeworx when you want the newest routing', naming the stable alternative and the condition that selects this tool. It also explains that results are compared against the stable router, so an agent understands the contextual role. The clarification that it is a full working router prevents misuse as a stub or fallback.

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?

Goes well beyond the readOnly/openWorld/idempotent annotations by disclosing the full output contract ({answer, evidence, confidence, source, fetched_at, refusal_reason:null}), the explicit refusal shape with all five enumerated refusal_reason values, the extract-verbatim-quote behavior, and the refusal-when-uncertain guarantee. Also discloses the cost behavior (extra LLM call). No contradiction with annotations.

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

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

Four dense sentences organized as identity → mechanism → output contract → usage guidance, front-loaded with the key differentiator. The refusal-reason enumeration is slightly long but genuinely useful given there is no output schema. Minor repetition of the no-hallucination concept, but no wasted sentences.

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 bears the return-value burden — and it delivers: success shape, refusal shape, all five refusal reasons, the routing mechanism, and the use-case boundary versus ask_pipeworx. Annotations cover safety (read-only, idempotent, non-destructive), so 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 description coverage is 100% — the schema already documents the 'question' parameter and all five aliases (query, q, prompt, text, input). The description adds only the framing that the question drives routing across 5,798 tools, which is mild contextual value. The baseline 3 applies since the schema does the heavy lifting.

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 function — a hallucination-resistant answer mode for grounded reads — with a clear verb+resource ('ask Pipeworx', grounded), and distinguishes itself from ask_pipeworx by the extraction-only-from-result behavior and the extra LLM call cost. An agent can tell this apart from ask_pipeworx and ask_pipeworx_beta without opening 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?

Explicitly names the alternative (ask_pipeworx), the exact conditions for choosing this tool (answers quoted, cited, or acted on; high-stakes domains like financial, legal, medical, public statements), and the exclusion condition ('prefer ask_pipeworx for casual lookups'). Also quantifies the tradeoff with 'costs 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?

Extensive disclosure of behavioral traits beyond annotations: describes resolver contract (market_match_confidence), parent event extraction, news fallback mechanisms, safety short-circuits for low-confidence/closed markets, spread warnings, and cancellation rule parsing. Annotations already indicate read-only/idempotent, and the description adds rich operational context.

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

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

The description is very long and dense with information. While front-loaded with a clear summary, the level of detail makes it less concise. Each sentence earns its place, but the overall length could be reduced by grouping related details more tightly.

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 (multi-step fan-out, multiple edge cases), the description covers all critical aspects: input resolution, classifier list, fan-out examples, response structure, safety mechanisms, and cancellation rules. No output schema exists, but the description compensates by detailing response fields. It is complete for agents to use correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description enriches parameter meaning: for 'depth' it explains quick vs thorough, for 'include_raw' it details what raw includes and how it affects response size. It adds examples for 'market'. This extra context justifies a 4.

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

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

The description clearly states the tool's core function: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input types (slug, URL, question text) and outputs (evidence packet + market-vs-model comparison). The purpose is distinct from siblings like 'ask_pipeworx' or 'polymarket_arbitrage' by focusing on comprehensive research for individual bets.

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 cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' Also includes when-not scenarios, e.g., low-confidence resolutions short-circuit. However, it does not explicitly name alternative tools for specific situations, which would elevate the score further.

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

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

Annotations already indicate readOnlyHint=true and idempotentHint=true. The description adds valuable behavioral details: it makes a single parallel call, handles off-calendar fiscal years correctly, returns results sorted by primary metric, and includes citation URIs. It also describes the specific data pulled for each type. This goes well 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 concise, consisting of two sentences. It front-loads with common user queries, then efficiently conveys the tool's purpose, usage preference, data sources, and behavior. Every sentence adds value; no redundancy.

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

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

With no output schema, the description explains return data (paired data + citation URIs, sorted by primary metric). It covers entity types, data sources, and constraints. While it omits details like error handling or pagination, it provides sufficient context for an agent to use the tool effectively given its simplicity.

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

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

Schema coverage is 100%, so parameters are fully described in the schema. The description adds meaning by providing examples ('company' vs 'drug', tickers vs drug names), clarifying the 2–5 item constraint, and explaining the data each type retrieves. This adds context not in the schema.

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

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

The description starts with natural language queries like 'Compare X and Y' and 'which is bigger / better', then explicitly states 'side-by-side comparison of 2–5 companies or drugs'. It clearly identifies the action (compare) and the resource (entities), and distinguishes itself from sequential lookups, 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 explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing clear guidance on when to use this tool. It also explains the data sources for each entity type. However, it does not explicitly state when not to use it (e.g., for a single entity lookup).

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 read-only, open-world, and idempotent hints, the description discloses account/paid-tier requirements, parallel routing across 5,798 tools, the findings packet shape, gaps[] semantics, fetchable citations, contradiction scans, semantic excerpting, and latency expectations. It adds substantial behavioral context without contradicting 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 dense but every sentence earns its place, and the access gate plus sibling alternative are front-loaded. Some sentences are long and parenthetical-heavy, but the overall order is logical: account requirement, core mechanism, output contract, depth behavior, performance.

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 specifying the return contract: verbatim evidence, confidence, source, fetched_at, pipeworx:// citations, gaps[], contradictions[], and excerpting behavior. It also covers auth, paid tiers, and latency, leaving an agent well-equipped to invoke and interpret results.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real value beyond the schema. It clarifies that the question can be broad/multi-part and that depth controls single-hop versus gap-recovery versus lead-chasing iterations, extending the enum descriptions in the schema.

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

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

The description states a concrete operation: grounded multi-source research across Pipeworx's 1517 structured data sources, with decomposition and parallel routing. It explicitly distinguishes itself from open-web search and from ask_pipeworx, so an agent can tell it apart from siblings.

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 gives the account gate and says to use ask_pipeworx instead when signed out. It also defines the intended use ('broad/multi-part questions over structured data') and explicitly excludes single lookups, directing those to ask_pipeworx. Depth tiers are documented with their trade-offs.

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

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

Annotations already indicate read-only, idempotent, non-destructive. The description adds concrete behavioral details: returns tools with names, descriptions, full input schemas, and curated examples, ready to call directly. No contradictions with annotations.

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

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

The description is front-loaded with purpose, then lists domains, then explains output and usage. Every sentence adds value; no wasted words. It is efficient and well-organized.

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

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

Given complexity (6 parameters but simple aliases, no output schema), the description fully covers what the tool does and returns. It even notes that results are ready to call without a second lookup, which is critical for agent workflow.

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 6 parameters with 100% coverage, describing each as an alias for 'query'. The description adds value by explaining these aliases and providing natural language examples. Baseline 3 is slightly exceeded due to clarifying alias behavior.

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

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

The description explicitly states the tool finds tools by describing data/task, lists specific domains (SEC filings, FDA drugs, etc.), and clarifies it returns top-N relevant tools with full schemas ready to call. It clearly distinguishes itself as a discovery tool among many siblings.

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 guidance: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This tells the agent when to use it and its primary role in the 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 establish read-only, open-world, idempotent, and non-destructive behavior, but the description adds substantial behavioral detail beyond that: it fans out across named sources, returns resolved_from/resolved_to, provides URI-bearing filings, and explains that sources_failed/sources_used distinguish real 'no data' from bugs. The empty-section explanation and private-company resolved:false note are exactly the kind of behavioral transparency an agent needs.

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 it is dense with necessary information: examples, source list, return fields, failure semantics, and input rules. It is front-loaded with the primary purpose and usage trigger, then moves to return details and edge cases. It could be slightly more scannable, but virtually every sentence contributes to correct tool use.

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 must explain what the agent will receive, and it does: CIK/company_name, resolved_from/resolved_to, recent_filings URIs, key fundamentals, sources_used/sources_failed, and the private-company behavior. It also covers source-specific caveats and the type/value contract. For a broad tool of this complexity, the description is remarkably complete for selection and invocation.

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

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

The input schema already covers both parameters at 100%, including enum values and descriptions. The description adds value by giving concrete examples ('AAPL', '0000320193', 'Moderna'), clarifying zero-padded CIKs, and explicitly stating that type='company' and type='ticker' are interchangeable. This goes beyond the schema, though the schema already carries most of the semantic weight.

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 user phrasings and immediately states the core action: 'full cross-source profile of a US public company in ONE parallel call.' It is specific about the resource (US public company), the output (multi-source profile), and how it differs from chained single-pack lookups. The examples of ticker, CIK, and company-name inputs further pin down exactly what the tool accepts.

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

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

The description explicitly says to 'ALWAYS PREFER' this tool over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view. It also specifies accepted input forms and what happens for private companies, giving an agent clear conditions for when the tool will succeed vs. return resolved:false. This is direct, actionable 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?

Annotations already indicate destructive (destructiveHint=true) and idempotent (idempotentHint=true) behavior. The description adds context about clearing sensitive data, which is valuable beyond annotations, but does not contradict 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?

Two concise sentences, front-loaded with the action and resource, followed by usage and pairing guidance. No wasted words.

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

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

Given the simplicity of the tool (one parameter, no output schema, clear annotations), the description fully covers purpose, usage, and behavioral context. No gaps remain.

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

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

Only one parameter 'key' with a clear description in the schema (100% coverage). The description does not add new semantics 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 clearly states the verb 'Delete' and the resource 'a previously stored memory by key', making the tool's action unambiguous. It also distinguishes itself from siblings by mentioning 'remember' and 'recall'.

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

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

Explicitly states when to use the tool (context stale, task done, clear sensitive data) and suggests pairing with siblings, providing clear guidance on alternatives.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral details: fetches the page, extracts title/description/key links, and emits standard llms.txt markdown. No contradictions.

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

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

The description is three concise sentences, front-loaded with the purpose, and wastes no words. It effectively communicates what the tool does without unnecessary elaboration.

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

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

Despite no output schema, the description specifies the output format (standard llms.txt markdown, single text blob) and covers input parameters adequately. The tool is simple and the description is complete for its 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 schema already documents both parameters. The description adds no new details beyond what's in the schema, warranting 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 clearly states the tool generates an llms.txt file for a URL, specifying the verb 'generate' and resource 'llms.txt'. It distinguishes from sibling tools like 'ai_visibility_check' by focusing on a specific output format for AI crawler indexing.

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

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

The description explicitly lists use cases: getting a client's site indexed, drafting for own project, or auditing competitor. It provides clear context but does not explicitly state when not to use it, which is acceptable given the focused purpose.

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

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

Beyond annotations (readOnly, openWorld, etc.), description adds key details: keyless access, source (PDBe/EBI), and return fields, enhancing transparency.

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

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

Two sentences with no waste; critical information (purpose, input, output) is front-loaded and efficiently presented.

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

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

Despite no output schema, description sufficiently describes return fields. With one simple parameter, the tool is fully specified for an agent.

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

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

Schema covers 100% of parameters with description, and description only reiterates the example, adding no new semantics beyond what's in schema.

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

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

The description clearly states the tool lists molecules/entities in a PDB structure with specific fields, distinguishing its purpose from siblings that are unrelated.

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 context on when to use (need molecule info from PDB) and input format (4-char PDB id), but lacks when-not or alternatives, though siblings are unrelated.

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

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

Annotations already indicate readOnly, idempotent, and non-destructive behavior. The description adds useful context: no auth needed ('keyless'), and enumerates the return fields. No contradiction; it supplements the annotations 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 is very concise—two sentences plus a brief note—while covering purpose, input, output, and source. Every sentence adds value, and key information (purpose, fields, example) 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 one parameter, high schema coverage, and annotations, the description fully covers the tool's purpose, input, and output fields. No output schema exists, but the description lists what the summary includes, making it self-contained.

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

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

Schema coverage is 100% with a clear description of pdb_id. The description reinforces this with an example ('1cbs'), but adds no new semantic meaning beyond what the schema already provides.

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

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

The description clearly states the tool retrieves a PDB entry summary with specific fields (title, experimental method, release date, source organism, entity counts) and specifies the input format (4-char PDB ID). It distinguishes itself by naming the source (EBI) and contrasting with RCSB PDB.

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

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

The description mentions the tool is the EBI counterpart to RCSB PDB and is 'keyless', implying no authentication needed, but does not provide explicit guidance on when to use this tool over alternatives or any exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds return fields and active filter context, enhancing agent understanding without contradiction.

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

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

Two sentences, front-loaded with action, no unnecessary words. Every sentence adds value.

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

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

Given no output schema, description lists return fields. With good annotations and simple tool, it is sufficiently complete 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 coverage is 100% for the single parameter. Description mentions 'active subscriptions' but the parameter include_inactive is already described in schema. No additional value beyond 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?

Clearly states 'List the caller's active subscriptions' with specific verb and resource. Distinguishes from siblings subscribe and unsubscribe by being a read-only list 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?

Explicitly advises using this tool to review subscriptions before adding more or to find an id to cancel. Does not explicitly state when not to use, but context is clear.

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

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

Beyond the annotations (all false), the description discloses important behavior: rate-limiting to 5 per identifier per day, that it's free and doesn't count against tool-call quota, that the team reads digests daily, and that filing without an account returns a claim_token for later status checks. This is valuable operational context that annotations alone do not 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 longer than average but every sentence earns its place: use cases, exclusions, claim_token behavior, rate limits, and quota impact. It is front-loaded with the core purpose and uses clear, scannable bullet-like phrasing even without bullets. Some redundancy exists (e.g., mentioning 'broken, missing, needs to exist' alongside 'bug, feature/data_gap'), but it is minor.

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

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

Given that there is no output schema and no required parameters, the description covers the main operational needs: what to submit, how to follow up, rate limits, and scope restrictions. It could be slightly more explicit about what a successful submission returns for an authenticated user, but the claim_token explanation largely fills this 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?

Schema description coverage is 100%, giving the baseline 3. The description adds extra semantic value by explaining the claim_token lifecycle ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})') and reinforcing the intended use of context fields (tool, pack, vertical). It does not repeat obvious 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 opens with a clear, specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It then enumerates exact feedback types (bug, feature/data_gap, praise) and explicitly distinguishes from sibling tools by limiting scope to tools served by this Pipeworx connection.

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

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

The description provides explicit when-to-use triggers (tool returns wrong data, wants a new tool, etc.) and a clear when-not-to-use case: feedback about tools from other MCP servers should be filed elsewhere. It also details the claim_token follow-up workflow, giving agents a complete decision path.

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

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

Annotations already provide readOnlyHint, idempotentHint, etc. The description adds valuable behavioral context: data derived from CF analytics engine, no PII, and caching behavior ('Cached 5min-1h depending on window'). 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 three sentences, each earning its place: first sentence states functionality, second lists use cases, third provides technical details. Information is front-loaded and no redundant 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?

Given the tool has one optional parameter with good schema description and no output schema, the description adequately covers inputs, behavior, and output (returns top tools, top packs, total call volume). No gaps for the complexity level.

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% (one parameter with enum and description). The description reinforces the parameter semantics by explaining the trade-off between window sizes, adding context beyond the schema's brief description. Could be slightly improved by mentioning default value explicitly (though it is implied).

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

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

The description clearly states the tool returns 'top tools, top packs, and total call volume' over a recent window, which is a specific verb+resource pair. It distinguishes itself from sibling tools (e.g., discover_tools) by focusing on trending/popularity data rather than 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 explicitly lists three use cases: discovering hot data sources, confirming canonical tool choice, and aligning use cases with agent behavior. It also explains when to use different window sizes ('shorter windows surface what's hot right now; longer windows show steady-state demand'). No explicit when-not-to-use, but the use cases are clear and comprehensive.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds extensive behavioral details: partition checks, semantic anchor Jaccard threshold, partition filter with placeholder detection, fill check with CLOB depth and realizable edge, and response structure. This goes far beyond annotations.

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

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

The description is well-structured with clear organization: overall purpose, then each mode in separate paragraphs. It is front-loaded with the main concept. While somewhat verbose, the detail is justified by tool complexity. A slightly more concise summary could improve readability.

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

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

Despite no output schema, the description thoroughly details the response format (opportunities array with fields, partition_check details, fill check). It covers all major aspects of the tool's behavior across modes, making it self-contained for an AI agent.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds context: explicit examples of event slugs and topic seed questions, and explains behavior when no args are passed. This adds meaningful value beyond the schema.

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

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

The description clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes between three modes (no args, event, topic) and explains each, differentiating it from sibling tools like polymarket_fill_risk 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?

Explicit guidance is provided for when to use each mode: no args for trending scan, event for a specific market, topic for cross-event scan. It recommends event for specific markets and explains the difference. Could be improved by explicitly stating when not to use, but overall clear.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint as true and destructiveHint false. The description adds substantial behavioral details: three model families with specific formulas, caching behavior (1h at KV level), output structure with diagnostics, and tradeable-edge knobs. 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 and dense, covering many details in a single paragraph. While every sentence adds value, the structure could be improved (e.g., bullet points) for better readability. It is not overly verbose given the tool's complexity, but it could be more concise.

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

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

The description thoroughly explains the output structure (by_segment, diagnostics) and caching, compensating for the lack of an output schema. It covers all aspects needed for an agent to understand the tool's behavior and return values, making it complete.

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

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

Schema description coverage is 100%, so each parameter already has a description. The tool description does not add significant meaning beyond what the schema provides; it mostly repeats or references them in context. Baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' and provides a use case. However, it doesn't explicitly distinguish this tool from siblings like polymarket_arbitrage or polymarket_edge_tracker, leaving some ambiguity about when to choose this over alternatives.

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

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

The description gives context ('what should I bet on today') and explains knobs for filtering, but it does not provide explicit guidance on when to use this tool versus alternatives or conditions under which it should not be used. The context is clear but without exclusions.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds rich behavioral context: it reads from daily snapshots with a 60-day TTL, decay numbers come from daily closes (net of slippage), not intraday, and explains the response structure in detail. 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 detailed and front-loads the core purpose, but it is somewhat verbose. The response structure is embedded within the description, which is helpful but makes it longer than necessary. It could be more concise while still providing essential 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?

With no output schema, the description thoroughly explains the response structure (tracked[], expired[], snapshot_dates[]) and lists fields like first_seen, trend, decay_pp_per_day. It also covers limits (60-day TTL, snapshot gaps, decay from daily closes). This is very complete for a read-only tool with two optional parameters.

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

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

Schema description coverage is 100% (both parameters described). The description adds default values (days=14, max 30; window='1wk') and explains the snapshot family concept, adding context beyond the schema definitions.

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

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

The description clearly states the tool provides 'edge persistence and decay telemetry' and answers a specific question about how long an edge has existed and whether it is shrinking. It distinguishes itself from siblings like polymarket_edges by focusing on persistence and decay, not just raw edge values.

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

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

The description implies when to use the tool (to assess edge duration and decay) and gives a concrete example contrasting a fresh wide edge with an old one. It does not explicitly mention when not to use it or list alternatives, but the context is clear enough for an agent to decide.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint) already indicate safety. The description adds rich behavioral context: walks the order book ladder, returns a verdict (clean|degraded|cannot_fill), and explains that partial basket fills convert an arb into an unhedged directional position. It does not contradict any 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 with clear sections for requirements, single-market mode, basket mode, and usage guidance. It uses bold and line breaks effectively. Every sentence provides essential information without fluff, making it comprehensive yet focused.

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

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

Despite no output schema, the description thoroughly explains all return fields for both modes, including verdict, capture_ratio, profit_usd, thin_legs, etc. It covers edge cases like forced directional risk and partial fills. For a complex tool with two modes, the description is complete and actionable.

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

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

Schema coverage is 100% with descriptions for all 4 parameters. The description adds significant meaning: e.g., size_usd is 'max spend on buys, target proceeds on sells' for single mode and 'settlement notional — shares per leg' for basket mode; side default auto-logic is explained; event and market usage are clarified.

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 specifies the tool performs a realizable vs theoretical edge check against live CLOB order-book depth. It distinguishes between single-market and basket modes, lists specific return fields (top_of_book, vwap_fill_price, slippage_pp, etc.), and differentiates itself from sibling tools like polymarket_arbitrage and polymarket_edges by stating when to use it.

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

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

Explicitly states when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' Also explains why (theoretical overround on thin books is not capturable, partial basket fills convert arb into directional position). Additionally mentions requirements ('REQUIRES one of market or event') and default values.

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 readOnlyHint/idempotentHint annotations, disclosing that compatibility_codes can be non-empty even when matched_pairs>0, that unknown legs are never paired, that temporal_alignment=null means 'could not compute' rather than 'aligned,' that pairing_unverified always applies, and that spreads are gross because Kalshi's fee schedule is not modeled. No contradiction with annotations; the safety profile is enriched, not repeated.

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?

Nearly every sentence earns its place for a tool this complex, but the ~350-word wall of text buries key operational warnings (fees_note, unclassified legs, pairing_unverified) mid-paragraph. The codes list and safety fields would be far more usable as scannable structure, and the front-loaded mode explanation could be tighter.

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 names nearly every response field (top_spreads_pp, compatibility_warning/codes, matched_pairs, temporal_alignment{...}, skipped_unclassified, low_confidence_pairs, skipped_cross_type/subtype) and their semantics, including null meaning, per-entry flags, and gross-vs-net caveats. An agent has what it needs to invoke and interpret results 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, but the description adds the two-mode framework (topic auto-fetch vs explicit override) and clarifies that both modes run the identical token-overlap matcher with the same disclosures. It also attaches behavioral consequences to supplying the ticker/slug, which the three independent schema fields do 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 opening line names the resource precisely — the cross-venue spread between Kalshi and Polymarket for the same resolving question — and the two-venue scope distinguishes it from Polymarket-only siblings like polymarket_edges or bet_research. However, there is no explicit verb (returns/computes) and no sibling tool is named, so it stops short of the strongest 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?

Provides concrete when-to-use context: a two-mode selection rule (topic shortcuts vs explicit ticker/slug pairing), a trust criterion (the delta is a real signal only when bet shapes are equivalent), and a calibration warning that most pre-mapped topics return compatibility_warning today. It never names alternatives or exclusions relative to siblings like polymarket_arbitrage, so it misses the explicit-alternative 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?

Annotations already declare readOnlyHint and idempotentHint true. Description adds value by explaining scoping to user identifier and pairing with remember/forget. No contradiction.

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

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

Three concise sentences front-loaded with main action. Every sentence adds value. No wasted words.

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

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

Given one optional parameter, no output schema, and robust annotations, the description fully covers purpose, usage, scoping, and pairing with siblings. Complete for a simple retrieval 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 the single optional parameter, and the description restates the same behavior (omit to list all keys). No additional meaning beyond schema.

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

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

Description clearly states 'Retrieve a value previously saved via remember, or list all saved keys', using specific verbs and resource. Differentiates from siblings like 'remember' and 'forget'.

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

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

Provides explicit usage context: 'look up context the agent stored earlier' with examples. Mentions scoping and pairing with remember/forget. No explicit when-not, but context is clear.

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

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

Discloses optional state modification via mark_read, which might contradict readOnlyHint annotation but is transparently described. Adds polling suitability and alternative access, going beyond annotations.

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

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

Three sentences, front-loaded with purpose, then returns, then filters. No wasted words; every sentence adds value.

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

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

Despite no output schema, description covers return structure, parameter details, side effects, and alternative access. Completely adequate for a read-oriented tool with good annotations.

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

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

Schema provides full parameter descriptions (100% coverage). Description adds minimal context: example for type, format for since, default for mark_read. Meets baseline but doesn't significantly enhance.

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

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

Clearly states action (pull) and resource (fired events from subscription feed). Includes specific return fields (source, citation_uri, raw payload), distinguishing it from sibling tools like list_subscriptions.

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

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

Provides usage tips: filtering by type and since, mark_read to update state, and notes that polling is fine. Mentions alternative access via GET endpoint for scripts. Lacks explicit when-not-to-use but overall helpful.

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 indicate readOnly, idempotent, nondestructive. Description adds detailed behavior: fans out to SEC, GDELT/GNews fallback, USPTO soft-fail, and return structure (changes grouped by source, total_changes, pipeworx URIs). No contradiction.

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

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

Concise yet dense: examples at start, then sources, fallback, soft-fail, parameter guidance, return structure, and sibling comparison. No wasted words, well organized.

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

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

Given complexity (multi-source, fallback, soft-fail, no output schema), the description covers all necessary context: sources, fallback behavior, date formats, return shape, and when to use alternative tool.

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

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

Schema covers all three parameters with descriptions. Description adds extra guidance: relative date shorthand for `since`, ticker/CIK examples for `value`, and that `type` is only 'company'. Adds meaningful value beyond schema.

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

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

The description clearly states this tool provides a change feed ('What's new with X') for a company in the last N days, fanning out to multiple sources. It distinguishes from sibling `entity_profile` which is for static profile.

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

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

Provides explicit use cases ('What's new', 'latest on', etc.) and directs agents to use `entity_profile` for static profile. Also advises on using relative dates like '30d' for typical monitoring.

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 indicate idempotent and non-destructive. The description adds context about retention periods (persistent for authenticated, 24h for anonymous) and scoping by identifier, enhancing understanding beyond annotations.

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

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

The description is a focused paragraph of 5 sentences, front-loaded with purpose, followed by usage guidance and technical details. No redundant information.

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

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

For a simple store tool, the description covers purpose, usage, persistence, and pairing with siblings. Lack of output schema details is acceptable as return values are likely trivial or implied.

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 description adds naming conventions and examples for key-value pairs, providing marginal extra value beyond 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 saves data for reuse across conversations/sessions, specifies key-value storage, and distinguishes from siblings 'recall' and 'forget'.

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

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

The description explicitly lists when to use the tool (e.g., discovered tickers, preferences) and covers scope and persistence differences, though it doesn't explicitly 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?

The description goes well beyond the readOnly/openWorld/idempotent annotations by disclosing key behaviors: it cascades through multiple lookup endpoints, returns figi_candidates when a name matches multiple instruments, labels each identifier by source, explicitly lists unresolved identifiers, and degrades gracefully when LEI/FIGI enrichment is unavailable. This gives the agent a rich model of how the tool behaves.

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

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

The description is dense and somewhat run-on, but it is front-loaded with user-phrase examples and a crisp purpose statement. Nearly every clause adds distinct information—supported types, ambiguity handling, fallback behavior, and source labeling—so it earns its length, though it would benefit from clearer segmentation.

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 input variants, ambiguity resolution, degraded enrichment, unresolved identifiers, and source attribution. An agent has enough information to decide when to invoke it and to interpret the likely outcome, even without 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 already provides strong descriptions for both parameters (100% coverage), so the baseline is 3. The description adds extra semantic value by introducing ISIN as an accepted company input, explaining how an ISIN resolves to the issuing legal entity, and clarifying that non-equity instruments resolve here. This goes beyond the schema's parameter text.

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 names a specific verb ('resolve') and a specific resource (user-spoken NAME to canonical/official identifiers), reinforced by concrete query examples at the start. It also differentiates itself from sibling tools by instructing 'Use FIRST whenever you have a name but need an ID', making its role as the identity-lookup tool unmistakable.

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

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

The description gives explicit when-to-use guidance ('Use FIRST whenever you have a name but need an ID') and detailed context for supported entity types and input formats. It also provides a strong negative instruction for bonds ('never the question's full noun phrase'), but it does not explicitly name alternative tools or state when not to use resolve_entity.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds specific behavioral details: it probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, signal density. 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 three sentences, front-loading the purpose in the first sentence. Second sentence adds detailed behavior. Third sentence gives a concrete example. No wasted words, well-structured.

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

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

Given the tool has 4 parameters, no output schema, and schema coverage is 100%, the description provides sufficient context: explains the workflow, return format, and use case. It could mention entity count constraints (2-8), but that's in the schema. Overall complete for its complexity.

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

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

Schema coverage is 100%, so the description adds minimal extra meaning beyond the schema. It mentions 'your brand + N competitors' implying the first entity is the subject, which is a slight addition. Otherwise, the schema already describes each parameter adequately.

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

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

The description clearly states it compares AI visibility across multiple entities, probes each with ai_visibility_check, ranks them, and surfaces most/least recognized. This distinguishes it from the sibling 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 gives a clear use case ('competitive AI-marketing audits') and an example question. It does not explicitly state when not to use or list alternatives, but the context implies it is for side-by-side comparison, which is sufficiently clear.

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

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

Annotations already indicate readOnly, idempotent, and non-destructive behavior. The description adds value by disclosing that bundlephobia's first measurement may take 5-30 seconds and that failures degrade gracefully with a 'sources_failed' field. 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 a single paragraph that front-loads the core purpose, then provides details. While it is longer than some, every sentence adds value (usage guidance, behavioral notes, return format). Slightly verbose but not wasteful.

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

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

Despite lacking an output schema, the description thoroughly explains the return value: summary block with listed fields, per-advisory detail, links, and alternative versions. It also covers edge cases like partial failures and timeouts, ensuring the agent knows what to expect.

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

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

Input schema has 100% description coverage for both parameters (package and version). The description adds minor context about scoped packages and default version, but does not significantly enhance the schema's clarity. Baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose as a composite check for evaluating npm packages, listing the specific data sources (deps.dev and bundlephobia) and the criteria checked (license, advisories, bundle size, etc.). It distinguishes from sibling tools by explicitly limiting to npm ecosystem in v1 and directing other ecosystems to deps.dev:version.

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

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

The description provides explicit when-to-use guidance: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' It also clarifies when not to use (other ecosystems) and notes partial failures and timeouts, helping the agent decide appropriately.

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?

Goes beyond annotations by specifying embedding model (BGE-base-en), window size (500-char overlapping), similarity metric (cosine), and truncation behavior (200K char cap with flag). Annotations already declare safety properties; description adds technical detail.

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 adding unique value. Front-loaded with purpose, no redundancy. Efficiently covers usage, behavior, and technical 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?

No output schema, but description explains return format (passages with offsets and scores). Covers input constraints, truncation, and pairing with a sibling tool. Complete for a search tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by providing query examples and clarifying the 'limit' default and range, plus embedding details that inform parameter usage.

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

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

The description clearly states 'semantic search INSIDE a fetched record' with specific verb and resource. It distinguishes from siblings by highlighting context-saving, character offsets, and pairing with ask_pipeworx_grounded.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and mentions pairing with ask_pipeworx_grounded. Provides clear context for when to use, though does not explicitly list when not to use.

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

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

Annotations provide readOnly=false, idempotent=true, etc. The description adds context such as OAuth requirement, sms/day cap, webhook auto-disable, and per-type parameter details, which enriches behavioral understanding beyond annotations.

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

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

The description is detailed yet well-structured, front-loading the core purpose and then layering specifics. Every sentence adds value, though there is slight redundancy with the schema's delivery description.

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 mentions return of subscription ID. It covers all parameter types, delivery channels, and constraints, making it sufficiently 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 has 100% coverage with descriptions for all parameters. The description adds concrete examples (e.g., items:["5.02"], topic:"fed") and delivery constraints (e.g., sms must match verified phone), providing meaning beyond the schema.

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

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

The description clearly states the tool creates a proactive monitoring subscription to live-data event streams, specifies return of a subscription ID, and lists event types, distinguishing it from siblings like list_subscriptions and unsubscribe.

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

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

It explicitly requires a Pipeworx OAuth account and states that anonymous/BYO cannot persist subscriptions, implying when to use. It details delivery channel constraints but does not explicitly contrast with sibling tools like list_subscriptions or recent_alerts.

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

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

The description aligns with annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false), adding important behavioral context: it returns live catalog data with exact tool and argument shape, and explains the difference between no arguments and topic-specific calls. 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 well-structured and front-loaded: it starts with alternative phrasings and purpose, then describes the return type and usage. It is moderately concise, with no wasted sentences, but could be slightly shorter while retaining all information.

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

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

Given the tool's simplicity (1 optional parameter, no output schema, but with rich annotations), the description provides complete context: categories, usage patterns, return content, and relation to other tools. It fully covers what an agent needs to know to use this tool effectively.

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

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

With 100% schema description coverage, the baseline is 3. The description adds value by explaining the effect of omitting the parameter ('cross-category spread') and listing the allowed topic values, going beyond the schema's basic description.

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

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

The description clearly states that this tool is an onboarding entry point for a new agent to learn about Pipeworx. It uses specific verbs ('returns category-bucketed example questions') and distinguishes from siblings like ask_pipeworx and discover_tools by detailing the exact content and purpose.

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

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

The description explicitly advises to use this tool first when you do not yet know what Pipeworx can do, and explains how to call with no arguments for a full spread or pass a topic to focus. While it doesn't explicitly state when not to use it, the context is clear and sufficient.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds valuable behavioral context: it is keyless (no authentication needed), sourced from EBI, and returns specific data (chains and residue range). 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 two sentences and front-loaded with the main purpose. The first sentence is dense but conveys all essential information without waste. Minor verbosity is acceptable.

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

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

For a simple one-parameter tool with rich annotations, the description fully covers the source, output format, keyless access, and example. No output schema exists, but the description explains return values sufficiently.

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% coverage for the single parameter (pdb_id), with a clear description and example. The description reinforces the 4-char format and example, adding no new semantics beyond the schema.

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

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

The description clearly states the tool performs SIFTS cross-database mapping from PDB to UniProt, specifying the source (PDBe/EBI), output details (matching chains and residue range), and a concrete example. It distinguishes from siblings by emphasizing 'curated cross-database mappings unique to EBI.'

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 (mapping PDB to UniProt) and implies authoritative curation, but does not explicitly state when not to use this tool or mention alternative tools for similar mappings. No exclusion criteria are given.

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 ownership enforcement and deactivation behavior beyond annotations. Annotations already indicate non-destructive and idempotent; description adds context that historical events remain available and links to 'recent_alerts'.

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

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

Two sentences, no wasted words. Action is front-loaded. Every sentence adds meaningful information.

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

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

For a simple tool with one parameter and no output schema, the description covers ownership, idempotency, deactivation, and data retention. No gaps for agent usage.

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

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

Schema coverage is 100% with description of 'id' parameter. Description adds value by clarifying that the id is 'returned by subscribe', providing useful linkage. Avoids redundancy.

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

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

Description clearly states 'cancel a subscription by id' with specific verb and resource. It distinguishes from deletion by noting 'deactivated (not deleted)' and references sibling tools like 'subscribe' and 'recent_alerts'.

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

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

Explicitly states ownership enforcement ('you can only cancel your own subscriptions') and explains the deactivation behavior, but does not explicitly contrast with alternatives like 'unsubscribe' vs 'delete' (though no delete tool exists). Guidance is sufficient.

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

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

Beyond the annotations (read-only, open-world, idempotent), the description discloses critical behavioral nuances: the dual pipeline (structured SEC EDGAR vs. grounded fallback), the exact verdict vocabulary, and the vital distinction between 'could_not_verify' (check failed) and 'unsupported' (no source coverage). It also warns callers not to treat 'could_not_verify' as evidence, adding significant value not present in annotations.

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

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

The description is comprehensive yet efficiently structured: it front-loads with natural-language triggers, then explains usage, return value, and important exceptions. Every sentence earns its place, covering routing, verdicts, citations, and error handling 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?

There is no output schema, so the description must fully explain return values and behaviors. It does so thoroughly: verdict types, actual value with citation, reasoning, and the semantic distinction between 'could_not_verify' and 'unsupported'. It even notes the tool replaces multiple sequential calls, giving a full picture of the tool's role and expectations.

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

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

The input schema already provides 100% coverage with detailed descriptions for both 'claim' and 'tolerance_pct', including the override behavior and default cap. The description adds example claims but no new semantic information beyond what the schema states, so it does not elevate beyond the baseline for high schema coverage.

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

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

The description clearly states the tool's purpose: natural-language claim verification against authoritative sources. It provides example queries ('Is it true that…', 'fact check') and explicitly distinguishes it from general research tools by focusing on fact-checking user statements. The scope is specific and actionable.

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 whenever the agent needs to check whether something a user said is factually correct', giving a clear trigger condition. It also details the internal routing for company-financial vs. other claims, which explains when one path is preferred. However, it does not name alternative sibling tools or provide explicit 'when not to use' exclusions, so it falls just 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.