Metmuseum

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

Annotations already declare readOnlyHint, openWorldHint, etc. The description adds detailed behavioral context: default model, cost implication for Anthropic, and the structure of the return (per-model score, confidence, signals, raw_response). 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?

Three sentences: first states primary purpose and output, second adds model details and key requirement, third adds return format and use cases. No redundancy, every sentence earns its place.

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

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

All parameters are covered, return structure is described, and use cases are given. No output schema exists, but the description compensates with a clear summary. For a tool with 4 simple parameters, this is 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?

Schema coverage is 100%, so baseline is high. The description adds value by explaining each parameter with examples ('E.g. "Pipeworx"'), clarifying the purpose of '_apiKey' and 'context', and indicating defaults (workers-ai as default model).

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

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

The description starts with a specific verb ('Probe') and resource ('LLMs for what they know about a business/brand/product/topic') and clearly states the scoring output. It is distinct from all sibling tools, many of which are about Pipeworx or Polymarket, while this one focuses on AI visibility across models.

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 ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains when to provide an API key ('pass _apiKey to also probe Anthropic'). No explicit exclusion of alternatives, but the context is clear enough.

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

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

Annotations already declare read-only, idempotent, non-destructive. The description supplements with routing behavior, stable pipeworx:// citation URIs, 'one fast call', and works on every tier. No contradiction, and the added detail is useful beyond annotations.

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

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

The description is long but well-structured: it opens with the primary directive, then examples, then escalation paths. Each sentence carries actionable information, though a few examples could be trimmed for conciseness.

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

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

For a complex meta-tool routing across thousands of sources, the description covers purpose, usage triggers, examples, return style (structured citations), and when to use alternatives. Even without an output schema, it clearly conveys what the agent will receive.

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

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

Schema coverage is 100%, with the 'question' parameter and its aliases fully described in the input schema. The description adds example queries but no new semantic detail about parameters beyond what the schema already provides, so baseline 3 is appropriate.

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

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

The description clearly states it answers factual questions by routing to 5,462 tools across 1,419 sources and returning structured citations. It distinguishes itself from web search and sibling tools like ask_pipeworx_grounded and deep_research, using specific verbs like 'routes' and 'returns'.

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

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

Explicitly says 'PREFER OVER WEB SEARCH' and gives trigger phrases like 'what is', 'look up', 'find', plus concrete examples. It also provides exclusions: use ask_pipeworx_grounded for hallucination-resistant answers and deep_research for broad/multi-part questions, making alternative selection 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, openWorld, idempotent, and non-destructive behavior. The description adds substantial context beyond annotations: beta status, live candidate routing under test, current state (last retired on 2026-07-26), and that it is a full working router rather than a fallback. This is rich behavioral disclosure exceeding the annotation baseline.

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 carrying distinct information: identity, current experimental state, usage guidance, and non-fallback nature. The date and tool count add specificity but are not wasteful. Slightly dense but well-structured and front-loaded.

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

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

For a complex router tool, the description covers beta nature, current behavior, usage, and response-shape equivalence. It lacks an explicit return format, but points to the stable ask_pipeworx for that, which is sufficient given the absence of an output schema. Overall complete for practical use.

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

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

Schema description coverage is 100% with all question aliases documented. The description adds only 'same arguments' referencing ask_pipeworx, which is marginal; the schema already fully explains the parameter. Hence the 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?

Description explicitly states this is the beta version of ask_pipeworx, an identical universal router with the same 5,462 tools, arguments, and response shape. It clearly differentiates itself from the stable ask_pipeworx sibling by framing itself as the experimental edge, 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?

Directly instructs to 'Use it exactly like ask_pipeworx when you want the newest routing' and explains that results are compared against the stable router to determine merges. It also clarifies the current state (no candidate active) and that it matches ask_pipeworx exactly, providing clear when-to-use guidance and naming the alternative.

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

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

The description goes well beyond the readOnlyHint/openWorldHint/idempotentHint annotations by disclosing the refusal mechanism with specific refusal_reason enum values, the evidence verbatim quote, and the extra LLM call cost. It clarifies that the answer is extracted using ONLY the tool result content, preventing hallucination. No contradiction with annotations.

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

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

The description is dense but every clause earns its place: mechanism, output format, refusal reasons, usage context, and cost comparison. It is front-loaded with the key differentiator ('Hallucination-resistant') and avoids filler, making it appropriately sized for the tool's complexity.

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

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

With no output schema, the description fully specifies the success return shape ({answer, evidence, confidence, source, fetched_at, refusal_reason:null}) and failure shapes with a refusal_reason enum. It also covers when to use, the routing scope, and the cost trade-off. This is complete for a high-stakes Q&A tool.

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

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

The input schema already documents all 6 parameters with 100% coverage, so the baseline is 3. The description adds meaningful semantic context by explaining that the question is used for routing across 5,462 tools and filling arguments, which goes beyond the schema's simple 'natural language' label. However, it doesn't elaborate on the alias handling or input format, so a 4 is appropriate.

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

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

The description opens with 'Hallucination-resistant answer mode for high-stakes reads,' clearly positioning it as a grounded Q&A tool. It explicitly distinguishes from ask_pipeworx by stating 'Same routing as ask_pipeworx' then describing the extraction-only-from-tool-result behavior, differentiating it from sibling tools like ask_pipeworx_beta.

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

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

It explicitly states when to use: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' It also gives a clear alternative: 'prefer ask_pipeworx for casual lookups' and notes the cost trade-off ('Costs one extra LLM call'), providing both positive and negative 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?

The description goes far beyond annotations by detailing response shapes, resolver contract, parent_event extractor, news fields, safety mechanisms (low-confidence short-circuit, closed markets, wide spreads), resolution-rule risk, and more. This comprehensive disclosure leaves no ambiguity about tool behavior.

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

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

The description is quite lengthy and contains detailed examples and edge cases. While it is front-loaded with the core purpose, the verbosity could be trimmed without losing essential information. Some agents may find the length overwhelming, but the structure is logical and progressive.

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 covers input expectations, processing steps, response shapes, safety paths, and nuance (e.g., resolution-rule risk). It addresses all likely agent concerns and edge cases, making it fully complete given 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?

Although schema coverage is 100%, the description adds substantial meaning beyond the schema: it explains the three accepted forms for 'market', describes 'depth' values (quick vs thorough), and clarifies 'include_raw' effects (summarized vs full payloads). This extra context is highly valuable for correct 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 starts with a clear verb-resource pair: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It elaborates on specific actions (resolve, classify, fan-out, return evidence packet) and gives explicit use cases. Though sibling differentiation is not explicit, the purpose is unique and 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 when to use the tool: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It provides classifiers and fan-out examples, guiding appropriate usage. It lacks explicit when-not-to-use or alternative tool mentions, but the context is clearly scoped.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds behavioral context: parallel call, sorted results, citation URIs, data sources (SEC EDGAR, FAERS), off-calendar fiscal year handling. 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?

Single paragraph front-loaded with query patterns, every sentence adds unique value. Efficient and well-structured.

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

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

Comprehensively covers both entity types, their data sources, return format (paired data + citations), sorting, and efficiency. Despite no output schema, the description provides sufficient detail for the agent to understand output.

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

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

Schema coverage is 100% but description enriches parameter meaning: for 'values' it specifies format (tickers/CIKs for company, names for drug) and constraints (2-5 items). For 'type' it explains the data pulled for each enum value. This goes 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 starts with natural language query examples, clearly states it performs side-by-side comparison of 2-5 companies or drugs, and specifies the data pulled for each type. It distinguishes itself from sequential lookups and implicitly from sibling tool 'entity_profile' which is for single 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?

Explicitly instructs 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing clear when-to-use guidance. The examples also help the agent recognize appropriate queries.

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

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

Annotations declare read-only/idempotent, and the description adds substantial behavioral context: required sign-in and paid plan for 'thorough', latency expectations (15-90s), gap[] and contradictions[] behavior, citation URI fetchability, semantic excerpting, and depth-specific iteration. No contradiction with annotations.

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

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

The description is long but well-structured, front-loading the critical account requirement and alternative tool, then moving to capability, usage guidance, and behavioral details. Every sentence adds a distinct point, but the density makes it a wall of text; a more structured format with bullets could improve scannability.

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

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

Despite no output schema, the description thoroughly covers expected return values (findings packet with verbatim evidence, confidence, source, fetched_at, citation_uri), failure behavior (gaps[]), and edge cases (breaking news, signed-out users). It also explains timing, account prerequisites, and depth-specific behavior, making it self-sufficient for an agent to select and invoke correctly.

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

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

Schema coverage is 100% with descriptions for both 'question' and 'depth'. The description adds extra meaning by explaining what each depth level does (gap recovery, lead chasing, contradiction scan), the paid requirement for 'thorough', and the type of questions best suited. This goes beyond the schema's enum descriptions, though the schema already covers the basics.

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 grounded multi-source research engine over Pipeworx's 1,419 structured data sources, with a specific verb+resource ('Grounded multi-source research'). It distinguishes itself from open-web search and from ask_pipeworx, and even states what it is NOT ('NOT open-web search').

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 and when-not-to-use guidance: use ask_pipeworx when signed out, for single lookups, or for breaking/current news; use deep_research for broad/multi-part questions over structured data. It names the alternative (ask_pipeworx) and gives context for each scenario.

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=true, idempotentHint=true, destructiveHint=false, already conveying safe, idempotent behavior. The description adds valuable context: results include 'full input schemas (with curated examples)' and are 'ready to call directly, no second schema lookup needed.' No contradictions.

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

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

The description is a single paragraph that covers purpose, usage, and output in a few sentences. It lists numerous domains efficiently without being verbose. Slightly more structure could improve clarity, but it's 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?

Despite lacking an output schema, the description fully explains what is returned: 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples).' It also provides example queries and instructs when to use, making it complete for a discovery 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% with detailed parameter descriptions including aliases and examples. The tool description does not add meaning beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It enumerates specific domains and explains that it returns ready-to-call tool schemas, making the purpose unmistakable and distinct from sibling tools (none with similar function).

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: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It also says 'Use when you need to browse, search, look up, or discover what tools exist.' While it doesn't specify when not to use, the 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context: patents soft-fail until USPTO reactivates, use of GDELT→GNews fallback, and exact return fields. No contradictions.

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

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

The description is lengthy but packed with essential information. It is front-loaded with example queries but lacks structured formatting like bullet points. Every sentence adds value, 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?

Despite no output schema, the description thoroughly explains what the tool returns (cik, company_name, recent_filings with URIs, fundamentals, patents, news, LEI) and notes limitations (patents soft-fail). This covers all needed context for a holistic profile tool.

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

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

Schema coverage is 100% with clear descriptions for both parameters. The description reinforces the meaning (ticker or CIK for value) and adds usage nuance (names not supported, only 'company' type).

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

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

The description clearly states the tool provides a 'full cross-source profile of a US public company' and gives multiple example natural language queries. It distinguishes from sibling tools like resolve_entity by specifying that names are not supported and directing users to that tool first.

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 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also specifies when not to use: only company type, ticker or CIK, and recommends using resolve_entity for names.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. Description adds 'sensitive data' context but no further behavioral traits beyond what annotations provide.

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

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

Two sentences, front-loaded action, no wasted words. Efficiently conveys purpose and usage.

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?

Simple tool with one parameter and no output schema. Description covers when and what, but lacks explicit return value info. Acceptable for destructive operation.

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

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

Single parameter 'key' has 100% schema coverage with description 'Memory key to delete'. Description does not add extra semantics beyond schema.

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

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

Clear verb 'Delete' and specific resource 'memory by key'. Distinguishes from siblings 'remember' and 'recall' by name and pairing mention.

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

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

Explicitly states when to use: stale context, task done, clear sensitive data. References paired tools remember and recall.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive behavior. The description adds context: fetches the page, extracts title/description/key links, and emits standard llms.txt format as a single text blob. No contradictions with annotations.

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

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

The description is concise (two sentences for the main action plus three short use cases) with no wasted words. It front-loads the purpose and then provides context. Every sentence contributes 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?

The description covers all key aspects: input (URL), process (fetch, extract), output (standard llms.txt markdown), and usage scenarios. Since there is no output schema, the description adequately explains the return format. Simple tool, well-covered.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining that max_links controls the number of link entries (default 25, max 50), which is not in the schema description. This helps the agent understand the parameter's purpose beyond the schema's 'Maximum number of link entries to include'.

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 any URL, specifying the output format (standard markdown) and use cases. It distinguishes itself from sibling tools by being the only one focused on llms.txt generation.

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 (indexing client's site, drafting for own project, auditing competitor). While it doesn't mention when not to use or alternatives, the use cases provide sufficient guidance for a specialized tool.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. Description adds value with 'Keyless' disclosure and specifics of returned fields (artist bio, medium, etc.), enhancing transparency beyond annotations.

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

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

Single sentence of ~30 words, front-loaded with purpose and key details. No redundancy, efficient communication.

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 rich annotations, full schema coverage, and simple input, the description sufficiently covers what the tool returns and usage note. No missing critical information.

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

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

Schema provides 100% coverage for the single parameter with description and example. Description reinforces by mentioning 'by its objectID', but adds no new semantic detail 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 it retrieves rich detail for a single Met object by objectID, listing specific fields. Distinguishes from sibling 'search_artworks' by emphasizing single object retrieval.

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?

Mentions 'Keyless' (no API key needed) but lacks explicit when-to-use or when-not-to-use guidance compared to siblings like 'search_artworks'. Usage context is implied but not stated.

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

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

Adds context beyond annotations: explains return value (department IDs) and their purpose. Annotations already declare readOnly, openWorld, idempotent, non-destructive; description does not contradict and adds value.

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

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

Single sentence, front-loaded with action and object, no unnecessary words.

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

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

For a zero-parameter, simple listing tool with no output schema, the description fully covers what the tool does, what it returns, and how it can be used.

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?

No parameters, so baseline is 4. Description explains what the tool returns (department IDs) and their use, adding meaning beyond the empty 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 specifically states it lists curatorial departments with their IDs, gives concrete examples (European Paintings, Egyptian Art), and notes it's keyless. Clearly distinguishes from sibling tools that search or perform other actions.

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?

Implies usage for scoping searches with 'usable to scope searches' and mentions 'keyless', but does not explicitly state when to use vs alternatives. No exclusion or comparison with sibling tools.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds return fields but does not contradict annotations. No additional behavioral context needed beyond what annotations provide.

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

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

Two sentences with no wasted words. First sentence states action and output; second sentence provides usage context. Perfectly sized and front-loaded.

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

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

For a simple list tool with good annotations and schema, the description covers the key aspects: what it does, what it returns, and when to use it. Lacks mention of pagination or limits, but not critical for low-complexity tool.

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

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

Schema coverage is 100% with clear parameter description (include_inactive). Description does not add extra meaning 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?

Clearly states it lists the caller's active subscriptions and specifies the returned fields (id, type, params, created_at, last_fired_at, fire_count). Distinguishes itself from sibling tools like subscribe and unsubscribe by being read-only.

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

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

Provides explicit usage guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' Indicates when to use it, though does not 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?

Annotations already note readOnlyHint=false and destructiveHint=false, so side effects are implied. The description adds valuable behavioral context: 'Rate-limited to 5 per identifier per day,' 'Free; doesn't count against your tool-call quota,' and the fact that 'The team reads digests daily and signal directly affects roadmap.' It also adds a content rule ('don't paste the end-user's prompt'). 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 organized logically (purpose → when to use → scope limitation → content guidance → expectations) and front-loaded with the main action. While it is longer than two sentences, each clause contributes unique guidance. Slight redundancy in the 'Not sure?' question and the explicit scope line prevents a perfect score.

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

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

For a tool with 3 parameters (one enum, one nested object) and no output schema, the description is exceptionally complete. It covers purpose, use cases, scope boundaries, content instructions, rate limits, quota behavior, and downstream impact. No relevant information is missing for correct invocation.

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

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

Schema coverage is 100%, with all parameters fully described. The description adds an extra constraint on the message field: 'Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt,' which is not present in the schema. This enriches the semantic meaning beyond the structured schema.

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

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

The description opens with a clear imperative 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It explicitly distinguishes feedback from sibling tools like ask_pipeworx and discover_tools by focusing on reporting issues about existing tools or requesting new ones.

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

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

Explicitly lists the conditions for use: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives a clear exclusion: 'ONLY for tools served by this Pipeworx connection... file it with that server instead.' This provides strong when-to-use and when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint as true, and destructiveHint as false. The description adds valuable behavioral context: caching duration (5min-1h), data source (CF analytics-engine), and privacy (no PII), which go beyond the annotations.

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

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

The description is concise and well-structured: first sentence gives the main output, then use cases in a bullet-like list, followed by data source and caching. Every sentence adds value, and it is front-loaded with the most important 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 (one optional parameter, no output schema), the description fully covers purpose, use cases, parameter semantics, and behavioral details like caching and data source. It is complete enough for an agent to understand when and how to use it.

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

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

Schema coverage is 100% with one parameter already described. The description adds extra meaning by explaining the trade-off between short and long windows (hot vs steady-state), enhancing the agent's understanding of the parameter semantics.

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

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

The description clearly states the tool returns top tools, top packs, and total call volume over a recent window, with specific use cases listed. The verb 'returns' and resource 'what other AI agents are calling on Pipeworx right now' is precise, and it distinguishes itself from siblings like 'discover_tools' by highlighting the self-aggregating signal from CF analytics.

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 three explicit use cases (discovering hot data sources, confirming canonical tool, checking alignment) but does not explicitly state when not to use or list alternatives. The context is clear enough for an agent to make a decision.

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

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

Despite annotations indicating readOnlyHint=true and no destructive action, the description adds critical behavioral context: internal checks (date-axis/threshold-axis ordering, partition_sum, Jaccard similarity, placeholder filtering), the fill check against live CLOB depth, and explicit conditions for not trading (realizable_edge_pp ≤ 0). No contradiction with annotations.

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

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

The description is long but well-structured, front-loaded with the purpose, then mode usage, then internal details. Every sentence adds value for a complex tool, though it could be slightly more concise. Still efficient for the depth of 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 no output schema, the description fully explains the response format (opportunities[] with fields, partition_check in event mode) and covers key aspects like fill check, filters, and failure conditions. It leaves no significant gaps for an AI agent to understand usage and outcomes.

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

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

Schema description coverage is 100% and already explains the parameters well (event slug, topic seed question). The main description adds behavioral details but not new parameter-specific semantics beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes itself from sibling tools by specifying the method (monotonicity, partition checks) and mentions different modes (trending_scan, event, topic) that are not present in siblings like polymarket_edges or polymarket_fill_risk.

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

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

The description provides explicit guidance on when to use each mode: 'Call with NO args for a trending_scan... pass event for... or topic for...' It recommends event for specific markets and explains cross-event advantages. It also tells when not to trade (fill check condition) and directs to polymarket_fill_risk for custom sizing.

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 annotations by detailing caching behavior (1h KV cache keyed on all knobs), response structure, the three model segments, how edge is computed net of slippage, and diagnostic fields. All annotations (readOnlyHint, idempotentHint, openWorldHint) are consistent and reinforced.

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

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

The description is well-structured, front-loaded with purpose, then organized by segments, response fields, and knobs. However, it is quite verbose and may overwhelm the agent; some technical detail could be streamlined without losing clarity.

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

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

Given no output schema, the description comprehensively explains all return fields (by_segment, fed_candidates, _diagnostics) and per-opportunity fields (edge_pp_net, kelly_fraction, market stats, 24h move warning). It also covers filter knobs and their effects, making the tool fully usable without additional context.

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

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

With 100% schema description coverage, the description adds significant value beyond the schema. For example, it explains the default slippage of 0.3 pp based on Polymarket's zero fees but bid/ask depth, and clarifies the min_partition_leg_kelly parameter's interaction with min_kelly for partition arbs.

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: scanning Polymarket markets for opportunities where Pipeworx data disagrees with market price. It differentiates from sibling tools like polymarket_arbitrage and polymarket_edge_tracker by focusing on daily discovery without paging hundreds of markets.

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 strong usage context, stating it's built for 'what should I bet on today' and that agents discover opportunities without manual paging. However, it lacks explicit guidance on when to use this tool over the many sibling tools (e.g., polymarket_arbitrage or polymarket_fill_risk), which would improve the score.

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

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

The description extensively discloses behavioral traits: it is read-only (snapshot-based), idempotent (querying same params yields same result), and non-destructive. It also reveals limitations like the 60-day snapshot TTL and that decay values are from daily closes, not intraday. This goes well beyond the annotations, which only hint at safety.

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 front-loaded purpose and clear sections for args and response. However, it is verbose, detailing the entire response structure in prose. In the absence of an output schema, this is justified, but a more concise presentation could improve readability without losing 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 complexity of the tool and the lack of an output schema, the description is remarkably complete. It describes every field in the response (tracked[], expired[], snapshot_dates[]) with their subfields and meanings, and covers limitations like TTL and data sources. No critical information is missing for an agent to use the 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?

The input schema already provides detailed descriptions for both parameters (days and window), achieving 100% coverage. The description adds minimal new semantic value: it mentions default and max for days, and that window refers to snapshot family, but the schema already includes these details. Thus, the description does not significantly enhance parameter understanding.

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

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

The description clearly states the tool's purpose: providing edge persistence and decay telemetry from daily snapshots. It uses an analogy to contrast fresh vs old edges, making the intent unmistakable. The description also distinguishes it from sibling tools like polymarket_edges by focusing on time-series behavior.

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 does not explicitly guide when to use this tool versus alternatives such as polymarket_edges or polymarket_arbitrage. It mentions that it uses snapshots from polymarket_edges, but provides no direct comparison or exclusion criteria. Users must infer usage from the tool's specific 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds substantial behavioral context: it walks the order book ladder, explains return fields (top_of_book, vwap_fill_price, slippage_pp, etc.), and details basket-mode risks like thin_legs and forced_directional_risk. No contradictions with annotations.

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

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

The description is long but front-loaded with the core purpose. Every sentence earns its place by explaining modes, inputs, outputs, or usage guidance. However, it could be slightly tightened without losing clarity.

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

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

Given the tool's complexity (two modes, multiple return fields, risk warnings), the description covers all necessary aspects: what it does, when to use it, parameters, return values, and edge cases. No output schema exists, so the description fully compensates by listing return fields and explaining their meaning.

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

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

With 100% schema coverage, baseline is 3. The description adds meaningful clarification: for size_usd, it explains 'max spend on buys, target proceeds on sells' in single-market mode and 'settlement notional' in basket mode. It also elaborates on the side parameter default logic. This goes 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's function as a 'realizable-vs-theoretical edge check against live CLOB order-book depth'. It distinguishes two modes (single-market and basket) and lists specific outputs, making it distinct from sibling tools like polymarket_arbitrage or polymarket_edges.

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

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

The description explicitly advises 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It also warns about the risk of partial fills converting an arb into an unhedged directional position, providing clear when-to-use and when-not-to-use guidance.

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

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

Annotations already indicate readOnlyHint=true. The description adds extensive behavioral context: compatibility warnings, temporal alignment, skipped cross-type/subtype counters, and how the tool handles non-equivalent bet shapes. No contradiction with annotations.

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

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

The description is front-loaded with the main purpose and well-structured into modes and safety fields. It is somewhat lengthy but every sentence adds necessary detail. Could be slightly more concise without losing 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 the complexity (cross-venue spread, multiple modes, safety fields), the description is very thorough. It explains the response structure (leg-by-leg prices, spread, compatibility warning fields) compensating for the lack of output schema.

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

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

Schema description coverage is 100% and the schema documents parameters with descriptions and examples. The description adds value by explaining the two modes and how parameters interrelate. Slight redundancy but overall effective.

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

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

The description clearly states the tool computes the cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes two modes (topic shortcuts and explicit tickers) and explains the output. This is specific and distinct from sibling tools like polymarket_arbitrage.

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 guidance on when to use: for comparing prices across venues. It notes that real spreads are rarer than the shortcut list suggests and that pre-mapped topics often return compatibility warnings. It does not explicitly mention alternative tools but sets expectations well.

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 scoping detail (by anonymous IP, BYO key hash, account ID). Does not contradict annotations. Adds value beyond annotations.

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

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

Two sentences, front-loaded with action, no redundant 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?

For a simple tool with one optional parameter, readOnly, and no output schema, the description covers all necessary aspects: pairing, scoping, listing, and retrieval behavior.

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

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

Schema has 100% coverage with one parameter (key) described. Description repeats the omission behavior but adds context 'without re-deriving it from scratch'. 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?

Description explicitly states the verb 'retrieve' or 'list', the resource 'value previously saved via remember', and scoping. It differentiates from siblings by naming 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 clear usage context: 'look up context the agent stored earlier without re-deriving it from scratch.' It explains when to omit key (list all) and implies pairing with remember/forget. No explicit exclusion of alternatives, but sufficient for this tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. Description adds value by detailing return fields (source, citation_uri, payload) and the effect of mark_read on subsequent calls. No contradiction; description complements annotations.

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

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

Concise, single paragraph with front-loaded purpose. Every sentence adds unique value: purpose, return fields, parameters, usage notes. No redundancy or filler.

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

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

Despite no output schema, description explains key return fields and behavior of mark_read. It covers all parameters implicitly and mentions the alternative REST endpoint. Lacks explicit pagination info but is adequate for a read-only, non-destructive 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?

All 5 parameters are described in the schema (100% coverage). The description adds minimal extra meaning, only clarifying mark_read's progression behavior. Baseline is 3 given high schema coverage, and this meets it without significant enhancement.

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

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

Description starts with a clear verb-focus phrase 'Pull fired events from your subscription feed' and specifies the resource. It distinguishes from siblings by mentioning the feed and alternative HTTP endpoint, making the tool's unique role clear.

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: polling works fine, the same feed is at an alternative endpoint for scripts/dashboards, and explains filters (type, since, mark_read). Lacks explicit when-not-to-use or direct sibling comparisons, but the guidance is strong enough.

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 the tool is read-only and idempotent. The description adds behavioral details such as fanning out to multiple sources, fallback logic, and soft-failure for USPTO.

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

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

The description is well-structured and front-loaded with examples. While it is packed with information, every sentence adds value and there is 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?

The description covers multiple data sources, return fields, and fallback. Lacks details on pagination or error handling but is sufficient for a complex tool.

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

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

With 100% schema coverage, baseline is 3. The description adds meaning by explaining 'since' formats and recommending '30d' or '1m' for monitoring.

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

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

The description clearly states the tool provides a 'change feed' for a specific company over a time window, fanning out to multiple data sources. It includes concrete usage examples and distinguishes itself from the sibling tool entity_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?

The description explicitly tells when to use this tool versus entity_profile (static profile) and provides example queries. It also notes fallback behavior for news sources.

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 behavioral traits beyond annotations: key-value pair scoped by identifier, persistent for authenticated users, 24-hour retention for anonymous sessions. Annotations already indicate idempotent and non-destructive; description adds valuable 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?

Three sentences, front-loaded with main purpose, no wasted words. Efficiently conveys all necessary 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 key-value store tool, description covers purpose, usage, persistence, and pairing. Lacks details on overwrite behavior but idempotent annotation hints at it. No output schema, but return value is not critical.

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

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

Schema description coverage is 100%, so baseline is 3. Description adds no extra meaning beyond schema examples; schema already provides key and value descriptions with examples.

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

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

Description clearly states the tool saves data for reuse later, using specific verb 'save' and resource 'data'. It distinguishes itself from sibling tools 'recall' and 'forget' by mentioning them explicitly.

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

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

Provides explicit guidance on when to use (discover something worth carrying forward) and when not (not needed for single-use data). Mentions alternatives ('recall' to retrieve, 'forget' to delete) and scoping rules.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds valuable behavioral context by disclosing that each call cascades through several lookup endpoints internally, implying higher cost. It also specifies return formats per type (e.g., ticker, CIK, company name, citation URI) which is beyond the annotations. 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 somewhat long but well-structured, front-loading the purpose with example queries and then detailing supported types. Each sentence contributes unique information, though the example query list is slightly verbose. The overall organization makes scanning easy.

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 explain return values, which it does thoroughly for both company and drug types. It also explains the internal cascading behavior and provides citation URI patterns. However, it does not address edge cases like unresolved names or multiple matches for drugs, leaving minor gaps given 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 already covers both parameters with 100% coverage, but the description significantly enhances parameter meaning. For 'type', it explains each enum value and what it returns. For 'value', it gives concrete formats (ticker, CIK, name for company; brand/generic for drug) and mentions auto-disambiguation. This goes well beyond the schema's basic descriptions.

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

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

The description clearly states the tool's function: resolving user-spoken names to canonical identifiers. It provides concrete examples ('ticker for', 'CIK for', 'RxCUI for') and differentiates itself from other tools by noting the returned IDs are what 'other tools require as input.' The explicit phrasing 'Use FIRST whenever you have a name but need an ID' further anchors its purpose.

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

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

The description provides clear usage context: use it when you have a name but need an ID, and use it first. It also explains that it replaces 2-3 manual lookups. However, it does not explicitly name alternative tools for when not to use it, limiting the when-not guidance. Still, the supported types and input acceptance rules give strong practical guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, establishing the tool's safety profile. The description adds behavioral context beyond this: it explains the process (probes each entity, ranks, returns ranked list) and output details (score, confidence, signal density). This provides useful transparency without contradicting annotations.

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

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

The description is three sentences, front-loaded with the main action, and each sentence earns its place. It avoids fluff and presents information efficiently. The structure is clear and easy to parse.

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 is provided, but the description explicitly states the return format: 'ranked list with score, confidence, signal density per entity.' It also explains the input semantics, process, and use case. The description is complete for a tool of moderate complexity, covering all essential aspects without gaps.

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 four parameters. The description adds significant meaning beyond schema: it clarifies that the first entity is treated as the 'subject', explains optional parameters (models, _apiKey, context), and describes the role of context in disambiguation. This provides high value for parameter understanding.

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

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

The description clearly states the tool's purpose: 'Compare AI visibility across multiple entities side-by-side.' It specifies the action (probe, rank, surface) and the resource (entities). It distinguishes from sibling tool ai_visibility_check by emphasizing multiple entities and comparison, and the use case for competitive audits.

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

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

The description gives clear context: 'Useful for competitive AI-marketing audits' and provides an example question. It implies when to use this tool (for comparison) vs ai_visibility_check (single entity), but it does not explicitly state when not to use it or list alternative tools. The guidance is clear but lacks explicit exclusions.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds: fans out across deps.dev and bundlephobia, mentions partial failures ('sources_failed will list it if it times out'), and timing ('first measurement on a new version can take 5-30s'). Also lists return components (summary, per-advisory, links, alternative versions). Adds significant 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?

Description is detailed but somewhat dense. It front-loads the core purpose and usage guidelines effectively. However, the format is a single block of text; breaking it into paragraphs could improve readability. Still, every sentence adds value and no unnecessary repetition.

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

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

Given tool complexity (multi-source, partial failures, two parameters, no output schema), description is complete. It explains the return summary block fields, per-advisory detail, links, alternative versions, and graceful degradation. No output schema is present, so description properly carries the burden of explaining return values.

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

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

Schema coverage is 100% with both parameters described. Description adds: 'Scoped packages (e.g. "@types/node") are accepted' for package, and 'Defaults to the latest published version when omitted' for version. Adds useful detail beyond the schema without being redundant.

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

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

Description clearly states it is a composite check for npm packages covering license, advisories, version history, and bundle size. The verb 'scan' and resource 'dependency' are specific. It distinguishes from siblings by focusing on npm ecosystem and combining multiple data sources, unlike other tools that target other ecosystems or single sources.

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 whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' Also states exclusion: 'PyPI / Maven / Cargo / Go fall under deps.dev:version directly.' Provides clear context for when to use this tool versus alternatives.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. Description adds value by stating 'Keyless' (no auth needed) and describing the return format (compact records with title, artist, date, medium, image hydrated from object detail). No contradictions.

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

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

Two sentences, no wasted words. Front-loaded with purpose, then optional filters and output. Highly concise and well-structured.

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

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

Covers purpose, optional filters, output format, and keyless access. Missing details like default limit, behavior for no results, or pagination, but adequate for a search tool with rich schema descriptions.

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

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

Schema descriptions cover all parameters (100% coverage), so baseline 3. The description summarizes available filters but adds no new 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?

Clearly states it searches The Met's open-access collection by keyword, with optional filters. Distinguishes itself from sibling tools like get_artwork (specific artwork retrieval) and list_departments (department listing) by being a general search tool.

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 clear context for when to use (keyword search, optional filters) and mentions 'Keyless' indicating no authentication needed. However, it does not explicitly state when not to use or compare to alternatives like get_artwork.

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 rich details: uses BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation flag, and character offsets for verification.

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 comprehensive: starts with core function, followed by examples, usage guidance, technical details, and limitations. Every sentence is purposeful 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 the tool's simplicity (3 parameters, no output schema), the description covers all necessary aspects: purpose, when to use, technical mechanics, limitations, and user hints. No gaps identified.

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 natural-language query examples (e.g., 'supply-chain risk') that go beyond the schema's generic description, aiding in parameter understanding.

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

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

The description clearly states the tool performs semantic search inside a fetched record, with specific examples like SEC 10-K or article. It distinguishes from sibling tools such as search_artworks by focusing on internal passage retrieval rather than external search.

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 it when records are too large for the prompt, saving context. It pairs with ask_pipeworx_grounded for grounding over relevant passages, providing clear usage context and a complementary alternative.

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

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

Annotations already indicate idempotentHint=true, openWorldHint=true, destructiveHint=false, readOnlyHint=false. The description adds behavioral traits: requires OAuth, delivery limitations (SMS 10/day cap), webhook auto-disabling after 10 failures, and phone verification requirement. 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 well-structured with line breaks, front-loading the core purpose. It is slightly lengthy but each sentence adds value. Could be more concise, but overall effective.

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

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

Given the tool's complexity (3 params, nested objects, no output schema), the description covers authentication, return value, types, delivery channels, limitations (SMS cap, webhook auto-disable), and phone verification. It is complete for effective use.

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

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

Schema coverage is 100%, but the description adds significant meaning by explaining the params object in detail for each subscription type and providing examples. It also clarifies delivery channel requirements and constraints 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 it creates a proactive monitoring subscription, returns a subscription ID, and distinguishes itself from siblings like list_subscriptions and unsubscribe. The verb 'Create' and resource 'subscription' are explicit.

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 specifies that a Pipeworx OAuth account is required and anonymous/BYO cannot persist subscriptions. It lists supported types, delivery options, and mentions the always-on feed. It does not explicitly state when to avoid using the tool, but the context and sibling tools provide enough 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 read-only, open-world, idempotent, non-destructive. Description adds that it returns 'category-bucketed example questions' from a live catalog, and explains how the topic parameter affects scope—valuable context beyond annotations.

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

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

Well-organized with a list of common queries, clear explanation of output, and usage instructions. Slightly verbose but every sentence contributes. Could be tightened without losing substance.

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 a single optional parameter and no output schema, the description fully covers the tool's purpose, behavior, and usage context. It even situates the tool within a broader workflow (first use, learning meta-tools). Perfectly complete.

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

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

Schema coverage is 100%, but description adds meaning by listing example topic values (finance, pharma, etc.) and explaining the effect of omission (cross-category spread). This is above the baseline of 3.

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

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

Clearly states the tool is an onboarding entry point that returns category-bucketed example questions, with explicit mention of verb ('get started', 'learn'), resource ('Pipeworx capabilities'), and sufficient distinction from siblings by positioning it as a first-step discovery tool.

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

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

Explicitly instructs to use this tool first when unfamiliar with Pipeworx, and to learn how to call meta-tools. Provides optional topic parameter guidance and describes behavior with no arguments.

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 non-readOnly, idempotent, non-destructive. Description adds three critical behaviors: ownership enforcement, deactivation (not deletion), and retention of historical events. No contradictions.

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

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

Three concise sentences with no wasted words. Front-loaded with the primary action, followed by important constraints and effects.

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

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

For a simple single-parameter tool with no output schema, the description covers essential behavior (ownership, deactivation, history retention). Could mention error handling for invalid IDs, but overall complete.

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

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

Schema coverage is 100% with a clear description of the 'id' parameter. The tool description adds no extra parameter details beyond what the schema already provides, meeting but not exceeding baseline expectations.

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 action ('Cancel a subscription by id') with a specific verb and resource. It distinguishes itself from siblings like 'subscribe' and 'list_subscriptions' by focusing on cancellation.

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 clear context: ownership enforcement and non-destructive deactivation. Implies usage for canceling one's own subscriptions, but lacks explicit guidance on when not to use (e.g., for permanent deletion).

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

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

The description goes well beyond the annotations (readOnlyHint, openWorldHint, etc.) by revealing the internal processing pipeline (SEC EDGAR + XBRL vs. grounded pipeline), the return elements (verdict, actual value with citation, reasoning), and the tolerance override mechanism. It also explains that the tool replaces 4-6 sequential calls, giving agents insight into efficiency.

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

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

The description is a single dense paragraph that packs significant information without wasted words. It front-loads the purpose with common user phrasings. While concise, it could benefit from slight restructuring (e.g., bullet points for return elements) to improve readability, but it remains effective.

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

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

The description covers the main use cases (company financial and generic factual claims), explains the return value, and notes the efficiency gain over multiple calls. It lacks explicit mention of edge cases or failure modes, but for a tool with good annotations and full schema coverage, it provides sufficient context for an AI agent to invoke it correctly.

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

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

The description adds value beyond the input schema by explaining that tolerance_pct overrides the claim's implied tolerance and suggests a specific range (1-2 for hallucination detection). The schema already has clear descriptions for both parameters, but the description provides practical usage context, justifying a score above the baseline of 3.

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

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

The description explicitly states the tool's purpose: verifying natural-language factual claims using authoritative sources. It uses clear, action-oriented language ('fact check', 'verify the claim') and distinguishes itself from sibling tools (e.g., deep_research, ask_pipeworx) by specializing in claim verification with two specific processing paths (company financial vs. other).

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 strong usage context ('Use whenever the agent needs to check whether something a user said is factually correct') and details two distinct execution paths (structured SEC EDGAR for financial claims, grounded pipeline for others). However, it does not explicitly list when not to use the tool or recommend alternative tools, leaving some ambiguity.

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