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 cover read-only, idempotent, open-world, and non-destructive behavior. The description adds context about the routing mechanism, citation URIs, speed, and tier availability, enriching the behavioral model 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 lengthy but front-loaded with the key instruction ('PREFER OVER WEB SEARCH'), followed by structured examples and alternatives. Every section earns its place; minor redundancy in domain lists is acceptable for this broad tool.

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

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

Given the tool's broad scope, the description covers when, why, and how to use it, including limitations and alternatives. The lack of an output schema is mitigated by specifying that results include structured answer data and pipeworx:// citation URIs.

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

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

All six parameters are documented in the schema with high coverage; the description adds no extra parameter-level detail beyond example natural-language questions. Baseline 3 applies.

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

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

The description clearly states the tool's role: it routes questions to one of 5,529 tools across 1,455 sources and returns structured answers with citations. It explicitly differentiates from siblings like ask_pipeworx_grounded and deep_research, making its purpose unambiguous.

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

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

Extensive guidance is provided: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and explicit step-up instructions to ask_pipeworx_grounded for grounded answers and deep_research for multi-part questions. It also lists example queries and domain coverage.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior. The description adds valuable context about its experimental nature, current identical behavior to the stable router, and that it 'falls back to nothing' meaning it's a full working router. This exceeds annotation coverage without contradiction.

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

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

The description is a bit longer than typical but every sentence earns its place: it defines the tool, states current status, gives usage guidance, and clarifies it's not a fallback. The structure is logical and front-loaded with the beta identity.

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 all essential aspects: what it is, how it differs from the stable version, current operational state, usage instruction, and response shape ('same response shape'). With no output schema, this fills the gap by referencing ask_pipeworx's shape. A complete and self-sufficient description for an agent.

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

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

Schema coverage is 100%, with all parameters documented including aliases. The description's mention of 'same arguments' adds a small amount of context but doesn't delve into parameter specifics, which is acceptable given the schema's completeness.

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

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

The description clearly states it is a beta universal router identical to ask_pipeworx, with the same 5,529 tools and response shape. It distinguishes itself from the stable sibling by highlighting its experimental routing improvements and current inactive candidate status.

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 says 'Use it exactly like ask_pipeworx when you want the newest routing' and explains that results are compared against the stable router for merging decisions. It stops short of naming exclusions or when NOT to use it, but the context is clear enough for an agent to choose between beta and stable.

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, but the description adds critical behavioral context beyond annotations: the strict grounding to tool results, explicit refusal reasons ('not_in_source', 'no_tool_match', etc.), 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?

While the description is relatively long, it is tightly structured and every sentence adds unique value: mode, routing, extraction, return format, refusal reasons, use cases, and cost trade-off. It is front-loaded with the core purpose and uses clear separators, avoiding redundancy.

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

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

Despite having no output schema, the description explicitly enumerates the success return structure and all refusal reasons, making return behavior fully specified. It also covers cost trade-offs and use case boundaries, which is essential for a high-stakes tool. Completeness is exceptional.

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

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

Schema coverage is 100% for all six parameters, all of which are natural-language aliases for the single 'question' parameter. The description doesn't add parameter-level details, but given full schema coverage, the schema already carries the semantic load. 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 a specific verb ('ask') and resource ('Pipeworx') with a distinct mode: 'Hallucination-resistant answer mode for high-stakes reads.' It differentiates from sibling ask_pipeworx by noting 'Same routing as ask_pipeworx' but adds an extraction step and explicit refusal behavior, 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?

Explicit when-to-use guidance is provided: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts...' It also names the alternative: 'prefer ask_pipeworx for casual lookups.' This fully addresses usage context.

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

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

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

Beyond the annotations (readOnly=true, idempotent=true), the description discloses auth requirements, runtime expectations, gap handling (never invented), contradiction scans, semantic excerpting, and citation fetchability. This is a thorough behavioral account that adds significant value over the structured 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 quite long and not front-loaded—it opens with account requirements rather than the core purpose. It also repeats some details already present in the schema's parameter descriptions. While the length is somewhat justified by the tool's complexity, the structure could be improved by putting the main purpose first and trimming 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?

With no output schema, the description fully explains the return value structure (findings packet with evidence, confidence, source, fetched_at, citation, gaps[], contradictions[]), runtime, auth, and depth semantics. It is exceptionally complete for a complex research 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?

The input schema already describes both parameters with 100% coverage, so the baseline is 3. The description adds contextual meaning by giving examples of suitable questions, explaining that multi-part questions are acceptable, and elaborating on depth levels (including the paid thorough tier). This extra context justifies raising the score to 4.

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

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

The description clearly defines the tool as a multi-source research tool over Pipeworx's 1455 structured data sources, explicitly stating it is NOT open-web search and contrasting with ask_pipeworx. It uses a specific verb (research, decomposes, routes) and identifies the resource (structured data sources), making it easy for an agent to distinguish from siblings.

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

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

Provides explicit when-to-use guidance: best for broad/multi-part questions over structured data, while single lookups and breaking/current-news topics should use ask_pipeworx. Also includes a fallback if not signed in, making the tool selection logic clear.

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

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

Annotations already indicate readOnly, idempotent, non-destructive. Description adds 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?

Annotations already indicate read-only, open-world, idempotent, non-destructive. The description adds detail about fanning out across multiple sources, patent API sunset (soft-fail behavior), and return structure. No contradictions.

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

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

The description is a single dense paragraph but efficiently conveys purpose, usage, behavior, and return format. It could be slightly more structured with bullet points, but it is not verbose and front-loads examples and preference guidance.

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

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

No output schema exists, so the description thoroughly explains all return elements (cik, filings with URIs, fundamentals sorted by period_end, patents with sunset note, news via fallback, LEI). It also covers edge cases like patent unavailability and name requirement.

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

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

Schema has 100% coverage with descriptions for each parameter. The description adds meaning by specifying that value accepts ticker or zero-padded CIK, and that names are not supported, which goes beyond the schema's basic type/description.

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

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

The description clearly states the tool provides a 'full cross-source profile of a US public company', lists example queries, and details the returned data (cik, filings, fundamentals, patents, news, LEI). It is distinct from siblings like compare_entities or deep_research.

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

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

Explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' and advises using resolve_entity if only a name is available, since names are not supported.

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?

The description discloses extensive behavioral traits beyond annotations: computation of spreads, raw probabilities, top_spreads_pp, compatibility_warning (with two specific cases), temporal_alignment, and skipped counters. 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 well-structured, with a clear purpose statement upfront, followed by modes, response, and safety fields. While it could be slightly more concise, every sentence contributes meaningful information given the tool's complexity.

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

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

Despite lacking an output schema, the description thoroughly covers return values (raw probabilities, matched spreads, compatibility warning, temporal alignment, skipped counters) and warns about the rarity of tradeable spreads. It provides all necessary context 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 coverage is 100%, so baseline is 3. The description adds significant value: explains the 'topic' parameter's 10 shortcuts and their auto-fetch behavior, and the override logic for explicit tickers. This goes beyond the schema's examples.

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

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

The description clearly states the tool computes the cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes itself from siblings by focusing on cross-venue comparison rather than within-Polymarket arbitrage, and specifies two modes (pre-mapped shortcuts and explicit tickers).

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

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

The description provides clear usage context: two modes, safety fields, and warnings about compatibility and temporal alignment. However, it does not explicitly contrast with sibling tools like polymarket_arbitrage or polymarket_edges, which could guide selection when the agent needs alternative tools.

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

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

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

Beyond the annotations (read-only, idempotent, open-world), the description reveals valuable behavioral details: unresolved identifiers are explicitly listed under `unresolved` rather than omitted, LEI/FIGI enrichment degrades gracefully if upstream sources are unavailable, and every identifier is source-labeled. These traits are not inferable from the schema or annotations and help the agent anticipate edge cases.

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

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

The description is long but well-structured: it front-loads with examples and a directive, then organizes supported types under 'SUPPORTED TYPES'. Every sentence adds value (source labeling, unresolved handling, graceful degradation). However, some phrasing like 'cross-source identity spine' is jargon, and the promotional note about replacing manual lookups is non-essential, preventing a 5.

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

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

Since there is no output schema, the description must explain return values—and it does thoroughly. It specifies exact identifiers returned for each entity type (CIK, ticker, company_name, LEI, FIGI, RxCUI), how ownership data is presented, how unresolved identifiers are handled, and the fallback behavior when upstream sources fail. This gives an agent a complete mental model of the tool's behavior.

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

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

The input schema already provides 100% coverage for both parameters (type and value) with clear descriptions. The tool description adds examples (AAPL, 0000320193, ozempic) but essentially restates what the schema defines. Since schema coverage is high, the baseline of 3 applies, and the description does not meaningfully extend parameter understanding.

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

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

The description opens with concrete examples ('What's the ticker for…') and states 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' This clearly specifies the action (resolve), the resource (entity names to identifiers), and distinguishes it from sibling tools like entity_profile or compare_entities by emphasizing that the output feeds other tools.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID,' providing clear when-to-use guidance. It also notes that the tool replaces 2-3 manual lookups, giving context on efficiency. However, it does not explicitly name alternatives or list when-not-to-use scenarios, so it falls short of a 5.

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

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

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.