Housing Intel

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

Annotations already mark readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds that default model is free, Anthropic requires BYO key (cost implication), and return structure includes per-model details. No contradictions.

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

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

Two sentences, front-loaded with action and result. Every sentence provides essential information without fluff.

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

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

No output schema, but description summarizes return shape (score, confidence, signals, raw_response + combined view). Could detail more, but sufficient for typical usage.

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

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

Schema coverage is 100% but description adds value: clarifies default model (Workers AI Llama-3.3-70b free), condition for using _apiKey, and context parameter purpose. Enhances schema without redundancy.

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

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

Description clearly states it probes LLMs for brand visibility and provides a 0-100 score. Verb is 'probe', resource is 'LLMs', and it distinguishes from sibling tools which are mostly housing or Pipeworx 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?

Explicit use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. Also specifies when to use _apiKey (for Anthropic). Lacks explicit when-not-to-use but 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 establish read-only, open-world, idempotent, and non-destructive behavior, so the bar is lower. The description adds valuable context by explaining that the tool routes to a large tool registry, fills arguments automatically, returns structured answers with stable pipeworx:// citation URIs, and covers live news. There is no contradiction with the annotations.

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

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

The description is front-loaded with priority and scope, then trigger phrases, examples, and upgrade guidance. It is fairly long, but the length is mostly purposeful because this is a complex routing tool with many sibling alternatives. Minor redundancy between 'Use whenever...' and 'START HERE...' keeps it from a 5.

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

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

For a tool with no output schema, it still tells the agent what to expect: a structured answer with stable citation URIs, automatic argument filling, and routing across many sources. It also covers scoping, example queries, and explicit sibling alternatives. For a routing tool of this complexity, no essential calling information is missing.

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

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

Schema coverage is 100%: all six parameters are aliases of question, and each is documented in the schema. The description supplies helpful examples but no additional parameter-level semantics. Baseline 3 is correct when the schema fully carries parameter documentation.

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

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

The description names a specific verb and resource: it routes a natural-language question to 5,798 tools across 1,517 verified sources and returns structured, cited answers. It clearly differentiates from siblings by explicitly naming ask_pipeworx_grounded and deep_research as alternatives, and the opening 'PREFER OVER WEB SEARCH' anchors its role.

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

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

It explicitly states when to prefer this tool over web search, lists trigger phrases and example queries, and says 'START HERE for most questions.' It also defines when to upgrade: exact verbatim citations go to ask_pipeworx_grounded; broad/multi-part fan-out goes to deep_research; breaking-news is already handled here. This is strong when/when-not guidance.

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

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

Annotations already declare read-only, idempotent, non-destructive, and open-world. The description adds dynamic context: candidate routing improvements may activate, the last candidate retired 2026-07-26, and results are compared against the stable router. This goes beyond annotations by explaining the tool's experimental and evolving nature.

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 with no filler, but slightly repetitive: 'identical universal router' and 'currently matches ask_pipeworx exactly' overlap. The front-loaded first sentence gives the core purpose immediately, and every sentence contributes operational context.

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

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

For a routing tool with no output schema, the description states the response shape is the same as ask_pipeworx, and it explains the experimental behavior and current status. It could be more explicit about what the response contains, but referencing ask_pipeworx covers the essential. Since all parameters are documented and safety is covered by annotations, this is reasonably complete.

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

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

Schema coverage is 100%, with all six parameters documented as aliases for 'question'. The description adds no parameter-specific meaning beyond stating it has the same arguments as ask_pipeworx, which is redundant with the schema. Baseline 3 is appropriate.

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

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

States clearly that this is a beta version of ask_pipeworx, an identical universal router with the same 5,798 tools, arguments, and response shape. It differentiates itself from the stable ask_pipeworx sibling by being the experimental edge with candidate routing improvements. The verb 'ask' and 'router' indicate the action and resource.

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

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

Explicitly instructs 'Use it exactly like ask_pipeworx when you want the newest routing', naming both the condition and the stable alternative. Also clarifies current state (no active candidate, matches ask_pipeworx exactly) and that it is a full working router, not a fallback. This is strong when-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 cover read-only, open-world, idempotent, and non-destructive traits. The description adds meaningful behavioral detail beyond annotations: refusal reasons, that answers are extracted only from tool results, the returned field structure, and the extra LLM call cost. 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?

Dense but well-structured: starts with the core purpose, then return behavior, refusal cases, usage guidance, and cost tradeoff. Every sentence adds useful information and nothing is redundant with schema or annotations.

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 documents the success response fields and all possible refusal reasons. It also explains when to prefer this over the sibling ask_pipeworx, making the tool self-sufficient for correct invocation.

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

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

Schema description coverage is 100%, so the schema fully documents the 'question' parameter and its aliases. The description adds no additional parameter-specific semantics beyond saying the question is in natural language, which the schema already states.

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

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

States a precise purpose: 'hallucination-resistant answer mode for high-stakes reads' that routes through tools then extracts answers only from returned data. Explicitly distinguishes itself from ask_pipeworx by describing the same routing but a stricter, evidence-grounded output mode.

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?

Gives explicit when-to-use guidance: 'whenever an answer will be quoted, cited, or acted on' and lists high-stakes domains. Also names the cost tradeoff and explicitly prefers ask_pipeworx for casual lookups, giving a clear alternative.

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

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

Annotations indicate readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true. The description goes well beyond these, detailing safe operations (status codes for low-confidence matches, closed markets, wide spreads), resolving behavior, response shapes, and resolution-rule risk (cancellation_rule parsing). No contradiction with annotations.

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

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

The description is long but efficiently structured. It front-loads the core purpose and usage, follows with classifiers, examples, response shapes, safety notes, and resolution details. Every sentence contributes critical information for tool selection and correct invocation. No redundancy or wasted words.

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

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

Given the tool's complexity, the description covers all necessary aspects: input format, classifiers, fan-out behavior, response structure (market, analysis, evidence), resolver contract, parent event extractor, news fields, safety mechanisms, resolution-rule risk, and tradeability. No output schema exists, so the description compensates fully by detailing return shapes.

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

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

Schema coverage is 100%, providing baselines for the three parameters. The description adds significant value: it explains market can be slug, URL, or question text; depth affects evidence source count (quick vs thorough); include_raw controls verbosity and typical payload sizes. This context enriches the schema definitions.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the verb (research) and resource (Polymarket bet via Pipeworx data). It also distinguishes from sibling tools by listing explicit use cases ('Use for...') and providing categories like crypto_price, fed_rate, etc., which differentiate it from other Polymarket-related tools.

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

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

The description provides explicit usage scenarios: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also includes classifiers and fan-out examples (e.g., BTC bet → coingecko + fred + gdelt+gnews) that guide when and how to use the tool. It implies when not to use it (e.g., when quick answer needed via depth param) but does not explicitly exclude alternatives, which is acceptable given the thoroughness.

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

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

Annotations already declare read-only, open-world, and idempotent behavior. The description adds meaningful context about return values (latest level, changes, peak, drawdown, softening flag) and the ranking behavior, which goes beyond the schema. It does not disclose potential caveats like data frequency or API limits, but for a read-only tool this is acceptable.

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

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

The description is dense but tightly organized: purpose, outputs, usage examples, and available metros are clearly sectioned. Every sentence contributes useful information without redundancy, staying within a manageable 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 output schema present and annotations covering safety, the description covers all necessary context: what the tool does, what it returns, when to use it, and available inputs. This is complete for the tool's complexity.

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

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

Schema coverage is 100%, giving a baseline of 3. The description enhances this by enumerating all 20 available metros (Atlanta, Boston, Charlotte, etc.), which is not in the schema, and reinforces that any subset can be passed. This extra context helps parameter selection, meriting 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 uses a specific verb ('Compare'), a specific resource ('Case-Shiller home price indices'), and clearly defines scope ('across multiple US metros in one call'). It also distinguishes itself by mentioning the 20-city composite and the exact output metrics, setting it apart from sibling housing tools.

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

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

The description explicitly states when to use the tool with example query types ('which metros are softening', 'Case-Shiller for [list of cities]'), and shows the benefit of automatic FRED series ID selection. However, it does not explicitly mention when not to use it or name direct alternatives, so it stops short of a full 5.

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

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

Annotations already declare read-only, idempotent, not destructive. The description adds valuable context: for companies, it pulls latest 10-K financials from SEC EDGAR/XBRL with correct fiscal year handling; for drugs, it pulls FAERS, FDA approval counts, and clinical trial counts. Also explains result sorting and citation URIs.

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

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

Single paragraph densely packed but well-structured starting with triggers, then core function, then type details, then output info. Very efficient but could benefit from bullet points for readability.

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?

Without an output schema, the description explains the nature of returned data (paired data + citation URIs) and the specific metrics per type. Covers the key aspects for a comparison tool, though exact response structure isn't detailed.

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

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

Schema coverage is 100%. The description enhances understanding by explaining what data each type pulls (company vs drug), gives example values (tickers/CIKs, drug names), and notes result sorting.

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

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

Description starts with clear usage examples ('Compare X and Y', 'X vs Y') and states it does side-by-side comparison of 2-5 entities in a single call. It distinguishes from siblings by explicitly preferring this over sequential single-pack lookups.

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

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

Explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', provides example queries, and mentions it replaces 8-15 sequential lookups.

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

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

Annotations already declare readOnly/openWorld/idempotent, so safety is covered; the description goes well beyond that by disclosing account requirements, the paid gate for thorough, expected latency, the gaps[]/never-invented guarantee, resolvable citations, contradictions[] on standard/thorough, and semantic excerpting of large records. No statement contradicts 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 long but deliberately structured: access gate first, then core capability, usage guidance, then depth/citation/contradiction details. Nearly every sentence carries useful information, but the depth-behavior detail partly repeats schema text, preventing a perfect 5.

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

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

With no output schema, the description must define the return contract itself, and it does: findings packet with verbatim evidence, confidence, source, fetched_at, hop, citation_uri, gaps[], and contradictions[]. It also covers auth, pricing, latency, coverage limits, and the non-truncation behavior. This is complete for a complex orchestration 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?

Both parameters have full schema descriptions, so the baseline is 3. The prose adds non-schema value by exposing the paid tier constraint for depth:'thorough', concrete latency expectations per depth, and examples of the kind of question the tool is designed for. It does not add new syntax or formats, so a 4 (not 5) 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?

States a precise capability: 'Grounded multi-source research across Pipeworx's 1517 STRUCTURED data sources ... in ONE call' and describes the decompose/route/return pipeline. It explicitly distances itself from open-web search and from sibling tools ('For a single lookup use ask_pipeworx instead'). This makes its purpose unmistakable and differentiated.

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

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

Gives a clear best-use rule ('Best for broad/multi-part questions over structured data') with concrete examples, and names the alternative for the non-matching case ('For a single lookup use ask_pipeworx instead'). It also handles the access edge case: 'If you are not signed in, use ask_pipeworx instead' and tells which depth requires a paid plan. This is explicit when/when-not guidance.

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

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

Annotations already indicate readOnly, idempotent, non-destructive. Description adds that it returns top-N tools with full input schemas and curated examples, ready to call directly. No contradictions.

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

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

Description is a single paragraph but packed with essential info: purpose, usage context, what returns. Could be more structured but is sufficiently concise and front-loaded.

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

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

For a discovery tool, description covers purpose, return value (top-N tools with schemas), and parameters fully. No output schema but description explains what is returned. Complete enough given 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?

Schema coverage is 100%. Description explains aliases for query parameter (task, q, description, search) and how to use natural language. Adds value beyond schema by specifying usage.

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

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

The description clearly states the tool finds tools by describing data or task, listing specific domains like SEC filings, FDA drugs, etc. This distinguishes it from sibling tools which are specific actions.

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

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

Explicitly advises to 'Call this FIRST when you have many tools available and want to see the option set'. Provides context for when to browse/search/discover.

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 beyond the annotations: source fan-out, soft-fail for USPTO, semantics of sources_used/sources_failed, the meaning of empty sections, and the resolved:false flow for private companies. No contradiction exists with the readOnly/openWorld/idempotent/non-destructive 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 information-dense, front-loaded with examples and a clear directive before enumerating output sections. Almost every clause adds value, though the wall-of-text format could be better structured for quick 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?

With no output schema, the description compensates thoroughly by enumerating every return section, expected empty cases, failure modes, soft-fails, and input resolution rules. It gives an agent everything needed to interpret results and handle edge cases correctly.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description reinforces the interchangeability of type and value and adds examples, but it does not introduce meaning substantially beyond the input 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 produces a full cross-source profile of a US public company in a single call, with concrete example queries anchoring its intent. It stops short of naming sibling tools like compare_entities or resolve_entity, so differentiation is by approach rather than by explicit sibling 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 gives an explicit directive — 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' — which is strong when-to-use guidance. However, it does not name alternative sibling tools directly or specify when to avoid this tool beyond the implicit private-company limitation.

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

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

The description states 'Delete', which aligns with the destructiveHint: true annotation. However, it does not elaborate on behavioral traits such as idempotency (whether deleting a non-existent key is safe) or any permissions needed. Since annotations already provide destructive hint, the description adds minimal behavioral context beyond that.

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

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

The description is concise: two sentences with no unnecessary words. The key information is front-loaded (purpose first), and 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?

The tool is simple with one required parameter and no output schema. The description, schema, and annotations together provide sufficient context for usage. Minor omission: no mention of behavior when the key does not exist, but for a simple delete it is acceptable.

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 a clear description for 'key'. The description does not add additional semantic value beyond what the schema provides, so a baseline score of 3 is appropriate.

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

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

The description clearly states 'Delete a previously stored memory by key', which is a specific verb and resource. It distinguishes from sibling tools 'remember' and 'recall' by naming them, providing clear differentiation.

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 outlines when to use this tool: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also suggests pairing with 'remember' and 'recall', providing clear context and alternatives.

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

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

Annotations indicate read-only, open-world, idempotent, non-destructive. Description adds behavioral detail: fetches the page, extracts title/description/key links. No contradiction with annotations, and it enriches understanding of how the tool works.

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

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

Two sentences, front-loaded with purpose and format, followed by use cases. No wasted words.

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

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

Despite no output schema, description fully explains output: a single text blob ready for use. Inputs are simple; all relevant context is covered for a tool of this complexity.

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

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

Schema coverage is 100%, so baseline is 3. Description adds extra context: URL example and a note that default max_links is 25 with max 50, which provides more guidance than schema alone.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, listing specific actions (fetches page, extracts title/description/key links) and output format. It distinguishes from sibling tools by its unique function, with no ambiguity.

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

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

Explicit use cases are provided (getting client site indexed, drafting for own project, auditing competitors). While it lacks explicit negative guidance, the positive examples are clear and cover common 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?

Annotations already declare read-only and idempotent behavior, so the description doesn't need to cover safety. It adds the scope of returning affordability metrics and the optional metro filter, but does not mention API key requirements or fallback data behavior, which are deferred to the schema. Adequate but not richly transparent.

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 short, punchy sentences: purpose, outputs, and usage hint. No wasted words, front-loaded with the action, and the example adds clarity.

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

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

With 6 optional parameters and an output schema present, the description covers the essential purpose and key optional usage (metro). It does not mention the state/national fallback or API keys, but the schema handles those details, so the description is sufficient for tool selection and basic invocation.

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

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

Schema description coverage is 100%, so the schema already documents all parameters well. The description only reinforces the optional metro parameter with an example, adding marginal value beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states a specific verb ('Check') and resource ('housing affordability in a market'), and enumerates concrete outputs (mortgage rate, median price, monthly payment, required income, HUD limits). This distinguishes it from sibling housing tools like housing_market_snapshot or housing_mortgage_history.

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 purpose is clear enough to infer when to use it, and the optional metro example gives usage context. However, it does not explicitly mention alternatives or when not to use this tool, so it stops short of full guidance.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds no further behavioral context such as rate limits, authentication requirements, or side effects, so it neither contradicts nor enriches 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 two sentences and each serves a purpose: the first states the function, the second lists outputs. It is front-loaded and free of 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 tool's simplicity, the read-only annotations, and an output schema (which signals return structure is already defined), the description covers the essential scope. It provides enough information about what the tool assesses and returns for an agent to invoke it correctly.

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

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

The schema fully describes the two optional API key parameters with 100% coverage. The description does not mention parameters, but since schema carries the burden, the description adds no semantic value, resulting in the baseline score of 3.

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

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

The description uses a specific verb ('Assess') and identifies the resource as 'labor market health for housing demand,' then lists the returned data. This clearly states what the tool does, but it does not explicitly differentiate it from sibling housing tools, meriting a 4 rather than 5.

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 no guidance on when to use this tool instead of alternatives like housing_market_snapshot or housing_metro_demand. There are no prerequisites, exclusions, or context signals for selection, so the agent is left without usage direction.

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 establish the tool as read-only, idempotent, and non-destructive. The description goes beyond by revealing the output calculation (gross rent yield formula), the data source (Zillow), and the lack of API key requirement, which are useful behavioral traits not evident from 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 five sentences, each serving a distinct purpose: statement of function, output formula, performance/dependency notes, use cases, and parameter tuning guidance. It is front-loaded with the core purpose in the first sentence, though it could be slightly tighter.

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?

Without an output schema, the description appropriately clarifies that the tool returns a sorted list of metros with the yield calculation. It covers the tool's main capabilities, dependencies, and how to tune results, making it sufficiently complete 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?

All four parameters are fully described in the schema (100% coverage), so the baseline is 3. The description adds some context by explaining 'direction' as top/bottom and 'home-value bounds' as optional, but this largely overlaps with the schema descriptions.

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

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

The description clearly states the tool's function with a specific verb ('Rank') and resource ('US metros'), and differentiates it from sibling tools by focusing on rental cash flow and gross rent yield. It provides a precise formula and example use cases, making it obvious when this tool is appropriate.

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

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

The description explicitly lists use cases ('best/worst rental markets', 'highest-yield metros'), giving clear when-to-use guidance. It also mentions 'No per-metro orchestration' which implies it's the one-call alternative, though it doesn't explicitly name sibling alternatives.

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

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

Annotations already cover safety (read-only, idempotent, non-destructive), so the bar is lower. The description adds behavioral context by listing the exact national metrics included and the optional metro price addition, which goes beyond what annotations provide. It does not describe rate limits or API key behavior, but those are not central to the tool's core behavior.

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

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

The description is two sentences, front-loaded with the main action ('Get national housing market overview'), and every sentence earns its place. The first sentence lists the data points; the second provides an explicit alternative. No wasted words.

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

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

Given the tool's moderate complexity, the presence of an output schema, and full parameter documentation in the schema, the description is complete. It specifies what is returned, the optional metro parameter, and directs users to the right sibling for multi-metro comparisons. No key behavioral gaps remain.

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

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

The schema already provides 100% parameter descriptions, so the baseline is 3. The description adds value with examples for metro_name ('Denver', 'Atlanta') and clarifies that adding a metro is optional and that national data is always included. It does not significantly enhance the _blsKey/_fredKey descriptions, but the schema covers those adequately.

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

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

The description clearly states the tool provides a 'national housing market overview' and enumerates specific indicators (mortgage rates, housing starts, Case-Shiller index, unemployment, construction employment). It also distinguishes itself from the sibling tool case_shiller_metro_compare, 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 tells when to use this tool (when a national overview with optional single metro is needed) and provides a direct alternative for multi-metro Case-Shiller comparisons: 'For comparing Case-Shiller across multiple metros use case_shiller_metro_compare instead.' This gives clear when/when-not 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 (readOnlyHint, idempotentHint) already indicate safety and idempotency. Description adds extra behavioral context: deterministic by metro, uses Census ACS data, no API key needed. Does not contradict annotations.

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

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

Two sentences with a concise closing line. Front-loaded with main purpose and value proposition. No redundant information.

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

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

Covers all essential context: data sources (Census ACS), use case (demand validation), parameter hints, and integration with sibling tool. Despite no output schema, the description adequately informs what the tool returns.

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

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

Schema coverage is 100%, so baseline is 3. Description adds value by specifying format of metros ("City, ST") and connection to housing_market_screen output, plus default and max for limit. Provides examples in schema but context reinforces 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 specifies the tool provides demand and rent-durability signals for US metros, including specific data points (population growth, renter share, income, unemployment). It clearly distinguishes from sibling tools by positioning it as a Stage-2 filter after housing_market_screen.

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: as a Stage-2 filter on a yield shortlist after housing_market_screen. Provides a warning ('high yield in a shrinking metro is a trap') and contrasts with alternatives that require FRED series-ID guessing.

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. The description adds context: data sourced directly from Freddie Mac (not FRED), ingested weekly by the Pipeworx data pipeline. This clarifies data freshness and source, going 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 3 sentences with key information front-loaded: data source, frequency, what is returned. 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?

Given the tool has 2 optional parameters and an output schema (not shown but implied), the description covers source, update frequency, return contents (latest, time series, stats), and data provenance. It is complete for a read-only data 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 coverage is 100%, so the schema already documents both parameters. The description restates their purpose and adds that 'window' defaults to '1y' and 'as_of' returns closest observation. This aligns with baseline 3, as the description adds minor value over schema.

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

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

The description clearly states it provides the weekly US mortgage interest rate from Freddie Mac's Primary Mortgage Market Survey, back to 1971. It specifies it returns the latest snapshot, time series, and stats, distinguishing it from sibling tools like housing_market_snapshot or housing_affordability_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 explains what the tool returns (latest snapshot, time series, stats) and the parameters (window, as_of) but does not explicitly contrast with alternatives. However, the context of mortgage rates vs. other housing metrics is clear, and sibling names help infer usage boundaries.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description does not need to repeat safety. It adds value by explicitly listing return fields (valuation, sales history, tax assessment, characteristics), which helps the agent understand what to expect.

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, efficient sentence with no extraneous information. Every word earns its place, clearly conveying purpose and outputs.

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 a small parameter set (3), full schema coverage, and annotations covering safety, the description adequately covers what the tool does and returns. However, it could mention data coverage or limitations (e.g., US only) for 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% (all parameters have clear descriptions). The description adds that the tool analyzes 'by address and zip code', which is consistent with the schema, but does not provide additional semantic detail beyond what the schema already conveys.

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

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

The description clearly states the verb 'Analyze' and the resource 'property by address and zip code', and lists specific outputs: valuation estimate, sales history, tax assessment, and detailed characteristics. This distinguishes it from sibling tools like 'housing_market_snapshot' which aggregate market data across properties.

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

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

No guidance is provided on when to use this tool versus alternatives such as 'housing_affordability_check' or 'housing_rental_analysis'. No exclusions, prerequisites, or decision criteria are mentioned.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds output details but does not disclose additional behavioral traits such as dependence on third-party APIs (ATTOM/HUD/BLS) or rate limits. It does not contradict annotations, but it contributes only marginal behavioral context beyond the structured metadata.

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

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

The description is two sentences, front-loaded with the primary purpose, and includes a concise list of outputs. There is no fluff or repetition of schema information. Every word earns its place, making it highly efficient and easy to parse.

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

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

Given the tool's complexity (6 parameters, multiple API keys, output schema present) and rich annotations, the description adequately covers the core purpose and outputs. It lacks explicit contextual differentiation from sibling tools and does not mention that outputs may vary based on optional keys, but the schema and annotations fill those gaps. Overall, it is sufficient for an agent to invoke correctly, though slightly under-specified in usage 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 description coverage is 100%, so the baseline is 3. The description's mention of 'address and zip code' slightly reinforces the address parameters but adds no syntax or formatting details beyond the schema. It does not clarify that fair market rents require _hudKey or that CPI trends require _blsKey, though the schema already covers this. Thus the description adds no significant value over 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 function: 'Evaluate rental investment potential by address and zip code.' It also lists specific outputs (estimated rent, fair market rents, CPI rent trends), making it distinct from sibling tools like housing_market_snapshot or housing_property_report. The verb 'evaluate' plus the resource 'rental investment potential' is specific and unambiguous.

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

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

The description implies the intended use case: when you need rental investment metrics for a property. It does not explicitly name alternatives or exclusions, but the context is clear enough given the specific outputs. Since there are many housing sibling tools, a more explicit 'use this when...' statement would improve it, but it is not misleading.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds that the tool scans 45+ indicators and flags unusual moves, but it does not disclose details like data sources, rate limits, or how flags are presented. The added context is mild, so a 3 is appropriate.

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

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

The description is two concise sentences with no unnecessary words. It front-loads the action ('Scan') and includes a helpful list of covered categories, making it easy to parse.

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

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

The tool has zero required parameters and an output schema, so the description can focus on functionality. It lists the indicator categories, giving a good sense of scope. However, it does not mention the data sources or the nature of the anomalies, but this is likely covered by the output schema.

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

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

Schema coverage is 100%, with both parameters (_blsKey and _fredKey) fully described in the schema. The description adds no parameter-specific information, so the baseline of 3 applies.

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

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

The description uses a specific verb 'Scan' with a clear resource '45+ housing indicators' and a specific outcome: detecting anomalies and reversals. This distinguishes it from sibling tools like housing_market_snapshot or housing_affordability_check by emphasizing broad anomaly detection across multiple housing categories.

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

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

The description does not provide explicit guidance on when to use this tool versus alternatives. It implies a broad screening use case but does not mention any alternative tools, exclusions, or conditions under which another tool would be more appropriate.

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, idempotentHint, destructiveHint. Description adds return fields and 'active' qualifier, but adds limited 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 concise sentences with front-loaded purpose and usage. No wasted words.

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

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

Tool is simple with one optional parameter and no output schema. Description explains return format and usage scenario completely.

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

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

Schema coverage is 100% with description of 'include_inactive'. Description does not add extra meaning to parameter; baseline 3 is appropriate.

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

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

Clearly states 'List the caller's active subscriptions' with specific verb, resource, and scope. Distinguishes from sibling tools like subscribe/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?

Explicitly states when to use: 'review what you're monitoring before adding more or to find an id to cancel.' Does not mention alternatives 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?

Discloses rate limits (5 per identifier per day), the claim_token flow for later retrieval, that it's free, and that the team reads digests daily (affects roadmap). This goes well beyond the minimal annotations, providing a clear picture of side effects and lifecycle behavior.

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

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

The description is substantial but every sentence adds value: purpose, use cases, exclusion, formatting guidance, claim_token flow, rate limits, and cost. It is front-loaded with the core purpose and logically flows from what -> when -> how -> 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?

For a simple feedback tool with no output schema, the description fully covers the return mechanism (claim_token), limits, scope, and likely outcomes. It leaves no significant ambiguity about what happens when feedback is filed and how to follow up.

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 meaningful semantics beyond the schema: it explains the claim_token behavior (pass it back with no other arguments to read resolution status), the intended content of message, and how context should be scoped to Pipeworx tools/packs.

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+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly enumerates the categories (bug, feature/data_gap, praise) and is unambiguously distinct from sibling research/query tools like ask_pipeworx or discover_tools.

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

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

Explicitly states when to use it (bug, feature/data_gap, praise) and when NOT to use it, including a concrete exclusion: reports for tools from other MCP servers should be filed with that server. It also gives guidance on what to include (describe in terms of Pipeworx tools/packs, don't paste the user's prompt).

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) already signal safety; description adds caching intervals, data origin (CF analytics), and PII absence. No contradictions. Could mention pagination, but not essential for a summary endpoint.

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

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

One tight paragraph with bulleted use cases and technical details. Every sentence adds value; no fluff 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?

Given no output schema, the description names the return fields (top tools, top packs, call volume) but lacks specifics on format (e.g., list of objects, counts). Sufficient for an agent to invoke correctly, but slightly incomplete.

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 enum descriptions. The description adds meaningful context by explaining the trade-off between shorter (surfacing 'hot now') and longer windows (steady-state demand), going beyond the schema's enum values.

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 returns top tools, top packs, and total call volume over recent windows, clearly differentiating from siblings like 'discover_tools' by focusing on what other agents are currently using.

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 concrete use cases are given (discovering hot data sources, confirming canonical choice, aligning use case). Lacks explicit when-not-to-use guidance, but the examples are strong enough to infer appropriate 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?

Description richly augments annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) with internal logic: semantic anchor, partition filter, fill check, and warnings about realizable edge. No contradictions with annotations.

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

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

Description is detailed but front-loaded with core purpose. While somewhat verbose, every sentence adds value for a complex tool. Could be slightly more concise but justified by functionality.

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 the response structure (opportunities array, partition_check object, fill check details). Complete enough for an agent to interpret results.

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

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

Schema coverage is 100% with both parameters described. The description adds significant context: examples for event slug, explanation of cross-event scanning and Jaccard similarity for topic. Far exceeds 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?

Description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes three modes (no args, event, topic) and contrasts with sibling tools like polymarket_edges by detailing its specific arbitrage detection methods.

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

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

Explicit guidance provided: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', 'topic (for cross-event scanning)'. However, lacks explicit 'do not use when' statements, slightly reducing clarity.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description discloses caching behavior (1h KV-level cache keyed on all knobs), response structure (by_segment, diagnostics), and edge-case handling (e.g., 'Market moved X.Xpp in 24h' warning, Fed bets unreliability). It explains internal model details (lognormal barrier, GDELT volume ratio) and filters. No contradictions with annotations.

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

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

The description is lengthy but well-structured: it starts with the core purpose, then breaks down model families (with headers), response knobs, and response structure. Every sentence provides useful detail for an agent. It could be slightly more concise by removing some technical model details that might be unnecessary for selection, but overall it is effectively organized and fronts the key information.

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

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

Given the complexity (9 parameters, no output schema), the description is remarkably complete. It covers the response format (by_segment, diagnostics), explains why segments might be empty (top-N stale, failed gates, knobs), mentions caching, and highlights a data quality caveat (Fed bets unreliable). An AI agent would have sufficient context to invoke this tool correctly and interpret its output.

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

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

All 9 parameters are fully described in the schema (coverage 100%). The description adds significant semantic value: it explains each knob's practical effect (e.g., min_liquidity: 'Set to 5000 to drop thin-book opportunities'), provides default values, and gives context for tuning (e.g., slippage_pp: 'Polymarket has zero trading fees... 20-50bp per trade'). This goes well beyond mere schema documentation.

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 scans Polymarket markets for opportunities where Pipeworx data disagrees with market price. It specifies the purpose as 'what should I bet on today' and distinguishes from sibling tools by focusing on Pipeworx data-driven edges, with detailed model families (model_driven, structural_arbitrage, concentrated_longshot). This makes the tool's purpose unambiguous and differentiated.

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

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

The description explicitly states the use case ('what should I bet on today') and provides guidance on when to use tradeable-edge knobs (min_liquidity, max_spread_pp) to filter unrealizable opportunities. It explains that Fed bets are excluded from ranking and why. However, it does not explicitly contrast when to use this tool vs siblings like polymarket_arbitrage or polymarket_edge_tracker, leaving some ambiguity for an AI agent to infer.

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

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

Annotations indicate read-only, open world, idempotent; description adds that history depth is bounded by 60-day TTL, decay computed from daily closes (not intraday), and snapshots depend on cache-miss. No contradictions.

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

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

Description is front-loaded with core purpose and then details response structure. It's moderately dense but well-organized. A bit lengthy but every sentence adds value.

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

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

Despite no output schema, description fully explains response fields (tracked[], expired[], snapshot_dates[]) and their subfields, as well as limits and caveats, making the tool's behavior entirely clear.

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 already describes days and window with defaults and limits. Description only minimally adds 'snapshot family' context and repeats defaults, providing marginal extra value.

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 provides edge persistence and decay telemetry, answering 'how long has this edge existed and is it shrinking?' It distinguishes from sibling polymarket_edges by focusing on temporal analysis.

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

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

Explicitly tells when to use: to assess edge age and decay, contrasting a fresh wide edge with an old one. Implicitly contrasts with polymarket_edges. Also provides constraints like snapshot TTL and snapshotting enablement.

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 aligns with annotations (readOnlyHint=true, etc.) and adds substantial behavioral detail: how it walks the order book, interprets size_usd differently per mode, returns verdict (clean/degraded/cannot_fill), and highlights risks like thin legs and forced directional risk. No contradictions.

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

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

The description is well-structured with clear sections (REQUIRES, SINGLE-MARKET, BASKET) and front-loads the core purpose. While lengthy, every sentence provides necessary detail given the tool's complexity. Minor verbosity could be trimmed 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?

Given the tool's complexity (two modes, multiple return fields, no output schema), the description is exceptionally complete. It explains return values (top_of_book, vwap_fill_price, slippage_pp, capture_ratio, etc.), the verdict system, and risks like partial fills and unhedged positions. No gaps remain.

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

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

Schema coverage is 100%, but the description adds significant meaning beyond the schema: it explains the distinction between single-market and basket modes, default values for side and size_usd, and how size_usd is interpreted differently (max spend vs target proceeds vs settlement notional). This goes beyond the basic parameter descriptions.

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

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

The description clearly states the tool's purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It specifies two distinct modes (single-market and basket) and explains the return values. It differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on fill risk verification.

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 when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains why: 'theoretical overround on thin books is not capturable, and partial basket fills convert an arb into an unhedged directional position.' No alternative tools are named, but the context makes usage 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?

Beyond the read-only/idempotent annotations, the description richly discloses behavior: the token-overlap matcher, compatibility_warning/codes, gross-vs-net fee disclosure, skipped_unclassified handling, per-entry flags, and the explicit meaning of null temporal_alignment. It also states that both modes run the identical matcher and that returned pairs may still be unverified—far exceeding the annotation baseline.

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

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

The description is long but front-loads purpose, then proceeds logically through modes, response fields, safety codes, fees, and caveats. It could be tightened with more bullet structure, but every section conveys necessary operational detail for a complex tool with no output schema.

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 must fully specify return semantics, and it does: leg-by-leg prices, top_spreads_pp with per-entry flags, compatibility codes, temporal_alignment meaning, fees_note, and skipped counters. Edge cases like null resolution months and unclassified legs are explicitly addressed, making the tool safe to invoke 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?

The schema already documents all three parameters with 100% coverage, so the baseline is 3; the description adds value by explaining override behavior ('Overrides the topic-mapped side') and clarifying that both modes run the same matching logic and disclosures. That extra context justifies a score above the schema-only 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?

The description opens with 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' which clearly states the tool's resource and function. It distinguishes from single-venue polymarket tools by naming both venues, but it does not explicitly call out overlapping siblings like polymarket_arbitrage, so it misses the top score.

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

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

The description gives clear internal usage guidance: when to use topic mode vs explicit ticker/slug mode, and warns that 'pre-mapped ≠ tradeable' and that most shortcuts return compatibility warnings today. However, it never mentions sibling tools or conditions for choosing this tool over them, leaving tool-to-tool selection implied at best.

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

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

Annotations already declare read-only, idempotent, non-destructive. Description adds scoping to user identifier, listing behavior when key omitted, and pairing context, enriching the agent's understanding 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 sentences precisely convey function, usage, and context. Front-loaded with core action and 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?

For a simple tool with one optional param, clear annotations, and no output schema, the description covers purpose, usage, scoping, and tool relationships completely.

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 the single parameter fully (100% coverage). Description repeats the omit-to-list behavior but adds contextual usage examples. Baseline 3 is appropriate as no new parameter-level detail beyond schema.

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

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

The description clearly specifies the tool retrieves a saved value or lists keys, using specific verbs and resources. It distinguishes itself from siblings remember and forget.

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

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

The description provides clear when-to-use guidance with concrete examples (ticker, address, research notes) and mentions pairing with related tools. It lacks explicit when-not-to-use instructions but 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 declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral context: it returns the most recent alerts from a persisted feed, explains that mark_read flags events as read for future calls, and notes that polling works fine. 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 four sentences, front-loaded with the main purpose. Each sentence adds unique information: return fields, filtering options, mark_read behavior, and alternative access. No fluff, highly concise.

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

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

The description covers input parameters (type, since, mark_read), output fields (source, citation_uri, payload), and side effects (mark_read affects next call). It also mentions an alternative HTTP endpoint. Missing explicit details on error handling or pagination, but overall complete given five parameters and no output schema.

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

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

Schema coverage is 100%, so baseline is 3. The description adds an example filter type (sec_8k) and mentions the since parameter uses ISO timestamps, but these add minimal value beyond the schema descriptions. No new parameter semantics beyond summarizing.

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 pulls fired events from a subscription feed, specifying the verb 'Pull' and resource 'events from your subscription feed'. It lists return fields (source, citation_uri, raw event payload). However, it does not explicitly distinguish from sibling tools like list_subscriptions, leaving some ambiguity.

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 usage context such as polling behavior and an alternative HTTP endpoint, but does not offer explicit guidance on when to use this tool versus sibling tools (e.g., list_subscriptions, subscribe). It implies usage for retrieving alerts but without comparisons.

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 key behaviors: parallel fan-out to multiple sources (SEC, GDELT/GNews, USPTO), fallback mechanism, soft-failure for USPTO, and return structure. Annotations already indicate read-only, but description adds significant 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?

Well-structured: starts with example queries, then explains sources, parameters, return values, and alternative tool. Every sentence adds value; no fluff.

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

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

Despite no output schema, the description explains return values (changes grouped by source, total_changes count, citation URIs). Covers inputs, sources, fallback, and edge cases thoroughly.

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

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

Schema already covers all parameters with descriptions (100% coverage). The description adds value by explaining the 'since' parameter format with examples and clarifying acceptable formats for 'value', justifying a score above 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?

The description clearly states the tool's purpose as a change feed for a company, providing specific examples like 'What's new with X' and distinguishes it from sibling 'entity_profile' by noting when to use each.

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

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

Explicitly tells when to use (recent changes in a window) and when not to (static profile), and names the alternative tool 'entity_profile'. Also provides practical guidance on 'since' parameter format.

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

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

Annotations already indicate idempotentHint=true and destructiveHint=false. The description adds valuable context about scoping by user identifier, persistence duration (24 hours for anonymous, permanent for authenticated), and the key-value pair storage model.

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 yet comprehensive, with no unnecessary words. It front-loads the core purpose and then adds details in a logical order.

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

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

For a simple key-value memory tool, the description covers purpose, usage context, persistence behavior, and sibling relationships. No output schema is needed for such a straightforward 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 descriptions cover both parameters (key and value), so baseline is 3. The description adds practical usage examples ('resolved ticker, target address, user preference, research subject') that clarify typical use cases 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 saves data for reuse, using specific verbs like 'save' and 'store', and distinguishes from siblings by mentioning 'recall' and 'forget'. It covers both conversation and session persistence.

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

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

Explicitly tells when to use the tool ('when you discover something worth carrying forward') and how it pairs with 'recall' and 'forget'. Provides concrete examples of when it's appropriate.

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

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

Annotations already mark it read-only/idempotent/non-destructive, and the description adds substantial behavior: internal cascading lookups, graceful degradation when GLEIF/OpenFIGI is down, explicit `unresolved` identifiers, ambiguity handling via `figi_candidates`, and source-labelled identifiers. No contradiction with annotations.

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

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

The description is dense and information-rich, with the core directive and examples front-loaded. However, it is one long paragraph with several nested parentheticals, so it could be better structured; it is still appropriately sized for the tool's complexity.

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

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

Even with no output schema, the description covers return semantics (CIK/ticker/LEI/FIGI, drug RxCUI, `figi_candidates`, `unresolved`, source labels), edge cases (ambiguous names, non-US ISINs, degradation), and input constraints. An agent has enough context to invoke it correctly in almost any expected use case.

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

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

Although the schema already documents both parameters (100% coverage), the description adds practical semantics: concrete formats (AAPL, 0000320193, CH0038863350, 'ozempic'), the exact name-only instruction for bonds, and the warning that trailing security-class words will fail the FIGI lookup. This meaningfully improves 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?

States a specific verb and object: resolve a user-spoken name to canonical/official identifiers. The examples (ticker, CIK, LEI, RxCUI) and the two supported types make the scope unmistakable, and the phrase 'identifiers other tools require as input' positions it apart from sibling profile/comparison 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?

Provides an explicit trigger: 'Use FIRST whenever you have a name but need an ID.' It does not name sibling alternatives or state when not to use it, so it falls short of the top tier, but the usage context is 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 indicate readOnly, openWorld, idempotent, non-destructive. The description adds value by detailing that it probes each entity with 'ai_visibility_check', ranks by score, and returns a ranked list with score, confidence, signal density. It also notes the first entity is treated as the 'subject' for narrative, which is beyond annotation coverage.

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

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

The description is two concise sentences that cover purpose, method, and use case. It is front-loaded with the primary action. However, it could be slightly more structured (e.g., bullet points for return fields) to improve readability, but it is efficient and not verbose.

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

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

The description explains the return format (ranked list with score, confidence, signal density) despite no output schema. It also mentions the sub-tool invocation. However, it does not explicitly restate the entity count limit (2-8) from the schema, but that is captured in the parameter description. Overall, it provides sufficient context for correct tool usage.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds useful context: it clarifies that the 'context' parameter disambiguates common names and that the first 'entities' entry is the subject with others as competitors. This enhances understanding beyond the schema alone.

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 'Compare AI visibility across multiple entities side-by-side', which clearly identifies the verb (compare) and resource (AI visibility). It distinguishes from the sibling tool 'ai_visibility_check' which checks a single entity, and from generic 'compare_entities' by specifying AI presence context.

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 notes it is 'Useful for competitive AI-marketing audits' and provides an example question, implying when to use. While it does not explicitly state when not to use or name alternatives, the sibling tool 'ai_visibility_check' suggests single-entity cases, and the context is clear enough for an agent to infer 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, openWorldHint, idempotentHint, and destructiveHint. The description adds extra behavioral context: the composite nature, potential delay for bundlephobia's first measurement (5-30s), and graceful degradation with partial failures listed in sources_failed. 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?

The description is relatively long but each sentence earns its place: purpose, usage, output summary, ecosystem scope, failure behavior. It is well-structured with clear progression. Could be slightly more concise but remains informative.

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

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

Given no output schema, the description adequately lists the return fields (summary block, per-advisory detail, links, alternative versions). It also covers ecosystem scope and failure modes. Minor missing details (e.g., exact structure of advisory details) but sufficient for an AI to understand the output.

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

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

Schema coverage is 100% with both parameters described. The description adds value beyond schema: confirms default version behavior and clarifies that scoped packages (e.g., '@types/node') are accepted for the 'package' parameter.

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

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

The description clearly states the tool's purpose: a composite check for npm packages combining deps.dev and bundlephobia data. It uses specific verbs ('scan', 'fans out') and resource ('dependency'), and distinguishes from siblings by being the only dependency scanning tool.

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

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

The description explicitly tells when to use the tool ('when an agent asks is X safe / popular / small') and when not to ('NPM ecosystem only in v1; other ecosystems fall under deps.dev:version directly'). This provides clear guidance and alternatives.

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

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

Annotations already indicate safe, idempotent operation; description adds details like BGE embeddings, windowing, character offsets, and truncation 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?

Single dense paragraph with no fluff; each sentence adds value, and key information is 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?

Explains output contents (passages, offsets, scores) despite no output schema, and covers limitations like truncation flag.

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; description adds practical examples and clarifies the 200K char limit, enhancing understanding beyond schema.

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

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

Clearly states it performs semantic search inside a fetched record, distinguishing it from siblings like ask_pipeworx_grounded.

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

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

Explicitly advises using it when the record is too large for the prompt and suggests pairing with ask_pipeworx_grounded for grounding.

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 are present (readOnlyHint=false, destructiveHint=false, etc.) and the description adds behavioral context such as subscription types, delivery channel details, email format, phone verification requirement, webhook signing, and auto-disable after 10 failing runs. 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 lengthy but structured: begins with core purpose, then lists types and delivery options. It front-loads essential info and organizes details logically. A few sentences could be trimmed, but overall it maintains clarity and completeness.

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 no output schema, the description covers required dependencies (OAuth account), parameter constraints, and return value (subscription id). It addresses complexity of nested parameters and multiple optional delivery channels. Slightly missing information on error cases or conflict handling, but sufficient for agent usage.

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

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

With 100% schema coverage, the description enriches parameter meaning by providing type-specific examples (e.g., sec_8k with items), detailed filter structures for each type, and delivery channel constraints (SMS must match verified phone, webhook HMAC signing). This adds significant value beyond the schema's basic descriptions.

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

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

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream and returns the new subscription id. It distinguishes itself from sibling tools like list_subscriptions and unsubscribe by detailing subscription creation with specific types and delivery channels.

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 (proactive monitoring, requires Pipeworx OAuth account) and prerequisites (anonymous/BYO cannot persist subscriptions). It includes constraints on delivery channels (10/day SMS cap, webhook auto-disable). However, it does not explicitly mention when not to use or alternatives, though sibling tools like recent_alerts imply alternative use cases.

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 safe read-only, idempotent, open-world behavior. The description adds that the output is category-bucketed examples with exact tool+argument shapes, and how to call with or without a topic. No contradiction with annotations.

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

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

The description is somewhat long but front-loaded with alternative phrasings (e.g., 'What can I ask Pipeworx?'), making it scannable. It covers all critical aspects without waste, though it could be tightened slightly.

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

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

Given that the tool is an onboarding discovery tool with good annotations and a single optional parameter, the description fully covers what the tool does, how to use it, and what to expect in the return (category-bucketed examples). No output schema is needed as the return is described 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% with one optional 'topic' parameter described. The description adds concrete examples of topic values (e.g., 'finance', 'pharma') and explains that omitting topic gives a cross-category spread, which goes 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?

The description clearly defines the tool as an onboarding entry point that returns category-bucketed example questions with tool+argument shapes. It specifies verb+resource (suggest questions) and distinguishes from siblings like ask_pipeworx by stating it's for learning what the agent can do.

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 this tool: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' Also provides guidance on arguments (no args vs topic) and hints at alternatives by mentioning meta-tools.

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

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

Beyond the annotations (which indicate idempotent and non-destructive), the description reveals that the row is deactivated (not deleted) and that historical events remain accessible via recent_alerts. This adds critical behavioral context not captured in structured fields.

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

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

The description is two sentences long, each serving a distinct purpose: first stating the action and input, then explaining ownership and side effects. No wasted words.

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

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

For a simple tool with one parameter and no output schema, the description covers the action, ownership constraint, and post-effect (deactivation vs deletion). It is complete and leaves no ambiguity.

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

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

The schema description coverage is 100% for the single parameter 'id', describing it as 'Subscription id (uuid) returned by subscribe.' The tool description reinforces this by referencing the source of the id, but adds minimal extra 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 starts with a specific verb and resource: 'Cancel a subscription by id.' This directly states what the tool does and distinguishes it from siblings like subscribe, list_subscriptions, and recent_alerts.

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 clearly states ownership enforcement ('you can only cancel your own subscriptions'), providing a precondition. While it doesn't explicitly list alternatives or when not to use, the context is clear enough for an agent.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description adds crucial behavioral nuances: distinguishing 'could_not_verify' as a pipeline failure not to be treated as evidence, explaining 'unsupported' as no source coverage, and detailing the verification_error payload. This is exactly the kind of context annotations cannot convey.

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

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

Though long, every sentence adds value: trigger phrases, routing logic, verdict/error semantics, and efficiency claims are all packed in a logical flow. The front-loaded NL examples immediately signal the tool's purpose.

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

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

No output schema exists, so the description compensates by fully explaining return values (verdicts, verified value, citation, reasoning) and edge cases (could_not_verify with error details, unsupported). It also clarifies the tool's role in reducing multi-step orchestration, giving the agent a complete mental model.

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

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

Schema already describes both parameters (100% coverage), but the description significantly enhances meaning: it explains tolerance_pct's override behavior (set 1-2 for hallucination detection), the default 'implied by wording, capped at 5', and provides realistic claim examples. This goes well 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 states a specific verb+resource: 'natural-language claim verification against authoritative sources.' It clearly distinguishes itself from siblings by focusing on fact-checking with defined verdicts (confirmed, refuted, etc.) and the special handling of company-financial claims via SEC EDGAR.

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

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

Provides explicit use context: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains internal routing between structured and grounded pipelines. However, it does not explicitly mention when not to use it or name alternative sibling tools, missing a bit on the when-not/alternatives criterion.

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