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 already communicate read-only, open-world, idempotent, and non-destructive behavior. The description adds meaningful operational context: the tool auto-selects among 5,798 tools, fills in arguments on the user's behalf, and returns structured answers with stable pipeworx:// citation URIs. There is no contradiction with the annotations.

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

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

The opening is strong and front-loaded, but the description becomes heavily redundant: the block 'START HERE for most questions — even if web search could also answer it. Examples: ...' is repeated many times. The trailing note about news feeds also feels truncated and out of place, so overall the description does not earn its length.

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

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

For a tool with one required parameter and no output schema, the description covers almost everything needed: when to use it, what data domains it covers, how the answer is returned, and that citations are included. It could be slightly more explicit about edge cases like ambiguous questions or missing sources, but nothing critical 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?

The schema already describes all six parameters as aliases for a natural-language question with 100% coverage, so the baseline is high. The description adds value by giving concrete example queries and trigger phrases that help the agent know what kind of natural-language input to pass as the question parameter.

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

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

The description clearly states what the tool does: it routes a factual question to the right tool among thousands, fills arguments, and returns a structured answer with stable pipeworx:// citation URIs. It also names concrete domains and example queries, making its scope unmistakable and distinguishing it from plain web search.

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

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

The description gives explicit triggers: prefer over web search for listed data categories, use for 'what is', 'look up', 'find', 'get the latest', 'how much', and 'current' questions, and 'START HERE for most questions'. It names web search as the alternative and covers breaking-news routing, but it does not explicitly differentiate from sibling variants like ask_pipeworx_grounded or deep_research.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior, so the description's added value is the live state disclosure: no candidate is active, it currently matches ask_pipeworx exactly, and routing can change whenever a candidate is under test. It also clarifies that this is a fully working router rather than a fallback stub. It could be more explicit about failure modes or volatility risk, but 'experimental edge' conveys the relevant caution.

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

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

The description is dense and front-loaded, with each sentence covering a distinct point: identity, current state, usage, and full-routing nature. The exact tool count and the 2026-07-26 date are precise but risk becoming stale, which keeps it just below a perfect conciseness score.

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

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

For a beta universal router with no output schema, the description conveys identity, current equivalence to ask_pipeworx, and the experimental comparison purpose. It points to ask_pipeworx for response shape rather than describing it directly, but since this is labeled as a variant of that existing tool, that is sufficient for selection and invocation.

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

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

Schema coverage is 100%, with all six parameters documented as aliases for the natural-language question, so the description need not repeat parameter meaning. The only additional hint, that arguments match ask_pipeworx, is useful but does not materially expand the schema semantics, so the baseline of 3 applies.

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

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

The description immediately identifies the tool as the beta version of ask_pipeworx, a universal router sharing the same tools, arguments, and response shape, with candidate routing improvements as the differentiator. This clearly separates it from the stable ask_pipeworx sibling and makes the resource and action 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?

It explicitly states when to use the tool: use it exactly like ask_pipeworx when the newest routing is wanted, and frames it as the experimental edge compared against the stable router. This gives a clear selection condition and names the main alternative, so an agent knows how to choose between them.

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

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

The description goes well beyond the readOnly/idempotent annotations by disclosing the full response contract: success shape with answer, evidence, confidence, source, fetched_at, and refusal shape with specific refusal_reason enumerations. It also reveals the extra-LLM-call cost and the internal routing/data-fetching process.

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 dense and well-structured: purpose first, then mechanics, then response contract, then usage guidance and cost tradeoff. A few repetitions (refusal and hallucination-resistance) could be trimmed, but every major clause carries useful information.

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

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

With no output schema, the description compensates by fully specifying the success and refusal return shapes. It also includes the routing rationale, cost consideration, and explicit usage boundaries, making it a complete selection and invocation guide.

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

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

Schema coverage is 100%, so the schema already documents the question parameter and its aliases. The description adds routing and grounding context but no additional parameter-level semantics.

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

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

The description clearly states this is a hallucination-resistant answer mode that extracts answers using only tool results, and explicitly frames it as grounded vs. the sibling ask_pipeworx. The verb, resource, and behavioral differentiator are all specific.

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

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

It gives explicit when-to-use guidance (answers that will be quoted, cited, or acted on) and when-not-to-use guidance (casual lookups, prefer ask_pipeworx). It also names the cost tradeoff: one extra LLM call.

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

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

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?

The description goes well beyond annotations, disclosing account/paid-tier requirements, parallel decomposition, the findings packet shape (evidence, confidence, source, fetched_at, citation_uri, gaps[]), contradictions[] for standard/thorough, semantic excerpting, and latency expectations. It also states that findings are 'never invented' and that citations are always fetchable. This aligns with readOnly/openWorld/idempotent annotations without contradicting them.

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

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

The description is long but each segment carries operational value: prerequisites, capability, usage guidance, depth semantics, return contract, and performance. It is front-loaded with the account requirement and structured with clear separators. Some redundancy exists, but the complexity justifies the length.

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

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

With no output schema, the description fully describes return values: findings packet with verbatim evidence, confidence, source, fetched_at, stable pipeworx:// citation, gaps[] for unanswered facets, and contradictions[] when applicable. It covers latency, auth prerequisites, and depth differences, so an agent has enough to decide 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?

Input schema covers 100% of parameters, and the description adds meaningful nuance: depth's enum behaviors (quick=3 single hop, standard=3 default with gap-recovery hop + contradictions[], thorough=6 paid iterative hop) and question as decomposable natural language. This exceeds the schema's own descriptions, though the schema already covered the basics.

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

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

The description states a specific operation: 'Grounded multi-source research across Pipeworx's 1517 STRUCTURED data sources ... in ONE call'. It distinguishes this from open-web search and contrasts it with ask_pipeworx for single lookups, making the tool's role unmistakable among siblings.

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

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

The description gives explicit routing rules: 'If you are not signed in, use ask_pipeworx instead' and 'For a single lookup use ask_pipeworx instead.' It also scopes applicability to 'broad/multi-part questions over structured data' with concrete examples, clearly defining when to use this tool versus alternatives.

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

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

Annotations already 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 provide readOnly, idempotent, and non-destructive hints, and the description substantially adds context: the fan-out across SEC, XBRL, USPTO, USAspending, and more; the `sources_used`/`sources_failed` semantics; the "empty section is a real no-data, not a bug" caveat; the USPTO API sunset soft-fail; and the private-company return shape. This goes well beyond what the annotations express.

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

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

The description is long, but it is densely informative and front-loaded with example queries and the primary directive. Each source and caveat earns its place, though some redundancy in the input-form explanation could be trimmed. It is appropriately sized for a complex tool with many return 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?

There is no output schema, so the description carries the burden of explaining return value structure. It enumerates every expected field, describes failure semantics for each source, clarifies empty results, and explains resolution behavior. Nothing essential is missing for an agent to call this tool correctly and interpret its response.

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

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

The schema already covers both parameters at 100%, so the baseline is 3. The description adds meaningful nuance by stating that `type` accepts "company" or "ticker" interchangeably and that `value` may be a ticker, zero-padded CIK, or company name with name resolution. It reinforces and clarifies the schema rather than merely repeating it, earning a 4.

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

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

The description names a specific verb+resource: it builds a "full cross-source profile of a US public company in ONE parallel call." It lists concrete example queries and enumerates the exact data sources, making the tool's purpose unmistakable and distinct from sibling tools like resolve_entity or deep_research.

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 directs agents to "ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view," which is clear selection guidance. It also explains acceptable input forms and what to expect for private companies versus public ones, so agents know when the tool applies and what fallback behavior occurs.

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?

Even though readOnly/idempotent/openWorld annotations already cover the safety profile, the description adds substantial behavioral details: unrecognized legs are never paired, compatibility flags and warnings can be non-empty even when pairs are returned, temporal_alignment null means unknown rather than aligned, and spreads are gross of Kalshi fees. There is no contradiction with annotations.

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

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

The description is long, but it is front-loaded with the core purpose and organized with labeled sections (RESPONSE, SAFETY FIELDS, Codes). It carries enough essential caveats to justify its length, though a few points are repeated (e.g., that both modes use the same matcher, and alignment semantics are restated), preventing a 5.

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

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

With no output schema, the description carries the full interpretive burden and succeeds: it explains response components, compatibility codes, per-entry flags, unclassified-leg handling, fee disclosure, and skip counters. An agent has what it needs to call the tool and interpret the result safely in either mode.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds cross-parameter semantics by explaining that topic auto-fetches both venues while kalshi_event_ticker and polymarket_event_slug override the mapped sides, and that both modes use the same matcher. This goes beyond the schema definitions, though the schema already describes the enumerations and overrides.

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

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

The first sentence states a specific action and resource: computing the cross-venue spread between Kalshi and Polymarket for the same resolving question. It also names two modes and the exact outputs, so it cannot be confused with intra-Polymarket tools like polymarket_edges or polymarket_arbitrage.

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

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

The description clearly explains when the tool is appropriate (cross-venue spreads), how to choose between the topic shortcuts and explicit ticker/slug pairings, and warns that most pre-mapped topics currently return compatibility warnings. It does not explicitly name alternative sibling tools or state when not to use this tool, so it falls short of a perfect 5.

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

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

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

The description discloses rich behavioral details beyond the annotations: internal multi-endpoint cascade, graceful degradation when LEI/FIGI sources are unavailable, explicit listing of unresolved identifiers, and ambiguity handling via figi_candidates. This is far more than the readOnly/idempotent hints convey.

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

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

The description is quite long, but it is well-organized with example queries, explicit supported types, and behavioral notes. It is front-loaded with usage cues, and while some examples (e.g., the ISIN number) could be trimmed, the overall length is justified by the tool's complexity.

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

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

The description covers input scenarios, edge cases (ambiguous bond names), degradation behavior, and result semantics like figi_candidates and unresolved fields. Given there is no output schema, this level of detail is sufficient for an agent to know what to expect when invoking the tool.

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

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

Even though schema coverage is 100%, the description adds substantial meaning: for 'value' it explains exact formatting rules (e.g., pass the issuer name exactly as printed, never the full noun phrase), and for 'type' it details source mappings and ISIN-to-LEI behavior. This goes well beyond the schema's brief 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 explicitly states the tool's function: resolving user-spoken names to canonical/official identifiers needed by other tools. It provides concrete example queries and clearly positions the tool as the first step in identifier lookup, distinguishing it from siblings like entity_profile or compare_entities that 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?

It gives explicit guidance: 'Use FIRST whenever you have a name but need an ID,' and it elaborates on supported entity types and input formats. However, it doesn't explicitly mention when not to use the tool or name alternative tools for overlapping tasks, so it lacks full exclusion 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 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.