Census

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

The description discloses that a default free model is used, that an API key is required for Anthropic probing (with cost implications), and the return format (per-model {score, confidence, signals, raw_response} + combined view). Annotations already indicate read-only, idempotent, non-destructive behavior, so the description adds valuable context beyond those 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 two sentences that front-load the core purpose and immediately convey the most important details (default model, optional Anthropic probing, return format, use cases). There is no wasted text; every sentence earns its place.

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

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

Given that there is no output schema, the description adequately summarizes the return structure (per-model fields and combined view). It covers the key behavioral aspects (model choice, API key usage) and use cases. While it could elaborate on the combined view or rate limits, the description is sufficient for an agent to invoke the tool correctly.

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

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

Schema coverage is 100% with descriptions for each parameter. The tool description adds value by stating the default model ('Workers AI Llama-3.3-70b') and clarifying that `_apiKey` is specifically for Anthropic and that the user pays Anthropic directly, which goes beyond the schema description.

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

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

The description uses a specific verb ('Probe'), clearly identifies the resource ('LLMs for what they know about a business/brand/product/topic'), and states the output format ('score visibility (0-100) per model'). It distinguishes itself from siblings by focusing on AI visibility scoring across multiple models, which none of the listed siblings do directly.

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: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It does not explicitly state when not to use it or name direct alternatives, but the context is clear enough for an agent to decide appropriately.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds valuable context: it routes to sub-tools, fills arguments, returns stable citation URIs, and works on every tier. It doesn't mention latency or failure modes, but the annotation coverage is strong, so this goes beyond baseline.

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

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

The description is longer than average but front-loaded with the key directive ('PREFER OVER WEB SEARCH'), followed by domains, examples, and routing rules. It's dense but every sentence serves a purpose — examples, alternatives, and conditions. Slightly verbose but structured logically; loses a point for wordiness.

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 (routing to 5,635 sources) and the absence of an output schema, the description is remarkably complete: it covers when to use, what it returns (structured answer with citations), alternatives, and examples. No critical gap for an agent deciding to invoke it.

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

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

Schema description coverage is 100% — every parameter (including five aliases) is documented in the schema. The description adds no new parameter details beyond noting examples, which is a baseline 3. Aliases are already documented in the schema, so no penalty but no enhancement.

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

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

The description states a specific verb+resource: 'Answers questions routed to one of 5,635 tools across 1,477 verified sources'. It lists concrete domains and provides example queries, which strongly distinguishes it from generic search tools. The purpose is unambiguous and action-oriented.

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

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

Explicitly says 'PREFER OVER WEB SEARCH' and 'START HERE for most questions', providing clear when-to-use criteria. It also names alternatives (ask_pipeworx_grounded, deep_research) and gives conditions for stepping up to them, plus a specific carve-out for breaking news. This is exemplary routing guidance.

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

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

Annotations already mark readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds transparent value by explaining the beta/experimental nature, that routing candidates can be enabled live, and that it falls back to nothing (i.e., it is a full working router). It also notes the current status (no active candidate) and the comparison against the stable router.

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

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

The description is somewhat long (5 sentences) but each sentence carries substantive info: beta status, identity, current state, usage guidance, and reassurance of full functionality. Key information is front-loaded with 'Beta version of ask_pipeworx'. Minor redundancy exists ('Falls back to nothing' clarifies what could be confused), but overall it is well-structured.

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

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

For a universal router, the description is quite complete: it states the same 5,635 tools, same arguments, same response shape, and explicitly confirms it is fully functional, not a stub. It does not describe the exact response format, but references to ask_pipeworx make that discoverable. Current active-state and merge-decision purpose are also covered.

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

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

Schema description coverage is 100% — all parameters, including aliases, are individually documented. The description does not add parameter-specific details, but with full schema coverage the baseline of 3 is appropriate. No compensation is needed.

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

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

The description states a clear purpose: a beta version of ask_pipeworx, a universal router. It specifies the resource (Pipeworx Beta) and immediately distinguishes it from its stable sibling ask_pipeworx. It also notes the identical tool count and args, so an agent knows exactly what it does.

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

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

Explicit guidance is given: 'Use it exactly like ask_pipeworx when you want the newest routing'. It contrasts with the stable router and explains that results are compared to decide merges. It also clarifies that no candidate is active, so it currently matches ask_pipeworx exactly. This leaves no ambiguity about when to pick this tool.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints, and the description adds valuable behavioral details: the exact return structure (answer, evidence, confidence, source, fetched_at, refusal_reason), the explicit refusal reasons, and the fact that it makes an extra LLM call. This goes well beyond annotations and clarifies how the tool handles failure.

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 bit lengthy but each sentence adds essential information: the core feature, routing details, return format, usage guidance, and cost trade-off. The most critical info ('hallucination-resistant') is front-loaded, and there's no redundancy. Slightly verbose but well-structured.

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

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

Given the tool's complexity (internal routing, refusal cases, output structure) and the lack of an output schema, the description fully compensates by detailing the return shape and failure modes. An agent has everything needed to decide when to use it and what to expect from the call.

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 aliases for the same 'question' field, which the schema fully documents. The description doesn't need to add parameter semantics, and it doesn't—it focuses on behavior. This meets the baseline for high schema coverage.

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

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

The description explicitly states the tool is a 'hallucination-resistant answer mode for high-stakes reads' and differentiates it from ask_pipeworx by noting the extraction step uses ONLY the tool result. It clearly identifies the primary use case and distinguishes it from siblings.

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

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

Provides explicit guidance: 'Use whenever an answer will be quoted, cited, or acted on' and lists specific high-stakes domains. It also explicitly warns to 'prefer ask_pipeworx for casual lookups' due to the extra LLM call cost, giving clear when-to-use and when-not-to-use conditions.

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

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

The description goes far beyond the annotations (readOnlyHint, etc.) by detailing the resolver contract, market_match_confidence, parent_event extraction, news fallback fields, safety mechanisms (low-confidence short-circuits, closed market handling), wide-spread market warnings, and resolution-rule risk. No contradictions with annotations.

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

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

The description is lengthy but well-structured with clear sections (RESPONSE SHAPES, RESOLVER CONTRACT, etc.). While every sentence provides value, the overall length could be trimmed slightly for brevity. However, the complexity of the tool justifies the detail.

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

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

Given the tool's complexity and lack of output schema, the description comprehensively explains input, process, output fields, edge cases (closed markets, low confidence, wide spreads), and safety measures. It fully equips the agent to use the tool correctly.

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

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

All three parameters are described in the schema (100% coverage), and the description adds significant context: market can be slug, URL, or question text; depth options explained; include_raw summarized. This adds meaningful guidance beyond the schema definitions.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It provides specific use cases ('Use for "should I bet on X"...') and distinguishes itself from sibling tools like ask_pipeworx by focusing on betting research with fan-out to category-specific 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?

It explicitly states when to use the tool ('Use for...') and provides examples of fan-outs for different bet types. Although it doesn't explicitly list when NOT to use, the use cases are well-defined and the description includes guidance on interpreting results (e.g., inspect market_match_confidence before trusting).

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior, so the bar is lower. The description adds valuable context about 5-year survey estimates and the B25003 variable caveat. However, it calls the tool 'keyless' while the schema requires an _apiKey, creating confusion about authentication needs. This is a notable transparency gap.

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

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

The description is lengthy but every sentence contributes value, covering purpose, geography input, variable selection, and temporal semantics. It is front-loaded with the main purpose and remains focused, though a more structured layout could improve scannability.

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

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

The description covers the use case, accepted geographies, variable codes, and the important caveat about 5-year survey period estimates. Since an output schema exists, return values are already documented. It is complete for a general-purpose ACS tool, aside from the minor keyless/API key confusion.

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

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

The description adds substantial meaning beyond the schema: it explains how to format geography naturally (ZIP, city with state, county, state) and that FIPS and raw 'for' syntax also work. It also recommends specific variable codes (B25077_001E, B25064_001E) and warns against B25003, far exceeding the schema's generic parameter descriptions.

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

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

The description clearly states the tool's function: returning median home value and median rent (and any ACS variable) for US geographies. It provides concrete examples like 'what do homes cost in 33158' and distinguishes itself from siblings by specifying sub-metro granularity and the ability to serve any ACS variable code.

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 frames when to use the tool: for answering median home value/rent questions at a sub-metro grain, and it gives thorough guidance on accepted geography formats. It does not explicitly name alternative sibling tools or state when not to use it, but the context is clear enough.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds that it returns dataset names, descriptions, and variable codes, which provides some context but is not highly detailed.

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 purpose and an example. Every sentence earns its place; concise and clear.

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 presence of an output schema (assumed complete) and clear description of what the tool returns, it covers the basics well. Could be slightly improved by mentioning typical use cases or frequency of change, but adequate.

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

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

Schema coverage is 100% with the only parameter _apiKey already described in the schema. The description adds minimal value beyond repeating the schema description.

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

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

The description clearly states the tool discovers datasets and their variables, with an explicit example of variable codes. It distinguishes from other census tools by indicating it returns metadata for 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 implicitly suggests usage as a preparatory step by saying 'for querying with other census tools', but does not explicitly state when to use this vs sibling tools like census_acs. No exclusion criteria or alternatives mentioned.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds that it returns counts and trends, which is minimally extra beyond annotations and the output schema.

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

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

Two sentences, front-loaded with the action, no extraneous content. Every word earns its place.

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

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

The description mentions 'by geography' but the input schema lacks a geography parameter, creating ambiguity. Output schema and annotations cover other aspects, so overall moderately complete.

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

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

Schema description coverage is 100%, so the schema already explains each parameter. The description does not add further parameter meaning, which is acceptable given full schema coverage.

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

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

The description clearly states the tool checks monthly building permits for new residential construction by geography, and returns specific data. It distinguishes itself from sibling census tools like census_housing_starts.

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

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

The description implies usage for building permit data but does not explicitly state when to use this tool versus alternatives like census_housing_starts or census_acs. No when-not guidance 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds value by specifying the return fields (headline, vacancy rates) and the default behavior (latest quarter), which goes beyond annotations.

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

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

The description is two sentences with no waste. It front-loads the core purpose and source, then succinctly covers returns and defaults. Every sentence earns its place.

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

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

Given the tool's simplicity, the presence of an output schema, and comprehensive annotations, the description is mostly complete. It covers the key output fields and default behavior, though it could mention data range or update frequency for extra completeness.

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

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

Schema description coverage is 100%, so the schema already documents both parameters (time format, API key). The description reiterates the default behavior for 'time' but does not add new semantic meaning beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states the tool returns US homeownership rate and housing vacancy rates by quarter, specifying the source (Census HVS) and output fields (headline, rental and homeowner vacancy rates). It distinguishes itself from sibling census tools like census_acs (demographics) and census_housing_starts (new construction).

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

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

The description implies usage for querying homeownership/vacancy data and mentions defaulting to the latest quarter, but it does not provide explicit guidance on when to use this tool versus alternatives (e.g., 'for other census data, use census_acs'). No when-not-to-use or prerequisites are mentioned.

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

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

The description adds behavioral context beyond annotations by specifying the returned data types (new starts, units under construction, completed units) and stating it returns housing supply and activity trends. Annotations already indicate read-only, idempotent, non-destructive 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?

Two sentences efficiently convey the tool's purpose and output. Every word adds value, with no unnecessary details. The information is front-loaded in the first sentence.

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 presence of an output schema (not shown but confirmed) and rich annotations, the description sufficiently explains the tool's function and return types. It could be strengthened by mentioning the default geographic scope or lack thereof.

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 description does not need to add much. It mentions 'by geography' (not in schema) and enumerates data types that map to category_code, but these are already covered by the schema. No significant new parameter semantics added.

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 residential construction pipeline data by geography, including starts, under construction, and completed units. It distinguishes from sibling tools like census_building_permits and census_homeownership by its focus on housing starts and pipeline metrics.

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 use when needing housing construction pipeline data, but it does not explicitly state when to use this tool over alternatives, nor does it provide context for exclusions or prerequisites.

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 safe, idempotent behavior. The description adds rich context: sources (SEC EDGAR/XBRL, FAERS), handling off-calendar fiscal years, sorting by primary metric, and returning citation URIs. No contradiction with annotations.

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

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

The description is slightly lengthy but highly informative. Trigger examples are front-loaded. Every sentence adds value, though minor redundancy exists (e.g., repeating 'parallel call').

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 explains return structure (paired data, citation URIs) and covers both entity types thoroughly. Sorting and data sources are specified, making it complete for an agent to understand and invoke correctly.

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

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

Schema coverage 100% with good parameter descriptions. Description enhances by detailing what each type returns (company: financials; drug: adverse events, trials) and explaining the values array constraints (tickers vs drug names, min/max).

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's purpose: 'side-by-side comparison of 2–5 companies or drugs in one parallel call.' It uses specific verbs and resources, and distinguishes from siblings like sequential lookups.

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

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

Explicitly tells when to use: 'X vs Y', 'which is bigger', 'rank these companies.' States 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' providing clear alternatives.

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

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

Annotations already declare readOnlyHint/openWorldHint/idempotentHint/destructiveHint, so the safety profile is covered. The description adds substantial context beyond that: the gaps[] 'never invented' disclosure, the hop field and resolvable citation_uri semantics, the contradictions[] scan for standard/thorough, semantic excerpting rather than head-truncation, and concrete latency expectations (15-60s, ~90s thorough). This is rich behavioral disclosure that materially changes how an agent uses the tool.

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?

Every sentence earns its place — no filler, no repetition of the schema. It's front-loaded with the critical account gate before the core function. The only deduction is structural: it's a single dense unbroken paragraph. Breaking the account requirement, usage guidance, and behavioral notes into sections would aid skimmability, but given the tool's genuine complexity, the density is justified.

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 there is no output schema, the description carries full burden for return-value explanation — and it delivers: findings packet (evidence + confidence + source + fetched_at + pipeworx:// citation), gaps[], contradictions[], hop field, citation_uri. Combined with the 1477 data sources, multi-hop behavior, tier gates, and sibling differentiation, nothing an agent needs to decide, call, and interpret this tool is missing.

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

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

Schema coverage is 100% (both question and depth documented). The description goes beyond the schema by explaining the behavioral difference between depth levels in operational terms ('standard re-angles unanswered gaps', 'thorough chases the best leads') — the schema only lists facet counts, so the description adds real meaning. Also clarifies that 'Broad/multi-part is fine' for the question param. Baseline 3 elevated to 4 for the added depth semantics.

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

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

States a specific verb+resource: 'Grounded multi-source research across Pipeworx's 1477 STRUCTURED data sources... in ONE call'. Explicitly distinguishes itself from open-web search ('this is NOT open-web search') and from the ask_pipeworx siblings by mechanism (5,635 tools in parallel vs one LLM call). The purpose is unambiguous and the differentiation from siblings is airtight.

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 best usage guidance possible. Names concrete alternates WITH selection conditions: 'If you are not signed in, use ask_pipeworx instead', 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. Also states the positive case ('Best for broad/multi-part questions over structured data') and the tier constraints (paid plan for thorough). Nothing is left to inference.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds: returns top-N tools with full schemas ready to call, no second lookup needed. Provides behavioral detail beyond annotations 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?

Front-loaded with primary verb and domain list, then return format and usage hint. Slightly long due to enumerated domains, but all sentences serve a 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?

No output schema, so description explains what is returned (names, descriptions, schemas). Covers limit parameter. Missing potential edge cases like no matches, but sufficient for typical use.

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

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

Schema covers 100% of parameters. Description adds aliases for query (task, q, description, search) and example queries, adding situational context beyond raw schema definitions.

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

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

The description explicitly states the tool finds tools by describing data or task, lists specific domains (SEC filings, FDA drugs, etc.), and differentiates from siblings by positioning it as a first-step meta-tool for browsing available options.

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?

Clear guidance: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available'—provides strong usage context and when-to-use advice.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true. Description adds value by detailing the fan-out behavior across multiple sources, soft-failure for patents (USPTO sunset), and return structure. 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?

Description is long but efficient—each sentence adds essential information. Examples and return field enumeration are useful. Slightly verbose but well-structured and front-loaded with usage 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?

Despite no output schema, description comprehensively lists return fields (cik, company_name, recent_filings with URIs, fundamentals, patents, news, LEI). Handles edge cases (patent soft-fail). Meets contextual needs for a complex multi-source 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% for both parameters. Description adds practical context: value accepts ticker or zero-padded CIK, names not supported, and type is restricted to 'company' with future plans. This supplements schema well.

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 a full cross-source profile of US public companies. Examples like 'Tell me about X' and list of data sources (SEC, XBRL, USPTO, etc.) make purpose unambiguous. Distinguishes from sibling tool resolve_entity by explicitly noting which input types are supported.

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 SEC/XBRL/news lookups' for holistic views. Notes that names are not supported and instructs to use resolve_entity first. Provides clear when-to-use and when-not-to-use guidance.

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

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

Annotations already indicate destructiveHint=true and idempotentHint=true, so the description's 'delete' aligns but adds little new behavioral context. The mention of clearing sensitive data is useful but not a behavioral trait.

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 the action, and no extraneous wording. Every sentence serves a purpose.

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

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

The description covers when to use but does not explain return values or error conditions (e.g., missing key). Given no output schema, more detail on invocation results would improve completeness.

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

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

Schema description coverage is 100% with clear description of the 'key' parameter. The tool description does not add additional meaning beyond what the schema already provides.

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

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

The description clearly states the verb 'delete' and the resource 'previously stored memory by key'. It also distinguishes from sibling tools 'remember' and 'recall', making the purpose 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 provides clear use cases: 'when context is stale, the task is done, or you want to clear sensitive data'. It mentions pairing with siblings but does not explicitly state when not to use or exclude alternatives.

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

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

Annotations already declare the tool read-only, idempotent, and non-destructive. The description adds behavioral detail: fetches the page, extracts title/description/key links, and emits standard markdown format. 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: purpose, process, use cases. Front-loaded and efficient with 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?

The description adequately covers purpose, behavior, output format, and use cases. Given the tool's simplicity (2 params, no output schema), the description is complete.

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

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

Schema coverage is 100% with both parameters (url, max_links) described. The description adds context about what the tool extracts but does not significantly enhance parameter meaning beyond the schema.

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

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

The description clearly states the tool's purpose: generate a production-ready llms.txt file for any URL. It specifies the output format and lists concrete use cases, distinguishing it from related sibling tools like scan_competitor_ai_presence.

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

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

The description provides clear usage contexts (client indexing, own project drafting, competitor auditing). It does not explicitly state when not to use the tool or mention alternatives, but the provided scenarios are sufficient.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds return field list and default active-only filter, which is useful but not essential 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 that front-load the main action and add value in the second sentence. 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?

For a simple tool with one optional parameter, the description covers purpose, usage, return fields, and parameter context. No output schema needed as fields are described.

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

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

Schema coverage is 100% with description for the sole parameter. Description adds no new information beyond what schema provides, so baseline score 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?

Clearly states 'List the caller's active subscriptions' with a specific verb and resource. Distinguishes from siblings like 'subscribe' and 'unsubscribe' by focusing on enumeration.

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: 'review what you're monitoring before adding more or to find an id to cancel.' Lacks explicit when-not-to-use but context is clear.

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

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

The description discloses valuable behavioral traits: rate-limited to 5 per identifier per day, free and doesn't count against tool-call quota, filing without an account returns a claim_token, and passing that token later allows reading resolution status. This is far beyond the annotations, which only say readOnly=false, and adds practical context.

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

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

The description is longer than typical but each sentence contributes important usage semantics, exclusions, and behavioral details. It is front-loaded with purpose and well structured, though slightly verbose.

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 return behavior (claim_token, status, changes) and operational constraints (rate limit, free, no quota). It is complete for a feedback tool and contains 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%, so baseline is 3. The description adds value by showing an exact call syntax for claim_token (pipeworx_feedback({claim_token:"pwfb_…"}) and explaining the workflow, which slightly exceeds the schema's parameter description.

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

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

The title 'Send Pipeworx Feedback' and opening sentence 'Tell the Pipeworx team something is broken, missing, or needs to exist' use a specific verb and resource. It clearly distinguishes this tool from sibling tools like ask_pipeworx or discover_tools by framing it as a feedback channel.

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

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

The description explicitly states when to use the tool (bug, feature/data_gap, praise) and provides an exclusion: 'if the tool came from a different MCP server... file it with that server instead.' It also clarifies how to identify Pipeworx tools, which is actionable 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, openWorldHint=true, idempotentHint=true. Description adds valuable context: no PII, sourced from CF analytics-engine, cached 5min-1h. No contradictions.

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

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

Two concise sentences followed by a bullet list of use cases and two more sentences about data source and caching. Front-loaded with purpose, 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?

Explains what is returned (top tools, packs, call volume) and caching behavior. For a simple read-only tool with one optional parameter, this is sufficient. Could specify return format but not essential.

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?

Parameter 'window' is fully described in schema (enum with descriptions). Description adds contextual meaning about what each window reveals (hot vs steady-state). Adds value beyond schema.

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

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

Description clearly states the verb 'Returns' and the resource: top tools, packs, and call volume over a recent window. Distinguishes from siblings like ask_pipeworx or discover_tools by focusing on trending 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?

Explicitly lists three practical use cases (discovering hot data sources, confirming canonical tools, aligning usage). Does not explicitly mention when not to use or name sibling alternatives, but the guidance is clear and actionable.

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

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

Description adds extensive behavioral context beyond annotations: explains semantic anchor (Jaccard similarity ≥0.30), partition filter (placeholder >20% returns null), fill check with book depth thresholds (realizable_edge ≤ 0 means do not trade), and specific thresholds like deviations >3pp. 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?

Description is long but well-organized: starts with purpose, then explains each mode, then details about filters, response, and fill check. Every sentence adds value, though somewhat dense. Could be slightly more concise but still well-structured.

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

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

Given the complexity (multiple modes, fill check, partition check), the description is very complete. Output schema not provided but description mentions response structure (opportunities array, partition_check fields). References sibling tool polymarket_fill_risk for custom sizing.

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 descriptions (100% coverage). Description adds additional context: event slug examples, topic seed question examples, and explains what each mode does. Goes beyond schema by explaining underlying logic.

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 finds arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes between two modes (event and topic) and mentions trending_scan when no args. It also differentiates from sibling tools like polymarket_edges, polymarket_edge_tracker, and polymarket_fill_risk.

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

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

Explicitly says when to use each argument: event recommended for specific market, topic for cross-event scanning. Also notes cross-event mode catches patterns single-event misses. Does not explicitly state when not to use, but provides clear context.

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

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

Annotations declare readOnlyHint true, openWorldHint true, idempotentHint true, and destructiveHint false. The description adds significant behavioral details beyond these: caching at KV level for 1 hour, detailed model families with formulas, tradeable-edge knobs and their effects, exclusion of Fed bets from ranking, and diagnostic information. 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 quite long and dense, but it is structured with sections for model families, tradeable-edge knobs, and response top-level. While every sentence provides useful information, it could be more concise without losing meaning.

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 (9 parameters, no output schema), the description thoroughly explains the response structure, internal models, exclusion logic for Fed bets, caching behavior, and diagnostic information. It provides nearly all necessary context for an agent to invoke the tool correctly.

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

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

Schema description coverage is 100% with each parameter having a clear description. The overall description adds context by grouping parameters as 'tradeable-edge knobs' and explaining their role in filtering opportunities (e.g., min_liquidity drops thin-book opportunities). This adds value beyond the individual schema descriptions.

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

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

The description clearly states the tool scans top Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. It uses a specific verb ('scan') and resource ('Polymarket markets'), and distinguishes its purpose from siblings by focusing on arbitrage opportunities based on model disagreement, not just general market 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 is built for 'what should I bet on today' which implies usage context, but it does not explicitly state when not to use this tool or compare it to sibling tools like polymarket_arbitrage or polymarket_edge_tracker. Usage is implied but not clearly differentiated.

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 important behavioral traits beyond annotations: history bounded by 60-day TTL, snapshot gaps, decay computed from daily closes (not intraday), and that decay numbers are based on edge_pp_net net of default slippage. No contradictions with annotations.

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

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

The description is long but well-structured, front-loading the purpose and then systematically listing args, response fields, and limits. Every sentence adds value, though a minor trim could improve 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 tool's complexity and lack of output schema, the description thoroughly explains the response structure (tracked[], expired[], snapshot_dates[]) with key fields and caveats. It covers limits and edge cases, making it complete for an AI agent.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by specifying default values (days=14, window='1wk'), clamping (days 2-30), and clarifying the meaning of 'window' (snapshot family). This enriches 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 identifies the tool's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It answers a specific question and distinguishes itself from sibling tools like polymarket_edges by focusing on historical persistence and trend 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?

The description implies when to use this tool (e.g., for understanding edge persistence vs. a single snapshot) and provides a concrete example contrasting fresh vs. old edges. However, it does not explicitly state when not to use it or compare to alternatives like polymarket_edges or 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 indicate idempotent, read-only, non-destructive. The description adds detailed behavioral traits: walking the order ladder, returning verdicts (clean/degraded/cannot_fill), and warning about forced directional risk from partial fills – all valuable beyond annotations.

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

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

Description is moderately long but well-structured with clear mode sections, bullet-like lists, and front-loaded purpose. Every sentence contributes significant information; minimal 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?

No output schema, but the description enumerates return fields for both modes (e.g., top_of_book, vwap_fill_price, slippage_pp, verdict for single; theoretical_sum, capture_ratio, thin_legs for basket). Also covers required parameter constraints. 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?

Schema coverage is 100% with descriptions, but the tool description expands each parameter's meaning: explains mode dependence for `market` vs `event`, side defaults and interpretation, and size semantics (spend vs target proceeds vs settlement notional). Exceptional value-add.

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 checks 'realizable-vs-theoretical edge against live CLOB order-book depth' with two distinct modes (single-market and basket). It explicitly relates to sibling tools like polymarket_arbitrage and polymarket_edges, differentiating its role as a pre-execution risk check.

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

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

Provides explicit guidance: use before acting on arb signals or trades >$500. Explains risks of thin books and partial basket fills. Does not explicitly list when not to use, but the context is strong and actionable.

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

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

Annotations already indicate readOnly and idempotent. The description adds extensive behavioral detail: compatibility warnings, temporal alignment checks, skipped cross-type/subtype counters, and realistic caveats about pre-mapped topics returning warnings. 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?

Well-structured with clear sections: purpose, modes, response, safety fields. Each sentence earns its place, though slightly verbose. Could be tightened without loss of content.

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

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

No output schema, but description fully explains response structure including leg prices, matched spreads, compatibility_warning, temporal_alignment, and skipped counters. Covers edge cases like non-equivalent bet shapes and temporal misalignment. 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 covers 100% of parameters with descriptions. The description adds value by explaining mode override relationships and providing examples for each parameter. Slightly above baseline due to additional context beyond schema.

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

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

The description clearly defines the tool as a cross-venue spread calculator between Kalshi and Polymarket for the same resolving question, distinguishing it from siblings like polymarket_arbitrage. The verb 'cross-venue spread' plus resource specification is precise.

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

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

Provides explicit usage modes (topic vs explicit tickers) and explains when compatibility warnings appear. Lacks a direct 'when not to use' statement but the safety fields effectively guide proper 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 read-only, idempotent, non-destructive. Description adds scoping (anonymous IP, BYO key hash, account ID) and behavior of omitting key. No contradictions.

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

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

Two concise sentences plus a contextual note. No filler; every sentence adds value. Front-loaded with core action and examples.

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 return behavior (value or list). Includes scoping and pairing with remember/forget. Fully covers the simple retrieval use case.

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

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

Schema coverage is 100% (one optional key parameter). Description reinforces schema and adds examples of key content (ticker, address, research notes), adding meaningful context beyond parameter description.

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

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

The description clearly states the tool retrieves a saved value or lists keys, with concrete examples (ticker, address, research notes). It distinguishes from siblings remember and forget by naming them explicitly.

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

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

Provides clear when-to-use context: 'look up context the agent stored earlier without re-deriving it.' Mentions omitting key to list all keys and pairing with remember/forget. Lacks explicit when-not-to-use but implied by sibling differentiation.

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

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

Adds value beyond annotations by specifying return fields, mark_read behavior, and polling suitability. No contradictions.

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

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

Three concise sentences with no wasted words; front-loaded with 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?

Covers usage, filtering, behavior, and alternative access. Since no output schema, description compensates with return field details.

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?

Adds example for type and explains mark_read effect beyond schema descriptions. All parameters have schema descriptions (100% 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 'Pull fired events from your subscription feed' with specific verb and resource. Distinguishes from siblings like list_subscriptions.

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

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

Provides filtering guidance and mentions alternative GET endpoint for scripts/dashboards, but lacks explicit 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 operations. Description adds significant behavioral context: fan-out to multiple APIs, fallback from GDELT to GNews, PatentsView sunset soft-fail, and return structure. Goes well beyond annotation defaults.

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

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

The description is lengthy but every sentence serves a purpose. It is front-loaded with usage examples. Could be slightly tighter, but remains efficient given the 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?

Given the tool's complexity (multiple data sources, fallback logic, parameter variations, no output schema), the description covers all necessary context: sources, fallback, parameter formats, return structure, and limitations like PatentsView sunset.

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 has 100% coverage with descriptions. Description enriches parameters: explains type enum limitation, provides multiple valid since examples with both absolute and relative formats, and clarifies value as ticker or zero-padded CIK.

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

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

The description clearly states it is a change feed for a company, listing sources like SEC EDGAR, GDELT/GNews, and USPTO. It distinguishes from sibling tool entity_profile by contrasting dynamic changes versus static profile.

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

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

Explicitly provides query examples ("What's new with X", "latest on Y") and states when to use entity_profile instead for static information. Gives clear context for appropriate invocation.

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?

Explains that data is key-value, scoped by identifier, and that memory is persistent for authenticated users but only 24 hours for anonymous sessions. This adds value beyond annotations (idempotentHint, destructiveHint).

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, well-structured paragraph that front-loads the core purpose and then adds important nuances. Every sentence contributes meaning 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?

Covers purpose, usage triggers, data format, scoping, persistence rules, and companion tools. No gaps given no 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% with descriptions, but the description adds examples of key patterns (e.g., 'subject_property', 'target_ticker') and value content (findings, addresses, preferences).

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: 'Save data the agent will need to reuse later' with concrete examples (ticker, address, preference). It distinguishes from sibling tools like recall and forget.

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

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

Explicitly says when to use: 'when you discover something worth carrying forward' and pairs with recall/forget. Also provides context on authentication and persistence.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, openWorldHint), the description adds critical behavioral details: cascading internal lookups, graceful degradation when GLEIF/OpenFIGI are unavailable, and explicit handling of unresolved identifiers under an 'unresolved' field. This provides the agent with a clear mental model of the tool's execution and failure modes.

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

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

The description is front-loaded with example queries and a clear mission statement, and every sentence adds value. However, it is somewhat lengthy (a dense paragraph) and could be tightened slightly without losing the rich detail. The structure is logical but not broken into sections.

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 entity types, multiple data sources) and the absence of an output schema, the description covers most essentials: supported inputs, internal cascades, error handling, and unresolved identifiers. It stops short of explicitly describing the output structure (e.g., a JSON object with identifiers and unresolved list), which would improve completeness.

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

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

Although the schema already covers both parameters with 100% description coverage, the description vastly extends that meaning. For 'type', it explains the full cross-source identity spine for 'company' and the RxNorm pipeline for 'drug'. For 'value', it lists accepted input formats (ticker, CIK, ISIN, name) and provides examples like 'CH0038863350' for ISIN-to-LEI resolution.

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

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

The description opens with concrete example queries and states the core purpose: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It details two supported types (company and drug) with distinct data sources, clearly distinguishing the tool from sibling tools like entity_profile and compare_entities, which serve different purposes.

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

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

The description explicitly advises 'Use FIRST whenever you have a name but need an ID,' establishing a clear when-to-use context. However, it does not explicitly mention when not to use it (e.g., if an ID is already known) or directly compare to alternative tools, leaving some inference to the 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?

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. The description adds that it probes with ai_visibility_check, ranks results, and returns a ranked list with 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?

The description is three sentences with no wasted words. Purpose is stated first, then behavior, then use case example. Every sentence earns its place.

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

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

For a tool with 4 parameters, 100% schema coverage, no output schema, and moderate complexity, the description fully explains what the tool does, how it works, what it returns, and when to use it. 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?

Schema description coverage is 100%, so baseline is 3. The description adds value by explaining 'entities' ordering (first is subject), suggesting default for 'models' ('omit for just workers-ai'), and explaining '_apiKey' and 'context' usage. This extra context raises the 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 uses specific verbs ('Compare', 'Probes', 'ranks', 'surfaces') and specifies the resource ('AI visibility across multiple entities'). It clearly distinguishes from sibling tools like ai_visibility_check (single entity) and compare_entities (generic) by focusing on multi-entity competitive AI 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?

The description gives a concrete use case ('competitive AI-marketing audits') and an example question, but does not explicitly state when NOT to use it or mention alternatives. However, the context signals show it is one of many tools, and the differentiation 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?

Beyond non-destructive annotations, the description discloses partial failure handling, bundlephobia's slow first measurement (5-30s), and that sources_failed lists timeouts. It also describes the return structure in detail.

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

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

A single dense paragraph that front-loads the purpose. While informative, it could be more structured (e.g., bullet points) but 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?

No output schema exists, but the description fully details the return fields and handles edge cases (partial failures, timeouts, NPM-only scope). Covers all necessary context 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?

Schema coverage is 100%. The description adds context: defaults to latest version if omitted, accepts scoped packages, and explains the external sources consulted and return structure.

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 a composite check for adding npm packages, covering license, advisories, size, and tree-shake support. It distinguishes itself from sibling tools which are unrelated to dependency scanning.

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 tells when to use: when an agent asks about safety, popularity, or cost of adding an npm package. Also notes NPM-only in v1 and directs users to deps.dev for other ecosystems.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. Description adds specific technical details: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, and 200K char cap with truncation flag. No contradiction.

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

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

Three well-structured sentences. First sentence states purpose, second explains usage and output benefits, third adds technical constraints. No redundant information; every sentence earns its place.

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

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

Despite no output schema, description hints at return structure (passages with offsets and similarity scores) and covers constraints (char limit, truncation). A clear output schema would make it 5, but the description is largely sufficient for agent understanding.

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 context by explaining how parameters are used (e.g., 'pass the text you already pulled', 'natural-language query') and provides examples for query. Adds value beyond schema.

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

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

Description clearly states the tool does semantic search inside a fetched record, with specific examples like SEC 10-K and articles. It distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded and implying it's for when records are too large for the prompt.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and explains that it saves context and returns only relevant passages with offsets. Mentions pairing with ask_pipeworx_grounded, but does not explicitly list when not to use it or contrast with all siblings.

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

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

Annotations already indicate readOnlyHint=false (write operation) and destructiveHint=false. Description adds concrete constraints: account type requirement, type-specific params, delivery channel limitations (SMS 10/day cap, webhook auto-disable after 10 failures), and that webhook signing secret is returned once. However, it does not clarify idempotentHint=true behavior (whether duplicate calls create multiple subscriptions). 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?

Description is front-loaded with core action and return value. It is relatively long but every sentence adds value (prerequisites, types, delivery details). A minor reduction could be made for brevity, but no fluff present.

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 3 parameters, 100% schema coverage, and no output schema, description covers prerequisites, types, delivery channels, and limitations. It lacks details on error conditions or idempotency behavior, but overall is sufficient for an agent to successfully invoke 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?

Schema coverage is 100%, so baseline is 3. Description adds significant value beyond schema by providing concrete examples for each type's params, delivery channel requirements (phone verification, email validation, webhook restrictions), and caps (SMS limit). This helps the agent understand parameter usage and 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 creates a subscription to a live-data event stream and returns the subscription id. It includes specific verb (Create), resource (subscription), and distinguishes from siblings like list_subscriptions and unsubscribe.

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

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

Description provides when to use (proactive monitoring), prerequisites (Pipeworx OAuth account), supported types with examples, and delivery channels. It implicitly mentions alternatives like recent_alerts for feed pull, but does not explicitly state when not to use or compare to siblings directly.

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 significant context beyond annotations: describes output format (category-bucketed examples with tool shapes) and role as onboarding entry point. 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?

Well-structured with front-loaded purpose, example utterances, and detailed explanation. Slightly long but 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?

Fully describes purpose, usage, and output for a simple discovery tool with no output schema. Handles all context signals appropriately.

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 1 parameter; description enhances by listing valid topic values and explaining behavior when omitted. Provides practical 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?

Description clearly states the tool returns example questions with tool+argument shapes, categorized by domain. Distinguished from siblings like ask_pipeworx and discover_tools.

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

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

Explicitly says to use first when unsure about Pipeworx capabilities and to learn meta-tools. Does not mention when to avoid use but context is clear.

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

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

The description adds value beyond annotations by explaining that the row is deactivated (not deleted) and historical events remain available via 'recent_alerts'. This aligns with 'destructiveHint: false' and provides useful behavioral context.

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

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

Three sentences, each purposeful. The action is front-loaded, and there is no redundancy or unnecessary 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?

The tool is simple with one parameter and no output schema. The description covers purpose, ownership, and side effects completely, making it adequate for an agent to use correctly.

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

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

The input schema has 100% coverage for the single parameter 'id' with a clear description. The tool description adds minimal extra meaning beyond restating that the id is used, so a baseline score of 3 is appropriate.

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

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

The description clearly states 'Cancel a subscription by id,' which is a specific verb and resource. It distinguishes itself from sibling tools like 'subscribe' and 'list_subscriptions' by focusing on cancellation.

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

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

The description explicitly notes ownership enforcement ('you can only cancel your own subscriptions'), guiding the agent on prerequisites. However, it does not mention when not to use this tool or suggest 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?

Beyond the annotations, the description discloses critical behavioral nuances: could_not_verify means the check did not happen and is not evidence, while unsupported means no source covers it. It also details the returned verdict, actual value with citation, and reasoning, which are not obvious from the schema or annotations.

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

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

The description is well-structured and front-loaded with the purpose and usage, then covers routing, return values, and error semantics. It is somewhat long due to the list of invocation phrases and the 'Replaces 4–6 sequential calls' note, but each section provides meaningful context.

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 2-param tool with no output schema, the description fully covers input, routing logic, return value structure (verdict, actual value, citation, reasoning), and edge cases (could_not_verify vs unsupported). This is sufficient for an agent to invoke it correctly and interpret results.

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

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

Both parameters are fully described in the schema (100% coverage), so the baseline is 3. The description adds value by explaining tolerance_pct's override behavior, default (implied by wording, capped at 5), and specific use for hallucination detection, which goes beyond the schema's basic definition.

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 natural-language claim verification against authoritative sources, using a specific verb and resource. It clearly differentiates between the SEC EDGAR/XBRL fast path for company-financial claims and the grounded pipeline for other claims, distinguishing 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 explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and explains the routing between financial and non-financial claims. However, it does not name alternative tools or state when not to use it, so it lacks full when-not/alternatives guidance.

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