Hud

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

Discloses return structure (per-model score, signals, raw_response + combined view), cost implications for Anthropic (BYO key, direct payment), and free default model. Annotations already cover safety (readOnly, idempotent), and description adds non-redundant 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?

Front-loaded with primary action and output. Single paragraph, no wasted sentences. Clearly organized: main verb, scoring range, default model, optional key, return format, use cases.

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 all aspects: input (entity, models, apiKey, context), behavior (probing models, scoring), output structure, and use cases. No output schema needed as description sufficiently explains return values. Complete for a probing tool.

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

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

Schema coverage is 100% with descriptions, but description adds critical context: default model identity, free tier, API key purpose, and disambiguation hint for context parameter. This goes beyond schema to guide agent usage.

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

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

Description uses specific verb 'probe' and defines resource as 'LLMs for visibility scoring'. It clearly differentiates from sibling tools like ask_pipeworx and deep_research by focusing on AI brand visibility measurement.

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?

States explicit use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring'. Mentions default model and optional API key, guiding usage. Lacks explicit when-not-to-use or alternatives, but context signals (siblings) provide 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?

Annotations already indicate readOnly, idempotent, openWorld, non-destructive. The description adds significant context: routing behavior, argument-filling, structured output format, citation URIs, tier coverage, and speed ('one fast call'). 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 deliberately structured: immediate priority instruction, capability overview, signal phrases, examples, escalation guidance, and coverage note. Every sentence contributes, though it could be tightened; still well-organized and front-loaded.

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

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

The description fully covers what an agent needs to decide when to invoke and what to expect: scope, sources, output format, alternatives, and examples. No output schema exists, but the description compensates by explaining the structured answer and citation URIs.

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 aliases fully documented. The description only provides examples and general phrasing, but does not add operational parameter semantics beyond schema. Baseline 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 explicitly states the tool routes questions to 5,529 tools across 1,455 sources and returns structured answers with citation URIs. It clearly distinguishes itself from siblings like ask_pipeworx_grounded and deep_research, and provides concrete examples of use.

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

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

The description gives explicit 'when to use' guidance: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and explains when to step up to ask_pipeworx_grounded or deep_research. It even clarifies breaking-news handling, making alternatives and exclusions unambiguous.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description meaningfully adds live candidate routing, the current inactive state with a date, identical tool/args/response, results compared against the stable router, and no fallback—it's a fully working router. 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?

Five sentences, front-loaded with the beta relationship and same-tool claim. Each sentence adds context—current state, usage, safety, comparison process—so it is information-dense rather than padded.

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

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

For a complex universal router, the description provides essential context: purpose, relationship to stable tool, current parity state, and comparison workflow. No output schema exists, but 'same response shape' references a known sibling; could be slightly more self-contained if the response format were spelled out, but overall sufficient.

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, enumerating five aliases for the single required question field. The description references 'same arguments' but doesn't need to repeat schema details; it adds the natural-language router context but provides no additional parameter-level guidance 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 identifies this as a beta version of ask_pipeworx—a universal router with the same 5,529 tools, arguments, and response shape—and distinguishes it from the stable sibling via experimental routing improvements. The verb 'ask' plus router scope is explicit.

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

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

States a clear use case: 'Use it exactly like ask_pipeworx when you want the newest routing.' Names the stable sibling as the reference and clarifies that no candidate is active, so it currently matches ask_pipeworx. It doesn't give an explicit when-not, but the beta/experimental framing implies preference for stable contexts.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint), the description discloses refusal modes, the guarantee of using only tool result content, and the extra LLM call cost. It also specifies the return contract including refusal_reason values. 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?

Front-loaded with the key differentiator ('Hallucination-resistant answer mode...'), then efficiently covers mechanism, use cases, and cost trade-off. Every sentence contributes value, with no filler or repetition.

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

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

The description covers routing behavior, extraction constraints, exact return shape (including refusal reasons), use cases, and the cost/alternative trade-off. Even without an output schema, an agent is fully equipped to select and invoke this 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 aliases fully described, so the description adds no new per-parameter details. The phrase 'fills arguments' gives contextual context but not parameter-level semantics. Baseline 3 applies as schema does the heavy lifting.

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

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

The description clearly states the tool's function: 'Hallucination-resistant answer mode for high-stakes reads' that 'EXTRACTS the answer using ONLY what the tool result contains.' It explicitly distinguishes itself from sibling ask_pipeworx by highlighting the grounded extraction and refusal behavior.

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

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

Provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts,' with concrete examples. It also names the alternative (ask_pipeworx) and states a clear preference for casual lookups, including the cost trade-off.

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

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

The description goes far beyond annotations (readOnlyHint, idempotentHint, etc.) by detailing safety behaviors: low-confidence resolutions short-circuit, closed/dead markets return status: 'market_closed_or_inactive', wide-spread markets carry tradeability note, resolution-rule risk parsing. 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 very dense with information. It could be more structured (e.g., use of bullet points or sections), but every sentence adds value. Not too concise, but the detail is necessary given 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?

Given the complexity of the tool (multiple outcomes, classifiers, fan-outs, response shapes, resolver contract, safety mechanisms), the description is highly complete. It covers all aspects: market matching, analysis, evidence, parent events, news fields, resolution-rule risk, and blocking conditions. No output schema exists, but the description adequately explains return values.

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

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

Schema coverage is 100%, and the description adds meaning: the market parameter accepts slug, URL, or question text; depth parameter describes quick vs thorough; include_raw explains use cases. The description also includes examples in the schema's examples field, aiding understanding.

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

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

The description clearly states the tool researches a Polymarket bet by pulling Pipeworx data, resolving the market, classifying the bet, and returning an evidence packet with comparison. It includes verbs like 'pull', 'resolve', 'classify', 'fans out', and 'returns'. It distinguishes from siblings like polymarket_arbitrage, polymarket_edges by focusing on research rather than arbitrage or edge tracking.

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

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

The description explicitly lists use cases: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. It provides example classifiers and fan-out scenarios. However, it does not explicitly state when not to use or mention alternatives, though the context makes it clear.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral details like handling of off-calendar fiscal years, sorting by primary metric, and specific data sources (SEC EDGAR, FAERS), all consistent 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?

A single dense paragraph that efficiently front-loads common queries and key rules. It could be slightly better structured, but every sentence adds value with minimal waste.

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

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

Despite no output schema, the description adequately explains returns (paired data + citation URIs) and sorting. It covers input constraints, data sources, and replaces many alternative tools, making it fully informative.

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 parameter docs. The description adds value by explaining how type and values affect behavior (e.g., company pulls financials, drug pulls adverse events) and specifying value formats, raising it above the baseline 3.

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

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

The description clearly states it performs side-by-side comparisons of 2-5 companies or drugs, listing specific query patterns like 'X vs Y' and 'rank these companies'. It distinguishes from siblings like entity_profile by emphasizing batch comparison over sequential single 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?

The description explicitly advises 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and notes it replaces 8-15 sequential lookups, giving clear guidance on when and when not to use it.

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

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

Beyond annotations, the description discloses auth requirements, latency (15-60s up to ~90s), guarantees against invented findings (gaps[]), conditional citation_uri fetchability, semantic excerpting, and contradictions[] behavior. No contradiction with annotations; these details add substantial value.

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

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

The description is long but every sentence earns its place (auth warning, source scope, alternative tools, output structure, latency). It is front-loaded with the most critical information and remains well-organized despite its length.

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

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

With no output schema, the description fully compensates by detailing the findings packet, gaps[], contradictions[], hop field, and citation_uri semantics. It covers edge cases and is exceptionally complete for a tool with only 2 parameters.

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

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

Schema descriptions cover 100% of parameters, so baseline is 3. The description adds meaningful parameter-level guidance: clarifying that 'question' should be broad/multi-part and explaining how 'depth' affects facet count, gap recovery, and paid tier. This exceeds schema basics.

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

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

The description clearly states a specific verb ('research') and resource ('Pipeworx's 1455 STRUCTURED data sources'), and explicitly distinguishes itself from siblings by noting it is NOT open-web search and contrasting with ask_pipeworx for single 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?

It provides explicit when-to-use guidance ('Best for broad/multi-part questions over structured data') and when-not-to-use guidance ('For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'). Also covers account requirements and depth selection.

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 it as read-only, idempotent, non-destructive. The description adds that returns top-N relevant tools with full schemas and examples, ready to call, which is valuable context.

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

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

Two sentences, no fluff. Front-loaded with purpose, then usage advice. 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 high param count (6, but many aliases for one concept) and no output schema, the description fully explains what to expect: tool names, descriptions, full schemas with examples, and that results are directly callable.

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

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

Schema coverage is 100%, but description adds meaning: explains aliases for query (q, task, description, search) and that returned results are ready to call without second lookup. Examples further clarify.

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 finds tools by describing data or task, listing many domains. It distinguishes from sibling tools (which are specific tools) by being the discovery gateway.

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 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' and provides concrete when-to-use scenarios.

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 extensive behavioral traits: it fans out across multiple sources (SEC, XBRL, USPTO, etc.), returns specific fields (cik, filings, fundamentals, patents, news, LEI), and notes the patents soft-fail after May 2025. This adds context beyond the readOnlyHint and other annotations.

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

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

The description is long but front-loaded with example queries and every sentence contributes value: examples, preference instructions, data source breakdown, parameter constraints. Slightly verbose but justified by tool 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 complexity and lack of output schema, the description covers inputs, behavior, return fields, limitations, and fallback mechanisms. It does not detail response format or error handling, but annotations and context mitigate this.

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 meaning by explaining that 'value' can be ticker or CIK, and that names are not supported, directing to resolve_entity. This practical guidance exceeds the schema descriptions.

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

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

The description uses specific verbs like 'tell me about', 'research', 'brief me on' and clearly defines the tool's function: full cross-source profile of a US public company. It distinguishes from siblings like resolve_entity by stating that names are not supported and requiring prior name resolution.

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

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

The description explicitly says 'ALWAYS PREFER over chaining single-pack...lookups when the user asks for a holistic view' and instructs to use resolve_entity for names. This gives clear when-to-use and when-not-to-use guidance.

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

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

Annotations already provide destructiveHint=true and idempotentHint=true. Description adds context about clearing sensitive data and stale context, which aligns with annotations and provides practical guidance.

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

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

Two concise sentences front-loaded with the action, followed by usage guidance. No filler or 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?

Tool is simple with one parameter and no output schema. Description covers purpose, usage, and behavioral context adequately.

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

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

Schema coverage is 100% and the description does not add additional meaning beyond what the schema already provides for the 'key' 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 uses a specific verb 'Delete' and resource 'memory by key', clearly stating the action. It also mentions related tools 'remember' and 'recall' to distinguish from siblings.

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

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

Explicitly states when to use: 'context is stale, the task is done, or you want to clear sensitive data'. Also pairs with 'remember and recall' for complementary usage.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds value by detailing that the tool fetches external URLs, extracts content, and emits a standard markdown format, which goes beyond the annotations.

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

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

The description is a single, readable paragraph of 4 sentences, front-loading the purpose. It could be slightly trimmed (e.g., 'so AI crawlers can index the site cleanly' is implied) but is generally efficient.

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 (2 params, no output schema), the description fully covers what the tool does, its output format, and use cases. No gaps identified.

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

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

Schema coverage is 100% (both url and max_links described). The description mentions 'any URL' but doesn't elaborate on max_links beyond schema defaults. It adds minimal 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 explicitly states it generates a production-ready llms.txt file by fetching a page and extracting key info. The title and description are aligned, and the tool is clearly distinguished from siblings like ai_visibility_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?

The description lists three specific use cases (client indexing, own project, competitor audit), providing clear context. It lacks explicit 'when not to use' or alternatives, but the sibling list implies 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, covering safety and idempotency. The description adds behavioral context by specifying that the tool returns 'household counts with cost burdens, overcrowding, and housing problems', which is not in annotations.

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

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

The description is extremely concise, using three short sentences that front-load the action and resource. Every sentence adds value without redundancy, making it easy to parse quickly.

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

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

Given the complexity of 4 parameters and the presence of an output schema and rich annotations, the description is complete enough. It clarifies the tool's purpose and output, though it omits details like pagination or authentication requirements (already in schema).

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

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

The input schema has 100% description coverage for all 4 parameters. The description does not add any additional meaning beyond what the schema already provides, so baseline 3 is appropriate.

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

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

The description clearly states the action 'Get', the resource 'housing affordability data', and specifies the dimensions 'by income level and family type'. It lists the returned data types and suggests a use case, making the purpose unmistakable.

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

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

The description explicitly says 'Use for housing needs assessment', providing a clear usage context. However, it does not mention when not to use or contrast with sibling tools, so it lacks 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?

Description adds mapping and translation behavior beyond annotations (readOnlyHint, idempotentHint). It does not contradict annotations. However, it could include more detail on rate limits or authentication scope, though schema covers the API key requirement.

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

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

Two sentences, front-loaded with action and output, followed by use cases. Every sentence earns its place with no redundancy. Highly efficient.

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 simple parameters, full schema descriptions, and presence of output schema, the description provides complete context for selecting and using this tool. No missing information.

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

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

Schema coverage is 100% with clear descriptions for all three parameters. Description does not add per-parameter semantics beyond the schema, but the overall purpose enriches understanding. Baseline 3 is appropriate.

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

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

Description clearly states the action ('Map'), resource ('ZIP codes to census tracts, counties, CBSAs, and congressional districts'), and output ('geographic identifiers'). It distinguishes from sibling HUD tools like hud_chas or hud_income_limits which serve different data retrieval 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?

Explicitly states use cases: 'translate between location code formats or join datasets.' Provides clear context for when to use. Does not explicitly exclude alternatives, but given sibling tools are for different HUD data queries, the guidance is sufficient.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds valuable behavioral details: the tool resolves HUD's required entity ID from area_name and expands 5-digit FIPS to a 10-digit county ID, plus the default for omitted year. This enriches the annotation-provided safety profile without contradicting it.

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 just three sentences, with the main action front-loaded. Every sentence earns its place: the core action, the entity resolution behavior, and the year default. No waste.

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

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

Given the tool has 5 parameters, an output schema, and strong annotations, the description covers all meaningful usage variations: area_name+state_code, FIPS expansion, entity_id omission, and year default. It does not need to explain return values because the output schema exists, and the safety profile is supplied by annotations.

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

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

Even though the schema covers all parameters (100%), the description adds significant meaning beyond the schema by explaining how parameters interact: area_name requires a state_code, FIPS is accepted and expanded, and omitting entity_id/resolves to all areas in the state. This is exactly the kind of parameter semantics that helps an agent invoke the tool correctly.

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

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

The description opens with a specific verb and resource: 'Get HUD Fair Market Rent ceilings by bedroom count (0–4+) for a county or metropolitan area and year.' This clearly distinguishes it from sibling HUD tools like hud_income_limits and hud_chas, which address different data sets.

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 concrete usage guidance: pass area_name with a state code, use a 5-digit FIPS, or omit entity_id to get all areas in a state; omit year to get the latest fiscal year. However, it does not explicitly mention when to use this tool over alternatives or include exclusion criteria, so it stops short of a perfect score.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the core behavioral traits (safe, idempotent, non-destructive) are covered. The description adds that it returns income limits by category, but no further behavioral details (e.g., rate limits, authentication needs beyond the schema). With annotations present, the description does not contradict them and provides minimal additional context, meeting the baseline.

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

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

The description is three sentences long, front-loading the purpose and key details. It is efficient with no superfluous words. Minor improvement could be better structuring the return value mention, but overall it is concise and well-organized.

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

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

Given the presence of an output schema (so return values need not be fully detailed) and annotations for safety, the description is moderately complete. It omits mention of the required API key (_apiKey) as an authentication requirement, which is important context not covered by annotations. The 'family size' inaccuracy also detracts from completeness. Still, for a straightforward query tool, it covers the essential query logic.

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 covers 100% of parameters with clear descriptions, so the baseline is 3. However, the description mentions 'by family size' but there is no family size parameter in the schema; this is misleading and may cause confusion about what inputs are needed. The description thus adds a negative semantic value beyond the schema.

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

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

The description clearly states the tool's purpose: checking income eligibility thresholds for HUD programs by area and family size, and returning income limits by category. It uses specific verbs ('check', 'returns') and specifies the resource ('income eligibility thresholds'). Among sibling tools like hud_fair_market_rents, hud_chas, etc., this tool is distinctly about income limits, so it effectively differentiates itself.

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 includes 'Use to determine program qualification', giving a clear context for when to use the tool. However, it does not provide explicit when-not-to-use guidance or mention alternatives (e.g., hud_fair_market_rents for rental values). The usage context is clear but lacks exclusions.

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

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

Annotations already declare readOnlyHint and idempotentHint. Description adds context on return value (state abbreviations and names) without contradicting annotations. Good additional 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?

Two concise sentences with no redundancy. Front-loaded with main purpose, followed by usage guidance. Every word is useful.

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 (single parameter, output schema present), the description fully covers what an agent needs: purpose, return type, and usage context. No 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% and describes the only parameter (_apiKey) as 'HUD API token'. Description does not add new semantic details beyond the schema, so baseline score of 3 is appropriate.

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

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

The description clearly states the tool lists U.S. state codes and names, specifies return value (abbreviations and full names), and distinguishes it as a support tool for other HUD 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 advises using the tool to validate or discover state codes for other HUD tools, providing clear context. Lacks explicit when-not-to-use or alternatives, but the narrow scope makes it 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 (readOnlyHint, idempotentHint, destructiveHint) already signal safe, read-only behavior. The description adds the specific return structure (id, type, params, timestamps, fire_count), providing useful behavioral context beyond annotations.

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

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

Two efficient sentences: first defines purpose and output, second gives usage guidance. No redundant information, perfectly front-loaded.

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

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

For a simple tool with no output schema, the description compensates by enumerating return fields and providing usage context. It is complete for the agent to understand when and what to expect.

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

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

Schema coverage is 100% with a clear parameter description for include_inactive. The main description does not mention the parameter, but the schema fully covers it, so a baseline of 3 is appropriate.

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

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

The description clearly states the action (list) and resource (caller's subscriptions), and lists the exact return fields. It is specific and distinguishes the tool's purpose from siblings like subscribe and unsubscribe.

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

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

Provides explicit usage scenarios: review monitoring before adding more or find an id to cancel. While it doesn't explicitly state when not to use, the context 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?

The description discloses rate limiting (5 per identifier per day), that it is free and does not count against quota, that the team reads digests daily, and the claim_token flow (returned when filing without an account, usable later to read status/changes). Since annotations provide no safety hints, this context is valuable and does not contradict the annotations.

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

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

The description is a single dense paragraph but every sentence serves a purpose: purpose, use cases, exclusions, claim_token mechanics, rate limits, and cost. It is slightly long but appropriately front-loaded with the core action before caveats.

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 4 parameters, nested context object, and no output schema, the description covers key invocation patterns and boundaries. Minor gaps remain: it does not clarify what happens if the tool is called with no arguments or exactly what an account-based filing returns versus a claim-token filing.

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 good per-parameter descriptions, so the baseline is 3. The description adds extra meaning for claim_token ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})' and 'with no other arguments') and for message content ('don't paste the end-user's prompt'), which goes beyond the schema.

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

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

The description opens with a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It immediately distinguishes the tool from siblings like ask_pipeworx or research tools by framing it as feedback about Pipeworx itself, not a domain query.

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 conditions for bug, feature/data_gap, and praise, and an explicit when-not-to-use: if the problematic tool came from a different MCP server, file it there instead. It even tells the agent how to verify if unsure ('Pipeworx tool names are the ones this connection lists').

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds valuable context: data source (CF analytics-engine), no PII, caching behavior (5min-1h depending on window), and the self-aggregating nature. This 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 concise and front-loaded with the main purpose, followed by use cases and implementation details. It is well-structured without unnecessary words, though it could be slightly more compact.

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

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

Given the single optional parameter and no output schema, the description fully covers purpose, usage, behavior, and parameter meaning. An agent can correctly select and invoke this tool without additional context.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning to the 'window' parameter by explaining what shorter vs longer windows surface ('Shorter windows surface what's hot right now; longer windows show steady-state demand.'), providing additional guidance 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 what the tool does: 'Returns the top tools, top packs, and total call volume over a recent window.' It uses specific verbs and resources, and the sibling list shows no direct competitor, making it easy to distinguish.

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?

Three explicit use cases are provided, giving clear guidance on when to use the tool. However, it does not explicitly mention when not to use it or how it compares to alternatives, so it is not a 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?

The description extensively discloses behavioral traits beyond annotations: it explains monotonicity checks, partition-sum logic, semantic anchor for cross-event pairs, partition filter for placeholder slugs, fill check against CLOB depth, and trade advisories (e.g., realizable_edge_pp <= 0 means don't trade). Annotations are consistent (readOnlyHint, openWorldHint, idempotentHint, no destruction).

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

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

The description is long but well-structured: it begins with the core purpose, then details each mode with examples. Every sentence provides useful information (e.g., fill check, semantic anchor thresholds). Slightly verbose but front-loaded and efficient for 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 modes, fill checks, partition filters) and lack of output schema, the description fully explains the return structure: opportunities array with fields, partition_check object in event mode, and fill check results. It also references a sibling tool (polymarket_fill_risk) for custom sizing, ensuring 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 baseline is 3. The description adds significant meaning: explains that `event` accepts full URLs, describes how `topic` works as a seed question for semantic search, and clarifies the behavior of each mode. This adds value 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 clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes three modes (no-arg trending scan, event-specific, cross-event topic) and provides specific use cases, differentiating it from siblings like polymarket_edges 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?

The description gives explicit guidance on when to use each parameter: pass `event` for a specific market slug, pass `topic` for cross-event scanning. It recommends `event` mode for specific markets and explains the semantics of each mode. Could be improved by stating when not to use (e.g., if no clear event or topic exists), but still clear.

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

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

The description provides extensive behavioral details beyond the annotations: caching at 1h, diagnostics for empty segments, tradeable-edge filters, and the move warning. It does not contradict any annotations (readOnlyHint, etc.) and adds significant value.

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

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

The description is long but every sentence is substantive. It front-loads the purpose and then details models, response, knobs, and caching. No wasted words, though it could be slightly more concise given the density.

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 9 parameters, no output schema, and complexity, the description is very complete. It explains the output structure, model families, edge calculation, knobs, and caching, leaving little ambiguity.

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

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

Schema coverage is 100%, so the baseline is 3. The description does not repeat parameter details but adds overall context about knobs and their effects. No additional meaning is added per parameter 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 that the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price. It explains the three model families and the output structure, distinguishing it from siblings like polymarket_arbitrage by focusing on edge discovery.

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

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

The description positions the tool for 'what should I bet on today' and explains the adjustable knobs like min_liquidity and max_spread_pp for filtering. It provides clear context on when to use the tool, though it does not explicitly compare to alternatives or state when not to use.

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

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

The description extensively discloses behavior: it is read-only (consistent with annotations), explains response structure (tracked, expired, snapshot_dates), details computed fields (trend, decay_pp_per_day), notes that negative values indicate SELL YES, and mentions limits (60-day TTL, daily closes). This adds significant value beyond annotations.

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

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

The description is fairly long but well-structured, with a clear opening sentence, parameter details, response breakdown, and limitations. Every sentence adds value, though minor trimming 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 no output schema, the description comprehensively explains the return structure (tracked, expired, snapshot_dates with fields) and constraints (TTL, decay computation). This is fully sufficient for an agent to understand and 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?

Both parameters are described in the schema with high coverage. The description adds contextual meaning ('lookback', 'snapshot family') that clarifies their purpose, slightly surpassing the baseline of 3 for well-documented schemas.

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: providing edge persistence and decay telemetry from historical snapshots. It explicitly answers the question 'how long has this edge existed and is it shrinking?', and distinguishes from sibling tools like polymarket_edges by emphasizing historical context vs. current edges.

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

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

The description explains the use case (assessing edge longevity) and provides defaults for parameters. However, it does not explicitly state when not to use this tool or directly contrast with siblings like polymarket_edges for real-time needs. Still, the context and detail imply appropriate usage.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, etc. Description adds detail: walks the ladder, returns specific fields, explains risks of partial fills. 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 uppercase mode labels and bullet-like info. Front-loaded with purpose. Slightly dense but appropriate for complexity. Every sentence is useful.

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?

Complex tool with two modes, no output schema. Description explains both modes, all parameters, return fields, and risks. Complete enough for an agent to invoke correctly.

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

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

Schema coverage is 100%, baseline 3. Description adds meaning: explains size_usd interpretation for buys vs sells, default side in basket mode, difference between market and event. Adds substantial 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?

Clearly states the tool checks realizable vs theoretical edge against live CLOB order-book depth. Distinguishes from siblings by specifying it's a risk check before acting on arbitrage or edge signals. Verb 'check' and resource 'edge against order-book depth' are 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?

Explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' Provides reasoning: theoretical overround on thin books isn't capturable, partial basket fills convert arb into unhedged directional position.

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

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

The description goes far beyond annotations, detailing compatibility warnings for mismatched bet shapes, temporal alignment issues, and skipped cross types. It explains when spreads are meaningful and when they are not, providing comprehensive 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?

The description is well-structured with clear sections and bold formatting for key terms. It front-loads the core purpose. However, it is somewhat lengthy and could be slightly more concise without losing important safety warnings.

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 three optional parameters, no output schema, and rich annotations, the description is highly complete. It covers response structure, safety fields, limitations, and compatibility conditions, leaving no obvious gaps for a skilled 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%, but the description adds significant value by explaining the purpose of each parameter: topic for pre-mapped macros, explicit tickers override the mapped side, and provides examples. This clarifies usage beyond the schema descriptions.

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

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

The description clearly states the tool computes cross-venue spread between Kalshi and Polymarket, specifies two modes (topic shortcuts and explicit tickers), and differentiates itself from siblings like polymarket_arbitrage by focusing on cross-venue comparison.

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

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

The description explains when to use each mode (topic for pre-mapped macros, explicit for custom pairings) and warns that most shortcuts currently return compatibility warnings, implying limited usefulness. However, it does not explicitly mention alternatives or when not to use the tool.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds scoping to identifier and pairing with remember/forget, providing extra behavioral context beyond annotations.

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

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

Three well-structured sentences: function, usage, context. Front-loaded with primary action. Efficient without unnecessary words.

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

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

Given single optional parameter, no output schema, and rich annotations, the description covers purpose, usage, scope, and paired tools. Adequate for a simple retrieval tool.

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

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

Schema description coverage is 100% and already explains the key parameter's behavior (omit to list). Description echoes this without adding new semantic details beyond what the schema provides.

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

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

The description clearly states it retrieves a value saved via remember or lists all keys, with examples like user's target ticker or address. It distinguishes from siblings by explicitly pairing with remember and forget.

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

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

Clear guidance to use when needing previously stored context without re-deriving it. Omitting key lists all keys. No explicit when-not-to-use, but context is sufficient.

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

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

Description adds behavioral details beyond annotations: mark_read flags events as read, polling works fine, alternative GET endpoint exists. No contradictions with annotations (readOnly, idempotent, etc.).

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 cover main purpose, return fields, filtering options, and key behavioral note (mark_read). No fluff, 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 5 parameters and no output schema, description explains return fields and parameter behavior well. Lacks only a brief mention of default ordering or pagination, but overall complete.

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

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

Schema coverage is 100%, and description adds context: type, since, mark_read, unread_only have further explanation (e.g., 'flag returned events read', 'only newer ones'). Adds value beyond schema descriptions.

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

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

Clearly states the tool pulls fired events from subscription feed and returns recent alerts with specific fields. However, it does not explicitly differentiate from sibling tools like list_subscriptions or subscribe.

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 guidance on polling, filtering by type/since, and mark_read behavior. Mentions an alternative HTTP endpoint for scripts. No explicit exclusions or 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?

Annotations already indicate readOnly, idempotent, non-destructive. Description adds critical behavioral context: fan-out to multiple sources with specific fallback logic (GDELT preferred, GNews on rate-limit, USPTO soft-fail), output structure, and citation URIs. This goes well beyond annotations.

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

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

The description is well-structured with a clear front-load of trigger examples, followed by source details and parameter explanation. It is slightly verbose with the list of examples, but every part is informative. Efficient use of text.

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 fully explains return values (changes[] grouped by source, total_changes count, pipeworx:// citation URIs). It covers all relevant behavioral aspects (fallback, soft-fail, date formats) for a complex multi-source tool, ensuring the agent can use it correctly.

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

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

Schema covers all parameters with descriptions. The description adds valuable context: relative shorthand patterns ('7d', '30d', '3m', '1y'), typical monitoring window ('30d' or '1m'), and value formats (ticker or CIK). While schema baseline is 3, this extra guidance merits 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 explicitly defines the tool as a change feed for a company, listing specific trigger phrases ('What's new with X', 'latest on Y') and sources (SEC, GDELT/GNews, USPTO). It clearly distinguishes from the sibling entity_profile tool, making 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?

Provides explicit when-to-use examples and directly states when to use the alternative entity_profile ('Use entity_profile instead when you want the static profile...'), offering clear guidance on tool selection.

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

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

Discloses scoping by identifier, authentication persistence, and 24-hour retention for anonymous sessions. Adds value beyond annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false). 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?

Compact and front-loaded with purpose. Minor redundancy in 'across this conversation or across sessions' but overall efficient.

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 explains purpose, usage, storage behavior, and pairing with siblings. Adequate despite no output schema, as the tool is a simple write operation.

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

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

Schema coverage is 100%; description adds naming conventions via examples (e.g., 'subject_property'), improving clarity above the schema baseline.

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

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

Clearly states the tool saves data for reuse across conversations/sessions, using key-value pairs. Distinguishes from siblings recall and forget by explicitly naming them.

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

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

Explicitly advises when to use ('when you discover something worth carrying forward') and mentions alternatives (recall, forget).

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 readOnly/idempotent annotations, the description discloses valuable behavioral traits: internal cascade over multiple endpoints, graceful degradation when GLEIF/OpenFIGI are unavailable, source labels on each identifier, and explicit listing of unresolved identifiers. This gives the agent a realistic performance model beyond what annotations alone provide.

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

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

The description is long but well-structured: it opens with concrete example queries, states the core action, then details supported types. Some sentences are dense (especially the company type), but every sentence carries useful information, so the length is justified and it remains readable.

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

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

Given the absence of an output schema, the description does an excellent job of explaining what the agent can expect: canonical identifiers with source labels, unresolved identifiers listed separately, graceful degradation, and fallback behavior. It covers inputs, outputs, and failure modes comprehensively for a lookup 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?

While schema coverage is 100%, the description greatly expands parameter semantics by explaining what each type returns (company vs drug), giving input format examples (ticker, CIK, name; brand/generic), and noting edge cases like unresolved identifiers. This is a substantial value-add over the bare 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: resolving user-spoken names to canonical/official identifiers needed by other tools, with concrete query examples. It distinguishes itself from siblings like entity_profile and compare_entities by explicitly framing it as a prerequisite ID lookup step ('Use FIRST whenever you have a name but need an ID').

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 ('Use FIRST whenever you have a name but need an ID') and explains that it replaces 2-3 manual lookups. However, it does not explicitly mention when not to use it or directly name alternative sibling tools for comparison, so it stops short of full when/when-not coverage.

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

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

Beyond annotations (readOnly, idempotent, openWorld), description adds that it probes each entity, ranks by score, and returns score/confidence/signal density. No contradiction with annotations.

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

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

Four sentences, front-loaded purpose, method, use case, output. No unnecessary words; every sentence adds value.

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

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

Describes return format (ranked list with score, confidence, signal density) since no output schema. Covers input constraints and rationale. Missing error handling or edge cases, but adequate for the tool's complexity.

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

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

Schema has 100% coverage but description adds extra constraints (entities 2-8) and clarifies _apiKey is passed to api.anthropic.com. Also explains context parameter usage for disambiguation.

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 compares AI visibility across multiple entities side-by-side, using ai_visibility_check to probe each entity and rank them. It distinguishes from sibling tool ai_visibility_check (single entity) and compare_entities (likely different comparison).

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

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

Explicitly says it's useful for competitive AI-marketing audits and gives a concrete question example. Implies when to use vs. single-entity check, though no explicit when-not-to-use or alternative list.

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 reveals multiple behavioral traits beyond annotations: calls deps.dev and bundlephobia, partial failures degrade gracefully with sources_failed list, bundlephobia first measurement can take 5-30s. Annotations already mark readOnly, idempotent, and non-destructive, so description adds valuable context like timeout 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?

Description is relatively compact given the complexity, starting with the core purpose and then detailing behavior and limitations. Minor fluff like 'composite "should I add..."' could be trimmed, but overall it earns its length.

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

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

Despite no output schema, the description fully explains return structure (summary block with specific fields, per-advisory detail, links, alternative versions), covers partial failure behavior, and notes ecosystem limitations. An agent has enough information to invoke and interpret results correctly.

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

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

Schema has 100% coverage, but description adds value by clarifying that scoped packages are accepted and version defaults to latest. This extra guidance helps agents correctly set parameters beyond the schema's 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?

Description clearly states the tool performs a composite check for npm packages, covering license, advisories, version history, bundle size, and tree-shaking. It distinguishes itself from siblings by being the only npm dependency scanner, and its specific verb 'scan_dependency' is well-explained.

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

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

Explicitly says 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"' and notes that NPM ecosystem is the only one supported in v1, directing other ecosystems to deps.dev 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?

The description adds rich behavioral details beyond annotations: it reveals the embedding model (BGE-base-en), similarity metric (cosine), chunking strategy (500-char overlapping windows), character cap (200K with truncation flag), and the inclusion of character offsets for verification. No contradiction with annotations.

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

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

The description is a single dense paragraph that front-loads the core purpose and packs multiple informative details. While efficient, it could benefit from bullet points or clearer structural separation for easier scanning.

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 explains return values: top-N passages with character offsets and similarity scores. It also covers technical details (embeddings, windowing, truncation), making the tool’s behavior and output completely understandable.

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% (all three parameters have descriptions). The description adds helpful examples for the query parameter and reiterates limits, but does not provide substantial new meaning beyond the schema. Baseline score 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 'Semantic search INSIDE a fetched record' and provides concrete examples (SEC 10-K, article, long tool result). It distinguishes the tool by specifying it searches within already-fetched text, contrasting with siblings like ask_pipeworx_grounded that ground over passages.

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 advises use when 'the record is too big to cram into the prompt' and explains the benefit of saving context. It also mentions pairing with ask_pipeworx_grounded, providing a clear use case. However, it does not explicitly state when not to use it or list alternative tools beyond that one pairing.

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 significant behavioral traits beyond annotations: requires OAuth account, delivery channel specifics (always-on feed, optional email/SMS/webhook with constraints), SMS cap (10/day), webhook auto-disable after 10 failures, one-time secret return. Annotations only indicate mutation and idempotency, so description adds crucial 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 appropriately sized for a complex tool with multiple types and delivery channels. It front-loads the main action and return value, then systematically details type-specific parameters, delivery options, and edge cases. Every sentence adds value 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?

Given the complexity (5 subscription types, 3 delivery channels, no output schema), the description is remarkably complete. It covers prerequisites, return value (subscription ID), type-specific params, delivery constraints (SMS cap, webhook secret, auto-disable), and account requirements. No critical 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?

With 100% schema coverage, baseline is 3. The description adds extensive meaning: type-specific examples for each enum value (e.g., sec_8k with ticker and items), detailed delivery options (e.g., webhook HMAC signing, SMS verification requirement), and constraints (SMS cap, webhook auto-disable). This far exceeds the schema's minimal 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 creates a proactive monitoring subscription to a live-data event stream and returns the new subscription ID. It distinguishes from sibling tools like list_subscriptions and unsubscribe by focusing on creation and proactive monitoring.

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

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

The description provides clear context on when to use the tool (to create a subscription) and prerequisites (requires Pipeworx OAuth account; anonymous/BYO cannot persist). It does not explicitly list when not to use alternatives, but the context is sufficiently clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. Description adds that it returns category-bucketed example questions drawn from the live catalog with exact tool+argument shapes, which is useful behavioral context beyond annotations. 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 detailed but front-loaded with purpose and usage. Every sentence adds value, though it is slightly lengthy. Structure is clear with examples and categories listed.

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 onboarding tool with one optional parameter and no output schema, the description is very complete: it explains the return type (category-bucketed questions with tool shapes), when to use, and how to focus. No 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 has 100% coverage with a description for 'topic' listing possible values. Description adds that omitting 'topic' gives full spread and passing it focuses, which adds usage nuance beyond the schema's enum-like 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 it's the onboarding entry point for a new agent, returning category-bucketed example questions with tool+argument shapes. It distinguishes from siblings like 'ask_pipeworx' and 'discover_tools' by being the first use when unsure what Pipeworx can do, and it lists the categories covered.

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 this FIRST when you do not yet know what Pipeworx can do for you' and mentions learning how to call meta-tools. It also provides a condition for omitting or including the 'topic' parameter, giving clear when-to-use and focus 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 provide readOnlyHint, destructiveHint, idempotentHint. Description adds ownership enforcement and deactivation behavior, offering useful context beyond annotations. 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?

Two sentences, front-loaded with the core action, no unnecessary words.

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

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

Given the tool's simplicity (one param, no output schema, annotations present), the description provides all necessary context: action, ownership, effect on data, and parameter source.

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

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

Schema has 100% coverage for the single parameter 'id' with clear description. The tool description does not add extra parameter semantic details, meeting the baseline for high schema coverage.

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

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

The description clearly states the action (cancel), resource (subscription), and identifier (by id). It distinguishes from sibling tools like subscribe and 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?

Ownership enforcement is explicitly stated—users can only cancel their own subscriptions. The description also clarifies that the row is deactivated, not deleted, retaining historical data. No explicit when-not-to-use guidance 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?

Annotations already declare readOnly, openWorld, idempotent, and non-destructive, and the description adds substantial behavioral context beyond that: the exact verdict enum with definitions, the distinction between 'could_not_verify' (did not happen, carries error object) and 'unsupported' (no source coverage), and the automatic routing logic. This is highly valuable transparency for callers, with no contradiction to annotations.

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

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

The description is longer than usual but every sentence earns its place: examples, dual-path explanation, return contract, and critical error semantics. It front-loads with user intents, making the purpose immediately clear. It is not overly verbose for the complexity of the tool, though it could be slightly tightened.

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 conveys the return value structure (verdict enum, grounded/structured value with citation, reasoning) and the special handling of failure modes. It explains both routing branches and the replacement of multi-step calls, giving the agent a complete mental model for successful invocation and response interpretation.

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 with descriptions, giving a baseline of 3. The description adds meaningful nuance for tolerance_pct (overrides wording-implied tolerance, recommended for hallucination detection) and clarifies claim as natural-language input with examples. This goes beyond mere schema repetition, so a 4 is warranted.

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

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

The description clearly identifies the tool as claim verification against authoritative sources, with explicit natural-language examples and a precise verb-resource pairing ('verify' + 'factual claims'). It distinguishes itself from siblings by describing the two-path execution (SEC EDGAR for financials, grounded pipeline otherwise) and by stating it replaces 4–6 sequential calls.

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

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

Explicitly states when to use: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also differentiates between company-financial claims and all other factual claims, routing to different pipelines. However, it does not name specific sibling tools as alternatives or state when not to use it, so it falls short of fully explicit exclusion guidance.

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