NYC Open Data

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

Annotations already indicate readOnly, idempotent, openWorld. Description adds value by specifying default model (Workers AI Llama-3.3-70b free), charging model for Anthropic (BYO key), and return structure (per-model {score, confidence, signals, raw_response} + combined view). No contradictions.

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

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

Three sentences, front-loaded with core purpose. Every sentence adds value: action, parameter details, return format and use cases. 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?

Given 4 parameters, one required, no output schema, the description covers all necessary aspects: purpose, parameters with defaults, optional key, return format, and appropriate use cases. Complete for a probing tool.

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

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

Schema coverage is 100% with descriptions. Description adds meaningful context: default for 'models', pass-through nature of '_apiKey', and examples for 'entity' and 'context'. Enhances understanding beyond schema.

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

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

The description uses specific verb 'probe' and resource 'LLMs' with clear output (visibility score 0-100). It distinguishes itself from siblings like 'scan_competitor_ai_presence' by focusing on direct LLM probing for brand visibility.

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. Explains default model and when to use _apiKey for Anthropic. Lacks explicit comparison to alternative tools but 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?

The description discloses key behaviors beyond annotations: it routes to a large toolset, fills arguments, returns structured answers with pipeworx:// citation URIs, and works on every tier with one fast call. It implicitly notes limitations by recommending ask_pipeworx_grounded for hallucination-resistant responses, providing useful context 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 long but efficiently packed with actionable information, starting with the most critical directive ('PREFER OVER WEB SEARCH') and including concrete examples. Each sentence serves a purpose—usage guidance, alternatives, and return contract—so it earns its length.

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

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

Given the tool's complexity and lack of output schema, the description provides essential context: return format (structured answer with citations), use cases, and relationships with sibling tools. It leaves little ambiguity for an agent selecting or invoking the 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 parameters (question and its aliases) are fully described in the schema, covering 100% of inputs. The description does not add syntax details beyond the schema but provides examples of natural language queries, which keeps the baseline at 3.

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

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

The description clearly identifies the tool's core function: routing questions to 5,529 tools across 1,455 verified sources and returning structured answers with citations. It distinguishes itself from siblings like ask_pipeworx_grounded and deep_research by specifying when each is appropriate.

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 instructs to prefer this tool over web search for factual questions, names it the default entry point, and provides specific trigger phrases like 'what is', 'look up', 'find', etc. It also gives clear alternatives: ask_pipeworx_grounded for hallucination-resistant single answers and deep_research for broad multi-part questions.

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

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

Annotations already cover safety (readOnly, idempotent, not destructive). The description adds valuable behavioral context: it is a full working router, not a stub, and may behave differently when a candidate is under test. It also discloses the current parity with ask_pipeworx, which is 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?

Four sentences, each serving a distinct purpose: beta status, current state, usage instruction, and assurance it is fully functional. The last sentence clarifies a potential misconception about 'falls back to nothing,' earning its place. Slightly verbose but efficient overall.

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

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

For a beta variant with a sibling relationship, the description is remarkably complete: it states the tool's identity, current behavioral equivalence to ask_pipeworx, how to invoke it appropriately, and that it is a complete router. No output schema is needed since the response shape mirrors ask_pipeworx. The agent has all necessary context for selection and invocation.

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

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

The input schema is fully self-documenting (100% coverage) with all six parameters (question plus five aliases) described. The description adds no parameter-specific semantics beyond 'same arguments,' but the schema carries the burden, so baseline 3 applies.

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

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

The description clearly defines the tool as a beta version of ask_pipeworx, an identical universal router with the same 5,529 tools and arguments. It distinguishes itself from the stable sibling by emphasizing the experimental routing candidate aspect, which is specific and actionable.

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

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

Provides explicit when-to-use guidance: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also clarifies the current state (no active candidate, matches ask_pipeworx exactly) and contrasts with the stable router, giving implicit alternative guidance.

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

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

Beyond the annotations (readOnly, idempotent, etc.), the description reveals the internal process: it routes through 5,529 tools, fetches data, then extracts only from the result. It precisely documents the success return shape and the explicit refusal variants with reasons, plus the extra LLM call cost. This goes well beyond annotation hints.

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

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

Although the description is long, it is densely packed with distinct value: purpose, process, return contract, use cases, and cost/alternative. It is front-loaded with the core message, and every clause earns its place. Structure is logical: definition → mechanism → contract → guidance.

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

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

The tool is complex (orchestrates many sub-tools) and has no output schema, so the description must fully explain return behavior. It does: success fields, refusal reasons, and data-truncation failure. It also clarifies cost implications and high-stakes applicability, making the description complete for agent decision-making.

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

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

The input schema already covers all parameters at 100%, with each alias explicitly described as equivalent to 'question'. The description adds no new parameter-specific meaning, but none is needed because the schema is self-sufficient. Baseline 3 is appropriate.

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

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

The description opens with a specific, distinctive purpose: 'Hallucination-resistant answer mode for high-stakes reads.' It explicitly contrasts with the sibling ask_pipeworx by explaining the same routing but adding extraction from only the tool result, and even names the cost difference. This clearly separates it from sibling tools.

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

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

The description gives explicit when-to-use guidance ('Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts'), concrete examples (financial verdicts, legal claims, medical lookups), and directly names the alternative for casual use ('prefer ask_pipeworx for casual lookups'). This is exactly the kind of decision support needed.

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

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

Beyond annotations (readOnly, idempotent, not destructive), the description details behavioral traits: market resolution, classification, parallel data fan-out, evidence packet return, and safety mechanisms (low-confidence short-circuits, closed market handling, wide-spread warnings, cancellation rule parsing). 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 comprehensive but verbose, running several paragraphs with extensive examples and internal structure. While the detail is valuable, it could be more concise to avoid overwhelming the agent. It is organized into sections (CLASSIFIERS, FAN-OUT EXAMPLES, etc.), which helps, but still earns only a middle score 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?

Given the complexity of the tool (multiple data sources, safety checks, output shapes), the description covers all necessary aspects: input format, behavior, response structure (market, analysis, evidence), error states (low confidence, closed market, illiquid), and resolution rules. No output schema exists, so the description must bear the burden, and it does so thoroughly.

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

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

Input schema has 100% description coverage, so baseline is 3. The description adds value by explaining that 'market' can be slug, URL, or question text; depth default is 'thorough' with 'quick' alternative; and include_raw default false with rationale for keeping responses small. This extra context justifies a higher score.

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

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

The description clearly states the verb ('research'), the resource (Polymarket bet), and the action (pulling Pipeworx data in one call). It distinguishes from siblings by being a comprehensive one-call research tool, while siblings like polymarket_edges or polymarket_arbitrage focus on specific aspects.

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

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

The description explicitly lists use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') and provides examples of fan-out for different bet types. It also warns about inspecting resolver contracts before trusting analysis. However, it does not explicitly contrast with alternative tools or state when not to use it.

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

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

Annotations already indicate safe read operation (readOnlyHint, idempotentHint, non-destructive). Description adds valuable behavioral details: for company type, it pulls latest 10-K revenue/net income/cash/debt with correct fiscal year handling; for drug type, it pulls FAERS counts, FDA approvals, trial counts; results sorted by primary metric; returns paired data + citation URIs. 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 slightly verbose but well-structured and front-loaded with examples. Every sentence adds value, though a few could be combined for brevity. It efficiently conveys key information without redundancy.

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

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

Despite having no output schema and moderate complexity (two entity types, multiple data sources), the description is remarkably complete. It covers what data is returned per entity type, sorting behavior, fiscal year handling, and citation URIs. No significant 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%. Description goes beyond schema: explains the 'type' enum values with what data each fetches (company vs drug). For 'values', it specifies business logic (tickers/CIKs for company, drug names for drug) and implicitly confirms min=2, max=5 through usage guidance.

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

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

The description clearly states that the tool performs side-by-side comparisons of 2-5 companies or drugs in a single call, with specific examples like 'Compare X and Y', 'X vs Y', etc. It distinguishes itself from sequential lookups by noting it replaces 8-15 sequential calls.

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 'ALWAYS PREFER over sequential single-pack lookups when comparing entities'. Provides concrete use cases (e.g., ranking companies, head-to-head) and explains the efficiency gain (replaces 8-15 sequential lookups).

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive). The description adds context about output fields and relation to metadata tool, but no further behavioral details like pagination behavior or rate limits.

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

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

The description is two sentences, front-loaded with purpose, and contains no extraneous 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 schema covers all parameters and annotations are present, the description sufficiently outlines return fields and hints at next steps. It lacks explicit pagination description but is adequate for the tool's complexity.

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

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

Schema coverage is 100%. The description adds no additional parameter semantics beyond what the schema already provides.

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

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

The description clearly states the verb (search), the resource (NYC Open Data catalog), and the output fields. It distinguishes itself from siblings by specifying this unique scope.

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

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

The description implies when to use (when searching datasets by keyword) and provides a workflow hint (pass resource_id to query/metadata). However, it does not explicitly exclude alternative tools.

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

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

Beyond the read-only/idempotent annotations, the description discloses significant behavioral traits: it never invents information and returns explicit gaps[], the output includes a findings packet with evidence, confidence, source, fetched_at, and citation_uri, and it explains depth-level behaviors like gap recovery, contradictions[], and semantic excerpting. Timing expectations (15-60s) and account requirements are also disclosed, which annotations do not cover.

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

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

Although long, every sentence carries essential operational information: account requirements, alternatives, scope, return format, citation behavior, depth semantics, and timing. The description is front-loaded with the most critical decision factors (account required, use ask_pipeworx otherwise) and stays dense without redundancy. This level of detail is justified for a tool with this complexity.

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

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

The description fully compensates for the absence of an output schema by detailing the findings packet structure (verbatim evidence, confidence, source, fetched_at, pipeworx:// citation, gaps[], contradictions[], hop field). It also covers edge cases like unanswerable facets, semantic excerpting for large records, and expected latency, making it highly complete for an AI agent to select and invoke the tool without further clarification.

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

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

The input schema already provides 100% coverage with rich descriptions for both parameters. The tool description adds value by explaining the depth parameter's practical effects (gap recovery, contradiction scans, paid plan) and giving example questions for the question parameter, going beyond the schema's basic type definitions. However, much of the param behavior is already captured in schema descriptions, so this is a modest improvement.

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: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' and explains the decomposition/routing process. It distinguishes itself from siblings by emphasizing this is 'NOT open-web search' and contrasting with ask_pipeworx for single lookups. The examples of multi-part questions further clarify its intended scope.

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

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

The description provides explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data' and directly names alternatives for other cases ('For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS ... prefer ask_pipeworx'). It also includes account requirements and a fallback if not signed in, making the decision boundary 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 behavioral detail: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' This goes beyond annotations, but lacks info on potential auth needs or rate limits, though none likely exist.

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 at 4-5 sentences, front-loaded with the core purpose, then usage guidance, then return value details, and ends with a strategic directive ('Call this FIRST'). Every sentence adds meaningful information with no redundancy or filler.

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

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

Given the tool's complexity (6 params, no output schema, no nested objects), the description adequately covers what it does and what it returns. It mentions the top-N results and that schemas are included. However, it does not address pagination, sorting, or whether results include relevance scores, which would make it fully complete.

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

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

Schema coverage is 100% and all parameters are described, but the description adds value by explaining the query parameter expects a 'natural language description' and provides examples. It also clarifies that multiple aliases (q, task, search, description) map to query, and specifies default limit of 20. This is helpful context beyond the schema's individual descriptions.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It provides specific examples of use cases (SEC filings, financials, etc.) and distinguishes itself from siblings by instructing to call this FIRST when many tools are available. The verb 'discover' and resource 'tools' are specific and unambiguous.

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

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

The description explicitly states when to use: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available.' It implies when not to use by saying 'not just one answer,' but does not explicitly list alternatives or exclusions, which would elevate the score to 5.

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

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

Discloses parallel call behavior, fan-out across multiple sources, patent soft-fail timeline, and return structure. Annotations already declare readOnlyHint, so this adds context without contradiction.

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

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

Dense but front-loaded with examples and clear one-paragraph structure. Every sentence adds value, though could benefit from bullet points.

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

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

No output schema, but description lists all returned fields (cik, filings, fundamentals, patents, news, LEI) and explains format. Addresses tool's scope and limitations adequately.

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%. Description adds real-world examples ('AAPL', '0000320193'), clarifies type enum and value format, and reinforces name restriction 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 returns a full cross-source profile for US public companies, lists data sources and outputs, and distinguishes from chaining single-pack lookups.

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

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

Explicitly says 'ALWAYS PREFER over chaining single-pack...' for holistic views, warns against using names, and advises using resolve_entity if only a name is available.

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

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

Annotations already indicate destructive and non-read-only behavior; description adds context about clearing sensitive data but doesn't significantly expand 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, no wasted words, front-loaded with primary purpose.

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

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

Sufficient for a single-parameter destructive tool with high schema coverage; covers purpose, when-to-use, and pairing with siblings.

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

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

Schema has 100% coverage for the single required parameter 'key' with clear description; description adds no extra semantics beyond 'by key'.

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

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

Clear verb+resource: 'Delete a previously stored memory by key.' Explicitly distinguishes from sibling tools 'remember' and 'recall'.

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

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

Provides explicit when-to-use scenarios (stale context, task done, clear sensitive data) and references sibling tools for context, but lacks 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=true, idempotentHint=true, etc. The description adds beyond that by detailing the process (fetches page, extracts title/description/key links) and output format (standard llms.txt markdown), which is helpful and non-contradictory.

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 purpose, followed by process and use cases. Every sentence adds value, no redundancy, and it efficiently communicates the tool's role.

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

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

Given no output schema, the description adequately explains the output format and process. The tool is simple with two clear parameters; all essential aspects are covered for an agent to select and invoke it correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add meaning beyond the schema's descriptions for 'url' and 'max_links'; it reinforces them but provides no new details about parameter behavior or constraints.

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 a llms.txt file for a URL, specifies the verb 'generate' and resource, and distinguishes from sibling tools like 'ai_visibility_check' by listing explicit use cases (getting a client's site indexed, drafting for own project, auditing competitors).

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 use cases for when to use the tool, but does not explicitly state when not to use it or compare it to alternative sibling tools. The context is clear, but exclusions are absent.

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 that it returns specific fields and that it's the caller's subscriptions, but no additional behavioral traits 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?

Two sentences, front-loaded with the core purpose. No wasted words; every sentence adds value.

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

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

Given the simple structure (1 parameter, no output schema, rich annotations), the description adequately covers purpose, return fields, and usage context. No major 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 description coverage is 100% (the single parameter 'include_inactive' is documented in the schema). The description adds no extra meaning beyond what the schema provides.

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

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

The description clearly states 'List the caller's active subscriptions,' providing a specific verb and resource. It distinguishes from sibling tools like 'subscribe' and 'unsubscribe' by implying this is for reviewing existing subscriptions.

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

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

The description advises using this to review monitoring before adding more or to find an ID to cancel, giving explicit context. It does not include when-not-to-use, but the guidance is still 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, openWorldHint, idempotentHint, and destructiveHint false. Description adds that it returns schema/metadata, but does not disclose further behavioral traits 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?

Single sentence with all essential information: verb, resource, outputs, and example. No wasted words, front-loaded with purpose.

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

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

Given a single parameter, rich annotations, and no output schema, the description adequately lists return fields. Slightly incomplete on potential error cases or limits, but sufficient for a straightforward metadata lookup.

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

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

Schema coverage is 100% for the single parameter 'resource_id', with both schema description and tool description providing example value. Description adds minimal extra meaning beyond a repetition of the example.

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 verb 'Get' and resource 'a NYC Open Data dataset's schema + metadata', listing specific fields (columns, types, row count, etc.). It differentiates from siblings like 'datasets' and 'query' by focusing on metadata 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?

No explicit guidance on when to use this tool vs alternatives. Sibling tools include query and datasets, but no comparison or condition for selection is provided.

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 annotations only provide generic hints (readOnlyHint=false, etc.), so the description carries the full burden. It discloses the claim_token flow (filing returns a token, passing it back later reads status and changes), rate-limiting (5/day), that it's free and doesn't count against quota, and that the team reads digests daily. There is no contradiction with annotations; on the contrary, the description adds vital non-obvious behavior beyond what annotations could convey.

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

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

The description is longer than average, but it is front-loaded with the core purpose and every subsequent sentence adds distinct value: usage conditions, exclusions, token mechanics, rate limits. The sentence about roadmap signal is slightly motivational and could be trimmed, but overall it remains well-structured and not redundant. A 4 reflects the slight extra verbosity while acknowledging the appropriate length 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?

There is no output schema, yet the description covers return behavior for both the initial submission (returns a claim_token) and follow-up (returns status and changes). It also covers rate limits, exclusions, and parameter usage context. For a simple feedback tool with unusual token flow, this description is remarkably complete.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful context for the claim_token parameter by explaining the submission→token→follow-up lifecycle, and for message by advising to frame issues in terms of Pipeworx tools/packs. While the schema already describes each parameter well, this extra context nudges the score to 4.

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

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

The description begins with a clear, specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It enumerates concrete use cases (bug, feature/data_gap, praise) and explicitly distinguishes itself from sibling tools like ask_pipeworx by clarifying this is for reporting to the Pipeworx team, not for querying data. The purpose is unmistakable and well-differentiated.

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

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

The description provides explicit when-to-use guidance with concrete triggers ('Use when a tool returns wrong/stale data...'), and explicit when-not-to-use guidance with an alternative ('if the tool came from a different MCP server... file it with that server instead'). It further disambiguates by advising 'Pipeworx tool names are the ones this connection lists.' This is a model of usage clarity.

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 beyond annotations by explaining the data source (CF analytics-engine), privacy (no PII), caching behavior (5min-1h depending on window), and the self-aggregating nature. It is fully transparent about how the tool works and its limitations, with no contradictions to annotations.

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

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

The description is concise with three sentences that cover purpose, use cases, and behavioral details. The use of bullet-like formatting for use cases improves readability. Every sentence adds value, though it could be slightly more compact.

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, no nested objects), the description is complete: it covers what is returned, when to use it, how it works (caching, privacy, aggregation), and the meaning of the parameter. No gaps remain.

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

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

The single parameter 'window' has full schema coverage with enum values and a description. The description enriches this by explaining the semantic difference between shorter and longer windows ('Shorter windows surface what's hot right now; longer windows show steady-state demand'), adding value beyond the schema.

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

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

The description clearly states the tool returns top tools, top packs, and total call volume over a recent window. It specifies the verb ('returns') and resource ('top tools, top packs, and total call volume'), and distinguishes it from sibling tools by focusing on trending/social proof rather than direct queries or other functions.

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

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

The description provides three specific use cases (discovering hot data sources, confirming canonical choice, seeing alignment) and explains when to use different windows (shorter for hot topics, longer for steady-state). It does not explicitly state when not to use the tool, 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 indicate read-only, idempotent, open-world behavior, which the description matches. It adds extensive behavioral details: monotonicity checks, partition-sum checks, Jaccard similarity threshold (≥0.30), placeholder filtering, fill check against live CLOB depth, and conditions under which to avoid trading. No contradiction with annotations.

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

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

The description is well-structured with clear sections for each mode and key concepts (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). It front-loads the main purpose and mode selection. Every sentence adds necessary detail for a complex arbitrage tool, making it efficient despite its length.

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

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

Given the tool's complexity (two modes, multiple filters, output specification), the description covers all necessary aspects: inputs, processing logic, output format, and fill check details. It also directs the agent to polymarket_fill_risk for custom sizing, ensuring completeness without needing an output schema.

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

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

Schema coverage is 100% but the description adds substantial meaning beyond the parameter descriptions. It explains how event and topic modes work, gives example inputs, describes algorithm steps (partition_check, cross-event scanning, similarity filters), and details the output structure. This greatly helps an agent select and invoke the tool correctly.

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

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

The description starts with 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks', providing a specific verb and resource. It clearly distinguishes the tool's purpose from siblings by mentioning polymarket_fill_risk for custom sizing, and explains the two modes (event and topic) in detail.

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 no args (trending scan), event mode (specific market), and topic mode (cross-event scanning). It also warns about fill check failures and recommends polymarket_fill_risk for custom sizing. However, it does not compare this tool to other Polymarket siblings like polymarket_edges or polymarket_kalshi_spread.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds rich behavioral details: caching (1h KV-level), edge calculation (including slippage subtraction, Kelly caps), handling of placeholder slugs and partition filters, and a note on the unreliability of Fed signals. 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 exceptionally thorough but quite long (500+ words). It front-loads key information but dives into deep technical details (e.g., specific alpha values for sports, exact thresholds). While well-structured with numbered sections, the length may hinder quick parsing by an AI agent.

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

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

Given the tool's complexity (3 model families, multiple filters, and no output schema), the description covers all essential aspects: input parameters, return structure (by_segment, fed_candidates, _diagnostics), individual opportunity fields (edge_pp_net, kelly_fraction), and caveats (e.g., placeholder filter, Fed note). It enables an agent to use the tool effectively 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?

Schema coverage is 100%, but the description adds significant context beyond parameter descriptions. For example, it explains how min_partition_leg_kelly works differently for partition arbs, clarifies the effect of min_liquidity and max_spread_pp as tradeable-edge filters, and interprets the category_filter by listing segments. This helps an agent understand parameter impact beyond schema 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 specifies a clear verb ('scan') and resource ('Polymarket markets'), and the outcome ('return opportunities where Pipeworx data disagrees with market price'). It is tailored for a specific use case ('what should I bet on today') and distinguishes from siblings by detailing unique segments (e.g., MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT) and a Fed bet note.

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

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

The description states it's built for daily opportunity discovery and notes caching and diagnostic outputs, but does not explicitly contrast with sibling tools like polymarket_arbitrage or polymarket_edge_tracker. However, the detailed description of segments implicitly guides when to use which filter, and the Fed note provides specific context for exclusion.

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 already indicating readOnly, idempotent, and non-destructive, the description adds critical behavioral details: history depth bounded by 60-day TTL, decay computed from daily closes not intraday, snapshot gaps meaning no scan that day, and how expired opportunities are tracked. This goes well 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?

Description is long but every sentence adds value. It is well-structured with sections for RESPONSE and LIMITS, front-loads the core purpose, and avoids redundancy. No wasted words.

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

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

With no output schema, the description fully explains the response structure (tracked[], expired[], snapshot_dates[]) and the meaning of each field (e.g., trend values, decay_pp_per_day, lifespan_days). This provides complete context for an agent to understand what the tool returns.

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. The description reiterates defaults and bounds (days: default 14, clamp 2-30; window: default '1wk') but does not add significant new semantics beyond the schema. 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 clearly states it provides 'edge persistence and decay telemetry' from daily snapshots, answering the specific question about how long an edge has existed and whether it's shrinking. This distinguishes it from sibling tool polymarket_edges which likely just provides current snapshot data.

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 context on when to use the tool by contrasting fresh wide edges vs. 3-week-old wide edges. It implies that this tool should be used when historical edge persistence matters but does not explicitly list alternatives or exclusion criteria.

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

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

Annotations already provide readOnlyHint, so the bar is lower. The description adds behavioral details like walking the ladder, returning a verdict (clean/degraded/cannot_fill), and identifying thin legs and forced directional risk, which goes beyond the annotations.

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

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

The description is front-loaded with the core purpose and structured into clear sections (single-market, basket). It uses bold and caps for emphasis without being wasteful. While somewhat long, every sentence carries useful 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?

Despite having no output schema, the description thoroughly enumerates return fields for both modes (e.g., vwap_fill_price, capture_ratio, thin_legs). It also relates to sibling tools, explains mode selection, and warns about risks, making it complete for a complex tool.

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

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

Schema coverage is 100% with descriptions, but the tool description adds context beyond schema descriptions (e.g., how size_usd is interpreted differently in single vs basket mode, and default side logic for basket). This adds value 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 states the tool performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth,' which is a specific verb+resource. It clearly distinguishes between single-market and basket modes, and its purpose is distinct from sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

Explicitly states 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It warns about the risk of partial fills and thin books, providing clear when-to-use and why guidelines.

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 annotations (readOnlyHint, idempotentHint, etc.) are complemented by a thorough description of behavior: two modes, response structure, safety fields, and conditions for meaningful results (e.g., compatibility_warning cases, temporal alignment). No contradictions with annotations.

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

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

The description is well-structured, starting with the core purpose, then detailing modes, response fields, and safety warnings. Every sentence adds value, and the length is justified by the tool's complexity. It is front-loaded with essential information.

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

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

Given the absence of an output schema, the description fully covers the return values (e.g., spread, compatibility_warning, temporal_alignment) and explains edge cases. It is comprehensive for a tool with three optional parameters and no required fields.

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

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

Schema coverage is 100%, and the description adds significant value by explaining the two parameter modes, the list of valid topics, and how explicit tickers override the topic-mapped sides. This goes beyond the schema's basic descriptions.

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

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

The description clearly states the tool's purpose: computing cross-venue spread between Kalshi and Polymarket for the same resolving question. It uses specific verbs and resources, but does not explicitly distinguish itself from the sibling tool 'polymarket_arbitrage', which may have a similar scope.

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

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

The description explains two usage modes (topic shortcuts and explicit tickers) and provides context for when spreads are meaningful via safety fields like compatibility_warning and temporal_alignment. It warns that most pre-mapped topics are not tradeable. However, it does not explicitly mention when to use alternatives like polymarket_arbitrage.

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 and idempotentHint=true. The description adds that it returns JSON rows. No contradiction. Could mention default limit or error handling.

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?

One sentence that front-loads the action and key parameters. No wasted words, appropriately sized.

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 7 parameters and no output schema, the description covers the essential: what it does, how to filter, return format. It could add more about dataset ID guidance or error behavior.

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

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

Schema coverage is 100%, so each parameter already has a description. The description adds valuable context that SoQL clauses should be without the leading $, which 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 clearly states 'Run a Socrata SoQL query against a NYC Open Data dataset by resource_id'. It specifies the verb (run), resource (dataset), and key parameter (resource_id), and distinguishes the tool from siblings like 'datasets' or 'search_within' by focusing on SoQL querying.

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

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

The description mentions filtering with SoQL clauses and pagination. While it provides context for usage, it does not explicitly state when not to use this tool or list alternative tools.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds scoping info ('Scoped to your identifier') and the pairing with other tools. No contradiction, and the description adds meaningful context beyond annotations.

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

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

Two concise sentences. The first sentence states the core purpose and optional listing behavior. The second provides example usage scenarios and scoping. No unnecessary words, front-loaded with the most critical 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 retrieval tool with one optional parameter and no output schema, the description covers everything needed: the action, the sibling tools, example contexts, and scoping. It is complete and leaves no ambiguity.

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

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

Schema coverage is 100% (the 'key' parameter has a description). The description adds meaning by explaining that omitting the key lists all saved keys, which goes beyond the schema's description. For a single parameter, this is clear and helpful.

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

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

The description clearly states the tool retrieves a value saved via 'remember' or lists all saved keys. It specifies the resource (saved values) and distinct action (retrieve/list), distinguishing it from siblings like 'remember' and 'forget'.

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

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

The description provides explicit when-to-use guidance: 'to look up context the agent stored earlier' with concrete examples (ticker, address, notes). It mentions companion tools ('remember' and 'forget') but does not explicitly exclude use cases like real-time data retrieval, though the context implies it.

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

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

The description states that setting mark_read:true flags returned events as read, which is a side effect (modifying read state). This contradicts the annotation readOnlyHint=true, which implies no data modification. The contradiction is serious and misleading for the agent. While other behaviors like return fields are disclosed, the key behavioral detail conflicts with annotations.

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

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

The description is three sentences with no redundant information. It front-loads the purpose, then details return fields and filtering, then adds a note about mark_read and alternative endpoint. 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?

Despite the annotation contradiction, the description covers all aspects: what it returns (source, citation_uri, payload), filtering options (type, since, mark_read, unread_only), side effect of mark_read, and alternative access method. Without an output schema, it provides sufficient context for an agent to understand inputs 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 coverage is 100%, providing a baseline of 3. The description adds value by explaining each parameter's effect: type filters subscription type, since filters by fired_at, mark_read flags as read, unread_only returns only new events. It also gives an example type 'sec_8k', enhancing understanding 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 'Pull fired events from your subscription feed,' specifying a specific verb and resource. It distinguishes the tool by identifying the source (subscription feed) and the kind of data (alerts from evaluator), setting it apart from siblings like 'query' or 'recent_changes'.

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

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

The description mentions that polling works fine and provides an alternative REST endpoint for scripts/dashboards, giving some context on usage. However, it does not explicitly state when to use this tool over other tools (e.g., 'query') or when not to use it. The mention of an alternative is helpful but not full guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint. The description adds important behavioral details: parallel fan-out to multiple sources, fallback logic (GDELT→GNews), patent soft-fail, and structured return format with citation URIs. No contradictions with annotations.

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

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

The description is a single dense paragraph, but every sentence adds value. It front-loads examples and purpose, then flows into technical details. A slight structural improvement (e.g., bullet points) could enhance readability, but it remains efficient and focused.

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

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

Despite the lack of an output schema, the description fully explains the return structure (changes[] grouped by source, total_changes, citation URIs). It covers edge cases (GDELT rate limits, patent API sunset) and provides alternative tool guidance, making it complete for a tool of this complexity.

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

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

Schema coverage is 100% with descriptions for all 3 parameters. The description adds value by explaining the `since` parameter's acceptance of ISO dates and relative shorthands (e.g., '7d', '30d'), and that `value` accepts tickers or CIK numbers. It enriches 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?

The description uses specific verbs ('change feed for a company') and names the covered sources (SEC, GDELT/GNews, USPTO). It includes example queries and explicitly distinguishes from the sibling tool 'entity_profile', making purpose unmistakable.

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

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

The description provides explicit usage context: 'What's new with X' queries and explains fallback behavior. It also states when NOT to use the tool: 'Use entity_profile instead when you want the static profile...' This leaves no ambiguity for an AI agent.

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

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

Beyond annotations (idempotentHint=true, destructiveHint=false), description adds details: key-value scoping by identifier, persistence differences for authenticated vs. anonymous sessions. Does not contradict annotations.

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

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

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

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

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

Given no output schema, description adequately explains retrieval via recall and deletion via forget. Covers key aspects of a memory store 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 has 100% coverage and descriptions. Description adds meaning beyond schema with examples like 'subject_property' and 'value to store (findings, addresses, preferences, notes)', enriching 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?

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

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

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

Explicitly states when to use: 'when you discover something worth carrying forward'. Also provides pairing with recall and forget, giving clear context for usage.

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 meaningful behavioral context: identifiers are labeled with sources, unresolved identifiers are explicitly listed, and LEI/FIGI enrichment degrades gracefully if external sources are unavailable. This adds transparency beyond the annotations, though it stops short of discussing rate limits or pagination.

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

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

The description is long but every sentence adds value. It is front-loaded with relatable query examples, then defines purpose, supported types, and behavior. The structure could be tightened (e.g., move 'SUPPORTED TYPES' earlier), but it is not wasteful.

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

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

Given a 2-parameter tool with no output schema, the description is remarkably complete: it explains return contents, source attribution, handling of unresolved identifiers, and graceful degradation. It covers all relevant usage scenarios and edge cases, so an agent can invoke the tool confidently.

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

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

Schema description coverage is 100%, so baseline is 3. The description enriches parameter meaning substantially: for 'type' it details what each entity type returns (CIK/ticker/LEI/FIGI for company, RxCUI/ingredient/brand for drug); for 'value' it gives concrete examples and accepted formats. This goes well beyond the schema.

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

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

The description uses a clear verb ('resolve') and resource ('user-spoken NAME to canonical/official identifiers'), supported by rich examples of user queries. It explicitly distinguishes from siblings by stating 'Use FIRST whenever you have a name but need an ID' and enumerates supported entity types.

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

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

The description gives explicit usage guidance: 'Use FIRST whenever you have a name but need an ID.' It provides concrete trigger phrases ('What's the ticker for…', 'find the CIK for…') and explains that it replaces 2-3 manual lookups, clarifying its role vs. 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 indicate safety (readOnly, idempotent, not destructive). Description adds details: probes each entity with ai_visibility_check, ranks by score, returns ranked list with metrics (score, confidence, signal density). No contradictions.

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

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

Three sentences: main action, process description, use case and return format. Efficient and front-loaded. No superfluous 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?

No output schema, but description specifies return format (ranked list with score, confidence, signal density). Covers purpose, usage, parameter roles, and return info. Complete for a tool with this complexity.

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

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

Schema covers 100% of parameters. Description adds context: first entity is treated as subject, context disambiguates. This adds meaning beyond schema descriptions.

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

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

Clearly states verb (compare), resource (AI visibility), and scope (multiple entities). Distinguishes from sibling ai_visibility_check (single entity) and compare_entities (generic).

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 use case provided ('competitive AI-marketing audits') and implies when to use this over single-entity check. Could add explicit when-not-to-use, but 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 (readOnlyHint, idempotentHint, etc.) are consistent. Description adds behavioral details: composite nature, partial failures, bundlephobia timeout, and sources_failed field. 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 slightly lengthy but well-structured with a clear purpose, usage, return summary, and limitations. Front-loaded with the core purpose. Every sentence adds 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?

Despite no output schema, the description enumerates the return fields (summary block, per-advisory detail, links, alternative versions). Covers limitations and partial failures. Adequate for a composite tool with multiple data sources.

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

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

Schema covers both parameters with 100% description coverage. Description adds practical context: scoped packages accepted, version defaults to latest. This provides additional value beyond the schema, though baseline is already high.

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

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

The description clearly states the tool's purpose: a composite check for npm packages combining deps.dev and bundlephobia data. It specifies the exact use case ('is X safe / popular / small') and distinguishes from sibling tools by focusing on npm dependency analysis.

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

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

Explicitly states when to use: when an agent asks about npm package safety, popularity, or bundle cost. Also clarifies ecosystem scope (npm only) and directs users to deps.dev:version for other ecosystems. No ambiguity.

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

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

Discloses beyond annotations: uses BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation flag, returns offsets. Annotations only show readOnlyHint and idempotentHint; description adds critical 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?

Compact, front-loaded with purpose and key benefit. Each sentence adds value; no fluff.

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

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

Covers usage, behavior, and pairing advice. No output schema exists, but description mentions return content (passages, offsets, scores). Missing explicit statement of 'top-N passages' but implied.

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

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

Schema already describes all 3 parameters (100% coverage). Description adds query examples and char limit context but doesn't significantly extend meaning.

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

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

Describes specific operation: semantic search inside a fetched record. Differentiates from sibling tools like ask_pipeworx_grounded by explicitly stating it works over retrieved text, not a database.

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

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

Explicitly states when to use: when a record is too large for the prompt. Names alternative: ask_pipeworx_grounded for grounded answers over passages.

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 authentication requirement, return value, delivery channel behavior, SMS cap, and webhook auto-disable, adding significant 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?

Well-organized with clear sections and front-loaded key info, though slightly lengthy; 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?

Comprehensively covers return value, input options, authentication, limitations, and examples, leaving no gaps for this 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?

Enriches schema with type-specific examples, constraints, and validation details (e.g., phone verification, webhook signature) despite 100% schema coverage.

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

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

Description clearly states it creates a subscription, listing supported types and delivery channels, distinguishing it from sibling tools like list_subscriptions and unsubscribe.

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

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

Provides prerequisites (OAuth account) and limitations (SMS cap, phone verification) but does not explicitly contrast with sibling tools or state when not to use.

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

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

Annotations already indicate safe, read-only, idempotent behavior. The description adds valuable details: returns category-bucketed example questions with tool/argument shapes, drawn from live catalog, and supports optional topic focus. 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 front-loaded with common queries, then explains purpose, output, and optional argument. It is comprehensive without being verbose, though slightly long for a one-parameter tool.

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

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

Despite no output schema, the description adequately describes the return content (category-bucketed example questions with tool/argument shapes). The tool has a simple, single optional parameter, and the description covers all relevant aspects for usage.

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

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

Schema provides full enum values for 'topic' and marks it optional. The description enhances this by listing examples of topics and explaining behavior when omitted ('full spread' vs. 'focus'), adding practical usage context beyond the schema.

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

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

The description clearly states the tool returns example questions for onboarding, with categories and tool shapes. It is distinct from siblings like 'ask_pipeworx' or 'discover_tools' by positioning itself as the entry point for new agents.

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 to use this tool first when unsure of capabilities: 'Use this FIRST when you do not yet know what Pipeworx can do for you'. Also explains calling with no arguments vs. with topic, providing clear context for when and how to invoke.

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 key behavioral context beyond annotations: ownership limitation, deactivation vs deletion, historical availability. No contradiction with annotations.

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

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

Two sentences, front-loaded with action and resource, no wasted words. Every sentence provides essential information.

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

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

Covers action, parameter, behavior, and consequences. No output schema needed; description provides sufficient context for a simple 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 already fully describes the parameter (id as uuid from subscribe), and description does not add extra detail. Baseline score 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 'Cancel a subscription by id' with specific verb and resource. Distinguishes from sibling 'subscribe' and explains deactivation vs deletion.

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

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

Explicitly states ownership enforcement and that rows are deactivated not deleted, guiding when to use and effect on history. Could be more explicit about alternatives but sufficient.

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

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

Annotations declare readOnly, openWorld, idempotent, and non-destructive, but the description adds crucial behavioral nuance beyond that: it defines the meaning of 'could_not_verify' (check did not happen, must not be shown as evidence), distinguishes it from 'unsupported', and explains the fallthrough routing from SEC EDGAR/XBRL to the grounded pipeline. This prevents misinterpretation of results.

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 front-loads trigger phrases, then explains pipelines, verdicts, and error semantics. Each sentence carries operational value, though some phrasing could be tightened (e.g., the long parenthetical list of claim types). Overall, the length is justified by the tool's complexity.

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

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

Despite having no output schema, the description fully enumerates all possible verdict values (confirmed, approximately_correct, refuted, inconclusive, unsupported, could_not_verify), describes the return contents (actual value with pipeworx:// citation, reasoning), and explains the distinct meanings of could_not_verify vs unsupported. It also mentions the structured vs grounded routing and the replacement of sequential calls, making it self-sufficient for callers.

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?

Since the input schema already covers 100% of parameters, the baseline is 3. The description goes beyond the schema by explaining how tolerance_pct overrides the implied tolerance, recommends 1–2 for hallucination detection, and notes the default is capped at 5. It also gives concrete examples for the claim parameter, adding real usage guidance.

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 'natural-language claim verification against authoritative sources' and includes explicit trigger phrases like 'fact check' and 'verify the claim that…'. It also distinguishes itself from sibling tools by noting it replaces 4–6 sequential calls (NL parsing → entity resolution → data lookup → comparison), giving a specific verb+resource+scope.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and differentiates the fast path for company-financial claims from the grounded pipeline for all other factual claims. However, it does not name or exclude specific sibling tools (e.g., ask_pipeworx_grounded, deep_research), so it lacks explicit alternatives but still provides clear context.

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