Housing Intel

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint. Description adds return format (per-model fields + combined view) and clarifies that Anthropic requires own API key and direct payment. 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?

Two sentences: first covers main purpose, second adds details and use cases. No waste, front-loaded with key action.

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 4 parameters and no output schema, description explains return format, use cases, and optional API key. Could mention potential ambiguity or error handling 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%. Description adds value by explaining default model, free tier, and the API key requirement for Anthropic. Also clarifies 'context' parameter usage for disambiguation.

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

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

Description clearly states probe LLMs and score visibility (0-100). The verb 'probe' and resource 'LLMs' are specific. It distinguishes from siblings like housing or pipeworx tools, which are unrelated.

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.' It also explains default model and optional Anthropic probing. Does not explicitly list when not to use, but context is clear.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds value by explaining that the tool routes to the right tool among 3,745 sources and returns answers with stable citation URIs. No contradiction with annotations.

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

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

The description is relatively long but well-structured. It front-loads the key preference over web search and provides clear examples. Every sentence adds value, though a slight trim could improve conciseness.

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

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

Given the tool's complexity (routing to many sources) and the absence of an output schema, the description is complete. It explains what the tool does, when to use it, and what to expect (structured answers with citations). No additional information is needed for an agent to correctly invoke it.

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

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

Schema coverage is 100%, and the description explains that the parameter accepts natural language questions. It also lists aliases (q, query, prompt, etc.). The examples in the schema further clarify usage. The description adds meaning beyond the schema by stating that the tool fills arguments and returns structured answers.

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: to answer factual questions using authoritative structured data. It specifies the verb 'ask', the resource 'Pipeworx', and explicitly lists the domains it covers (SEC filings, FDA data, etc.). It distinguishes itself from alternatives like web search by emphasizing structured data with citations.

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 this tool over web search: 'PREFER OVER WEB SEARCH for questions about current or historical data...' It provides specific trigger phrases like 'what is', 'look up', 'find', and gives concrete examples. It does not mention when not to use it, but the preference is clear and actionable.

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

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

The description details the return structure (answer, evidence, confidence, source, fetched_at, refusal_reason) and lists explicit refusal reasons. Annotations already indicate readOnly, idempotent, openWorld, non-destructive; the description adds 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?

The description is approximately 150 words, well-structured with front-loaded purpose, bullet-style return format, and no wasted sentences.

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 (3,745 tools, 884 sources) and no output schema, the description is highly complete: it explains the mechanism, return format, refusal reasons, and cost.

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 one real parameter with aliases. The description adds value by specifying 'natural language' and context for the question, but schema already documents aliases thoroughly.

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

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

The description explicitly states the tool is for 'hallucination-resistant answer mode for high-stakes reads' and provides specific use cases (financial verdicts, legal claims, medical lookups) that clearly distinguish it from sibling tools like ask_pipeworx.

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

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

The description gives clear guidance: 'Use whenever an answer will be quoted, cited, or acted on' and explicitly advises to prefer ask_pipeworx for casual lookups, including a cost trade-off note.

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?

Massively exceeds annotations: describes fan-out behavior, response shapes, resolver contract, parent event extractor, news fallbacks, safety mechanisms (low-confidence, closed markets), wide-spread warnings, and resolution-rule risk. No contradiction with annotations (readOnlyHint, idempotentHint).

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?

Long but well-organized: purpose, classifiers, fan-out examples, response shapes, resolver contract, parent event, news fields, safety, resolution risk. Every section adds necessary detail; could be slightly more concise but appropriate for complexity.

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

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

Given 3 parameters and no output schema, the description covers return values exhaustively: nested structures (result.market, result.analysis, result.evidence), resolver contract, parent event, news fallbacks, safety mechanisms, and edge cases. No output schema needed.

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

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

Schema covers 100% of parameters with descriptions; the description adds context with examples, depth options, and size implications for include_raw. This adds value beyond the schema baseline 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 clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input types and output, but lacks explicit differentiation from sibling tools like polymarket_edges, though the level of detail makes 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?

Provides explicit use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' Also includes depth parameter guidance and examples, but does not explicitly state when not to use or suggest alternatives.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds that it returns latest level, 3-month change, 12-month change, all-time peak, drawdown, softening flag, and ranking. 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 paragraph with all key information: purpose, return fields, example queries, and available metros. It is front-loaded and efficient, though could benefit from slight structural formatting.

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

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

Given the presence of an output schema and full parameter documentation, the description provides sufficient context: it explains what the tool does, what metrics it returns, and which metros are supported. No gaps.

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

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

Schema coverage is 100%. The description lists available metros and mentions the platform key for _fredKey, adding value beyond the schema. It doesn't repeat schema details unnecessarily.

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

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

The description clearly states the tool compares Case-Shiller home price indices across multiple US metros, returns specific metrics, and handles FRED series IDs automatically. It distinguishes from sibling tools by focusing on the 20-city composite and providing per-metro data.

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

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

The description explicitly lists example queries ('which metros are softening', 'Case-Shiller for [list of cities]') and mentions it picks correct FRED series IDs. It could improve by noting when not to use it, but the context is clear.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. Description adds value by disclosing data sources (SEC EDGAR/XBRL, FAERS), handling of fiscal years, and that results are sorted by primary metric. 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 slightly verbose but well-organized, front-loading purpose with examples and then providing behavioral details. Every sentence adds value, though some redundancy exists.

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

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

Given no output schema, the description adequately explains return format (paired data + citation URIs) and sorting behavior. It covers key aspects for a comparison tool, though exact data structure could be more 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% with descriptions already present. The description adds extra context like '2-5 tickers/CIKs' and 'names', clarifying the expected format and constraints beyond the schema's basic description.

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

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

Description clearly defines the tool as a side-by-side comparison of 2-5 companies or drugs, with example queries. It distinguishes from siblings by explicitly stating preference over sequential single-pack lookups and referencing alternatives like entity_profile.

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

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

Explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing clear guidance on when to use. Example queries and specific entity types further clarify 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 provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds valuable context: parallel execution, gaps[] for unanswered facets, no invented facts, expected duration (15-60s). 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 well-structured and front-loaded with key purpose. Every sentence adds value, though slightly verbose. Could be trimmed slightly but still effective.

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 explains return format (structured findings packet, verbatim evidence, confidence, source, etc.). Covers prerequisites, timing, and sibling differentiation comprehensively.

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

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

Schema coverage is 100% with descriptions. Description adds meaning by explaining depth values (quick=3, standard=5, thorough=8) and linking 'thorough' to paid plans, plus clarifying question scope.

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 performs grounded multi-source research in one call, decomposing questions into sub-questions and routing to 3,745 tools. Distinguishes from sibling ask_pipeworx by specifying single lookups vs broad/multi-part questions.

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

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

Explicitly says when to use (broad/multi-part questions) and when not (single lookups, use ask_pipeworx). Also states requirements: Pipeworx account, paid plan for 'thorough' depth.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds that the tool returns top-N relevant tools with full schemas and examples, and that results are ready to call directly. This supplements annotations without contradicting them.

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

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

A single paragraph that front-loads the purpose, then gives usage context, then return details. No redundant sentences; every part 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 description fully covers what the tool does, when to use it, what it returns (top-N tools with names, descriptions, schemas, examples), and parameter aliases. Despite having many siblings and parameters, the context is complete and actionable.

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 value by clarifying that 'query' accepts natural language and aliases (task, q, search, description). It also specifies default and maximum for 'limit', which is not in the schema's description field.

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 'Find tools by describing the data or task' with a clear verb ('find') and resource ('tools'). It distinguishes from siblings by advising to call this tool first when exploring options, which sets it apart from individual data-retrieval 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?

Explicit guidance: 'Use when you need to browse, search, look up, or discover what tools exist for...' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This clearly defines when to use this tool versus alternative sibling 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 provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds valuable context: USPTO PatentsView API sunset May 2025 (soft-fails until reactivated), and that names are not supported. 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 packed with useful information but is slightly verbose. It front-loads with example queries, which is good. Every sentence is necessary, but could be more streamlined. Still very effective.

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 lists return fields and mentions potential soft-fail for patents. It also provides links to related tools (resolve_entity). Given the tool's complexity, the description is complete and covers edge cases.

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 has 100% coverage and parameters are well described. The description reinforces schema details and adds guidance (e.g., 'Names not supported — use resolve_entity first'). This adds value beyond the schema, justifying 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 clearly states the tool provides a full cross-source profile of a US public company, listing specific data sources (SEC, XBRL, USPTO, news, GLEIF) and returned fields. It distinguishes from sibling tools by explicitly stating to prefer over chaining 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 when to use: for holistic view of a company. Also provides clear exclusions: names not supported, use resolve_entity first. Additionally advises to prefer over chaining other tools, giving strong usage guidance.

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

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

Annotations already indicate destructiveHint=true. The description adds behavioral context by mentioning 'clear sensitive data' and implies the deletion is irreversible. 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?

Two sentences, no fluff. Action and purpose are front-loaded. Every sentence is meaningful.

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, single-parameter tool with annotations covering behavior, the description is fully sufficient. It includes purpose, usage context, and sibling references.

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

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

Schema coverage is 100% with a clear description for the 'key' parameter. The description adds no extra semantic beyond 'by key', so baseline 3 is appropriate.

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

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

The description clearly states the verb 'delete' and the resource 'memory' and specifies deletion by key. It distinguishes itself from sibling tools 'remember' and 'recall' by referencing them.

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

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

Explicitly states when to use this tool: 'when context is stale, the task is done, or you want to clear sensitive data'. It also pairs the tool with 'remember' and 'recall', providing clear guidance on alternatives.

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

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

Beyond annotations (readOnly, openWorld, idempotent, non-destructive), the description adds that it fetches the page, extracts title/description/key links, and outputs markdown. 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?

Single front-loaded paragraph with no wasted words. Every sentence adds value: main action, output, use cases.

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

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

Given no output schema, the description adequately explains output format. Covers parameters, behavior, and use cases. Annotations handle safety cues; description fills remaining gaps.

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

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

Schema coverage is 100% (baseline 3). Description adds examples and defaults (e.g., 'default 25, max 50' for max_links, example URL format). Provides useful context beyond schema.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, specifying the output format and use cases. It effectively distinguishes from sibling tools by focusing on AI crawler indexing.

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

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

Explicitly lists three use cases: getting a client's site indexed, drafting for own project, auditing competitor. Lacks explicit when-not-to-use, but context is clear enough.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint=true and destructiveHint=false, making safety and idempotence clear. The description adds that results include HUD limits and optional metro, but doesn't disclose behavioral details like data currency, rate limits, or required API key roles beyond the schema.

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

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

The description is two sentences, front-loading the core purpose and outputs, then noting the optional metro parameter. No extraneous wording; every sentence earns its place.

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

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

With an output schema present, the description does not need to detail return values. However, given the number of sibling tools, a brief note on when to use this tool versus others would improve completeness. Currently it covers the essential use case well.

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 each parameter has a description. The tool description adds only a brief note about optionally specifying a metro, which is already implied by the metro_name parameter description. This is adequate but not value-adding 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 checks housing affordability and lists key outputs (mortgage rate, median price, etc.). However, it does not differentiate from sibling housing tools like housing_market_snapshot or housing_rental_analysis, which could also provide similar data.

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

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

The description provides minimal usage guidance, only noting that a metro can optionally be specified. It does not explain when to use this tool versus the many other housing-related siblings, leaving the agent without clear selection criteria.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds value by enumerating specific return fields (employment, construction jobs, etc.), which provides behavioral context 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?

Two sentences, no filler. The first sentence states purpose, the second lists outputs. Information is front-loaded and every word earns its place.

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

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

For a simple tool with no required parameters, high annotation coverage, and an existing output schema, the description provides a useful overview of return values. It could mention data source freshness or potential limitations, but the given context is sufficient for typical use.

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

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

Schema description coverage is 100%; the schema already documents the single optional parameter _fredKey with a clear description. The tool description does not add any additional meaning or usage guidance for this parameter, so baseline 3 is appropriate.

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

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

The description clearly states the verb 'Assess' and the resource 'labor market health for housing demand'. It lists specific outputs (employment, construction jobs, etc.), distinguishing it from sibling housing tools that focus on prices or affordability.

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

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

The description implies usage for assessing labor market health related to housing demand but provides no explicit guidance on when to use this tool versus alternatives like housing_metro_demand or housing_market_snapshot. No when-not-to-use or exclude conditions are given.

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 agent knows it's safe and idempotent. The description adds valuable context beyond these: it specifies the exact formula (gross rent yield = (Zillow median monthly rent × 12) ÷ Zillow typical home value), clarifies the data source (Zillow, Pipeworx-hosted), and notes no API key is required. 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 three sentences long, each earning its place. The first sentence announces the core purpose (ranking for rental cash flow) with a compelling label. The second explains the metric and data source. The third gives example use cases and parameter tuning. 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 having no output schema, the description is complete: it defines the output (metros sorted by gross rent yield), the calculation formula, the data source, the key parameters (limit, direction, optional bounds), and the type of use cases. An agent can understand the tool's behavior, input constraints, and output format sufficiently to select and 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 input schema has 100% coverage with descriptions for all four parameters. The description adds meaning by explaining that 'direction' tunes between top/highest yield and bottom/lowest yield, and that home-value bounds are optional filters. It also mentions the default limit of 25 metros and max of 100, which maps to schema descriptions but recontextualizes them for the rental cash flow use case.

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 ranks US metros by rental cash flow in a single call, specifically positioning it as the 'which markets are best for a landlord' view. It distinguishes from siblings like housing_rental_analysis and housing_market_snapshot by focusing on a single metric (gross rent yield) and providing a high-level ranking, not detailed analysis.

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

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

The description provides explicit use cases: 'best/worst rental markets', 'highest-yield metros', 'where does rent go furthest vs. home prices'. It also notes the tool requires no per-metro orchestration and no API key, implying it's an efficient single-call alternative to iterative queries. However, it does not explicitly exclude alternative sibling tools for more nuanced rental analysis.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the description does not need to repeat these. The description adds context about the data content but does not disclose additional behaviors such as rate limits or data freshness. Given the comprehensive annotations, this level of transparency is adequate.

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

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

The description is extremely concise: two sentences with no filler. The first sentence lists the data provided, the second covers optional parameter usage and an alternative tool. Every word earns its place.

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

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

For a tool with two parameters, full schema coverage, and an output schema (not shown), the description covers the key aspects: purpose, optional parameter, and sibling alternative. It does not explain the output format, but that is handled by the output schema, so completeness is high.

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 by explaining that metro_name is optional, gives examples (e.g., 'Denver', 'Atlanta'), and clarifies that national data is always included. This enriches the schema information.

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 gets a national housing market overview, listing specific metrics (mortgage rates, housing starts, Case-Shiller index, unemployment, construction employment). It distinguishes from the sibling tool 'case_shiller_metro_compare' by noting that for comparing multiple metros that tool should be used instead.

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 guidance on when to use this tool (for a single snapshot of national data with optional metro-level prices) and points to an alternative for multi-metro comparisons. It does not cover all sibling comparisons but the guidance is clear and actionable.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint. The description adds non-obvious behavioral traits: deterministic by CBSA-key, data source (Census ACS), and no API key needed. It 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?

The description is concise, front-loaded with purpose, and each sentence adds value. It efficiently communicates what the tool does, its input, data source, and usage context without unnecessary words.

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

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

Given no output schema, the description fully explains the output content (list of specific signals). It addresses its role among sibling tools and provides all necessary context for an agent to select and 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?

Schema coverage is 100% with good descriptions for both parameters (limit default and max, metros format and example). The description reinforces the expected input format but adds no new parameter information 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 provides demand and rent-durability signals for US metros, listing specific data points (population growth, renter share, etc.). It distinguishes itself from sibling tools by positioning as a 'Stage-2 filter' after a market screen, and the input format references housing_market_screen, differentiating it from other 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 positions the tool as a 'Stage-2 filter' and instructs to pass metros from housing_market_screen, giving clear context for usage. It does not explicitly state when not to use it, but the relationship to siblings is implied.

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 valuable context: data is from Freddie Mac (not FRED) and updated weekly, informing freshness and reliability. No behavioral contradictions are present.

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 no superfluous content. The first sentence defines the tool's purpose and data, the second details output and provenance. Every word serves a purpose.

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

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

Given the simple tool (2 optional params, read-only, output schema exists), the description fully covers what the tool does, what it returns, and the data source. No critical gaps are apparent.

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 does not add additional meaning to the parameters beyond what the schema provides; it only describes output components. The parameter descriptions in the schema are sufficient.

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 returns Freddie Mac weekly US mortgage rates, including a snapshot, time series, and stats. The verb 'Returns' and resource 'Freddie Mac Primary Mortgage Market Survey' are specific, and the tool is distinct from sibling tools like housing_affordability_check or housing_market_snapshot, which focus on different aspects.

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 context on the data source and frequency ('Sourced from Freddie Mac directly... ingested weekly'), implying use for historical mortgage rate data. However, it does not explicitly state when to use this tool versus alternatives among the many sibling housing tools, lacking exclusion criteria or comparative guidance.

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

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

Annotations already indicate readOnly, idempotent, non-destructive. The description adds that it returns specific data types, which aligns with these annotations. No contradictions.

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

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

Two sentences, no fluff, front-loaded with action and resource. 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?

With output schema present, the description adequately covers key return types. It omits mention of the API source or authentication, but schema covers _attomKey. Overall sufficient for a read-only property report tool.

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

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

Schema description coverage is 100%, so the description adds no extra parameter meaning beyond what the schema provides. It mentions 'address and zip code' which maps to the params, but no deeper semantics.

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

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

The description clearly states the verb 'analyze' and resource 'property', and lists specific outputs (valuation, sales history, tax assessment, characteristics). It distinguishes from sibling tools like housing_market_snapshot which focus on broader market data.

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

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

The description implies usage for getting a detailed property report but does not explicitly state when to use or avoid it compared to alternatives. No guidance on prerequisites or exclusions.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior. The description adds detail about return types (rent, FMR, CPI trends), agreeing with annotations. No contradictions, but no additional behavioral context beyond what annotations provide.

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

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

Two sentences, zero waste: first defines purpose, second specifies outputs. Front-loaded with 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 presence of a full output schema and detailed annotations, the description adequately covers purpose and outputs. Minor gap: does not explicitly mention API key requirements (though schema lists them as required).

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 parameters are well-documented. The description reinforces the use of address and zip code, which maps to address1/address2/state_code, but adds minimal new semantic insight 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 evaluates rental investment potential by address and zip code, listing specific return types (estimated rent, fair market rents, CPI rent trends). However, it does not differentiate from sibling housing tools like housing_affordability_check or housing_market_snapshot.

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 on when to use this tool versus alternatives (e.g., when to prefer housing_rental_analysis over housing_affordability_check). No prerequisites or exclusion criteria 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, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds value by stating it scans 45+ indicators and lists categories, which clarifies the input scope without contradicting annotations.

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

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

Two concise sentences that immediately convey purpose and scope. No redundant information; every word earns its place.

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

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

Given the tool has one parameter, output schema, and annotations, the description covers the core functionality and scope. It could mention output expectations briefly, but the output schema likely covers that. It is complete enough for its simplicity.

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

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

Schema coverage is 100% with a description for the only parameter (_fredKey). The tool description does not add semantics beyond 'FRED API key', but since the schema already provides baseline, a score of 3 is appropriate.

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

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

The description clearly states the tool scans 45+ housing indicators for anomalies and reversals, specifying the categories (rates, starts, etc.). The verb 'scan' and resource 'housing indicators' are specific and distinguish it from sibling tools like housing_affordability_check which have narrower focus.

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 explicit guidance on when to use this tool versus alternatives, such as housing_market_screen or housing_affordability_check. The description does not mention preconditions, exclusions, or scenarios where it is not suitable.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. The description adds context about the specific fields returned and the default scope (active subscriptions), 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?

Two sentences, no wasted words. Critically front-loaded with purpose and output, then usage guidance.

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

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

For a simple read-only tool with one optional boolean parameter and no output schema, the description covers purpose, output fields, and usage context. 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%, so baseline is 3. The description clarifies the default behavior (active subscriptions only), which adds semantic value beyond the schema's parameter description.

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

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

Clearly states that the tool lists the caller's active subscriptions and enumerates the returned fields (id, type, etc.). Distinguishes from sibling tools like 'subscribe' and 'unsubscribe'.

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

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

Provides explicit use cases: 'review what you're monitoring before adding more' and 'find an id to cancel.' This tells agents when to use this tool vs 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?

Given minimal annotations (all false), the description fully discloses behavioral traits: rate-limited (5 per identifier per day), free, not counting against tool-call quota. Also notes that team reads daily and feedback affects roadmap, providing useful transparency.

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 that front-loads purpose, then usage, then constraints. Every sentence adds value, no fluff. It is concise yet comprehensive, covering all necessary aspects without excess.

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 has 3 parameters (2 required) with nested objects and no output schema. Description covers what to provide, how to structure feedback, rate limits, and behavioral context. It is fully complete for the agent to understand 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 baseline is 3. The description adds additional context beyond the schema, such as clarifying the 'type' enum values and advising what to include in the message (mentioning tools/packs, not pasting end-user prompts). This extra guidance justifies a slightly higher score.

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

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

Description clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It uses a specific verb ('tell') and resource ('Pipeworx team'), and is distinct from sibling tools which are all queries or actions unrelated to feedback.

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 specifies when to use the tool (for bugs, features/data gaps, praise) and provides guidance on what not to do ('don't paste the end-user's prompt'). Also mentions rate limits and quota, giving clear 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, destructiveHint=false, idempotentHint=true, and openWorldHint=true. The description adds valuable context: data source (CF analytics-engine), no PII, caching behavior (5min-1h). This extra information about data freshness and privacy enhances transparency 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?

Three sentences, each with clear purpose: first states core output, second lists use cases, third details source and caching. No wasted words, but the second sentence could be slightly more concise. Still, well-structured 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 simple tool with one optional parameter and no output schema, the description covers inputs, outputs, use cases, and behavioral traits (source, privacy, caching). No missing critical information. The context signals confirm 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 coverage is 100% with a single parameter 'window' that has enum and description. The description adds meaning by explaining that shorter windows surface hot trends and longer windows show steady-state demand. This provides practical guidance beyond the schema.

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

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

The description specifies the tool returns top tools, top packs, and total call volume over a recent window, using clear verbs like 'returns' and listing specific use cases. This distinguishes it from sibling tools like 'ask_pipeworx' or 'discover_tools' by focusing on trending aggregation rather than individual queries or tool discovery.

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

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

Explicitly states three use cases: discovering hot data sources, confirming canonical choice, and checking alignment. It also explains window trade-offs (shorter vs longer windows). While it doesn't list when not to use it, the contexts are sufficiently clear for an agent to decide.

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, idempotent, open-world, non-destructive. Description adds significant behavioral context: explains algorithms (monotonicity, partition checks), Jaccard similarity filter, placeholder filtering, fill check with realizable vs theoretical 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?

Well-structured with clear sections: requirement, purpose, mode details, filtering, response, fill check. Every sentence adds value, but slightly dense; could be marginally more concise without losing 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 complexity (two modes, algorithms, multiple filters), the description covers all necessary aspects: input requirements, algorithm details, response format, fill check. No output schema, but response is described adequately. Annotations cover safety.

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 3. Description adds value with examples ('fed-decision-may-2026', 'Fed rate decision'), explains mode behavior differences, and provides context not in schema, justifying 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 clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes two modes (event and topic) and differentiates from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

Explicit guidance: 'REQUIRES one of event (single-event mode) OR topic (cross-event mode) — call with no args fails.' Recommends event for specific markets and topic for cross-event scanning. Mentions sibling polymarket_fill_risk for custom sizing, providing clear when-to-use and when-not.

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, openWorldHint, idempotentHint, and destructiveHint false. The description adds extensive behavioral context: caching (1h at KV level), edge calculation details, segment filtering logic, diagnostics, and tradeable-edge knobs. 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 comprehensive but verbose (around 400 words). It is well-structured with clear sections but could be more concise. Front-loaded with purpose, but some sentences are complex and dense.

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 high complexity (9 parameters, no output schema, three segments), the description is extremely thorough. It explains output structure, filtering, diagnostics, and edge computation. The only gap is no return value description, but that is outside scope per rules.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond schema by explaining how parameters like min_kelly, min_edge_pp, and min_partition_leg_kelly interact with the overall logic, providing context that helps the agent understand their impact.

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

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

The description clearly states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price. It specifies the scope ('top Polymarket markets') and the specific verb 'scan,' distinguishing it from siblings like polymarket_arbitrage and polymarket_kalshi_spread.

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 it's built for 'what should I bet on today' and that agents can discover opportunities without paging. It provides context for use but lacks explicit when-not-to-use or alternatives, though it implies when not to use by discussing filters.

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 and idempotent behavior. The description adds significant behavioral context: details about the response structure (tracked, expired, snapshot_dates), the limitation of history depth (60-day TTL), and the fact that decay numbers are from daily closes not intraday. 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 detailed and well-structured with sections like RESPONSE and LIMITS. However, it is somewhat verbose, including illustrative phrases like 'the latter is wide for a reason nobody is willing to take.' Still, every sentence earns its place, and the structure aids 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?

Given no output schema, the description thoroughly explains the return structure: tracked array with edge history, trend, and decay; expired array with lifespan; snapshot_dates. The LIMITS section adds crucial context on data bounds. This completeness enables an agent to understand and use the tool effectively.

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 coverage is 100%, so baseline is 3. The description adds minor context (e.g., default days=14, max=30) but slightly mismatches the schema's clamp range. The window parameter description adds no new info beyond the schema. Thus, minimal added 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?

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It differentiates from the sibling tool 'polymarket_edges' by focusing on temporal analysis rather than raw edge data.

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

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

The description provides context for when to use this tool by posing the question 'how long has this edge existed and is it shrinking?' It contrasts fresh vs. old edges, but does not explicitly name alternative tools or state when not to use it, though the distinction from 'polymarket_edges' is implied.

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

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

Annotations already indicate readOnlyHint, idempotentHint, and not destructive. The description adds valuable behavioral context: it walks the order book ladder, returns verdicts like 'clean|degraded|cannot_fill', and warns about forced directional risk. 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 verbose with multiple sentences and detailed explanations. While structured with headings for modes, it could be more concise. However, the complexity of the tool justifies some length, so it is acceptable but not optimally 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?

Given the tool's complexity (two modes, no output schema), the description is remarkably complete. It details what each mode returns (top_of_book, vwap_fill_price, slippage_pp, etc.), explains risks, and provides usage thresholds. An agent can confidently select and invoke this tool based on the description alone.

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% for all 4 parameters. The description adds meaning beyond the schema: it explains size_usd in basket mode as 'settlement notional', clarifies default behaviors for side, and distinguishes modes. This extra context helps agents understand parameter usage correctly.

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

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

The description clearly states the tool does a 'Realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes two modes (single-market and basket). It explicitly differentiates from sibling tools by mentioning its use before polymarket_arbitrage and polymarket_edges, making its purpose distinct.

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 guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It also explains when not to use it and the risks of partial fills and directional risk, giving clear context for 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 indicate read-only, idempotent, non-destructive behavior. The description adds rich behavioral detail: response format, safety fields, compatibility warnings, temporal alignment, and skipped counters. 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 comprehensive but well-structured, front-loading the purpose and modes. While lengthy, every sentence adds value 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?

No output schema exists, so the description fairly covers response format and edge cases. It could mention maximum number of legs or pagination, but overall adequate for the 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?

Despite 100% schema coverage, the description adds significant meaning beyond schema: listing exact macro shortcuts, providing examples, and explaining how explicit parameters override topic-mapped sides.

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 computing cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes itself from siblings like polymarket_arbitrage by focusing on cross-venue comparison.

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

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

The description explicitly describes two modes (topic shortcuts and explicit pairings) and warns that pre-mapped topics often yield compatibility warnings, setting expectations. It lacks explicit exclusion of alternatives but provides clear context.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds context about scoping and pairing with remember/forget, 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?

Description is concise, front-loaded with main action, and consists of three efficient sentences with no waste.

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

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

Given low complexity (1 param, no output schema), description is complete: covers purpose, usage, scoping, and pairing with related tools.

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 parameter. Description explains the key parameter's usage (omit to list all keys), adding slight extra context beyond schema.

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

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

Description clearly states the verb 'retrieve' and 'list', specifies the resource (values saved via remember), and distinguishes from sibling tools '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?

Explicitly states when to use (looking up stored context) and mentions alternatives (remember, forget), as well as scoping to identifier.

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

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

The description adds substantial behavioral context beyond annotations: it explains the effect of 'mark_read' (flags read so next call returns newer), that results are 'persisted feed' and 'most recent', and that polling is suitable. Annotations already indicate read-only and idempotent, and the description reinforces consistency.

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, with no superfluous words. It front-loads the core action and immediately details return fields, filter options, and side effects. Every clause 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 having no output schema, the description explains what the return contains (source, citation_uri, raw payload). It covers all parameters, usage context (polling), and even mentions an alternative access method. For a tool with 5 optional parameters and no output schema, this is thoroughly complete.

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

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

All 5 parameters are described in the schema (100% coverage). The description adds contextual meaning: it ties 'type' to subscription types like 'sec_8k', explains that 'mark_read' affects subsequent calls, and mentions that 'since' is an ISO timestamp. The addition is helpful but not essential given 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 purpose: 'Pull fired events from your subscription feed' and specifies what it returns (source, citation_uri, raw event payload). It distinguishes itself from sibling tools like 'search_within' or 'subscribe' by focusing on subscription 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?

The description implies polling use ('Polls work fine') and provides an alternative endpoint for scripts/dashboards, guiding usage context. However, it does not explicitly exclude scenarios where this tool should not be used.

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, openWorldHint, idempotentHint, and no destructive behavior. The description adds significant context: fans out to multiple sources, describes fallback behavior (GDELT preferred, GNews when rate-limited), notes USPTO patent API sunset and soft-failure, explains date format options, and mentions the 'pipeworx://' citation URIs in the output. 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 relatively long but every sentence adds value. It is front-loaded with intuitive example queries, then covers sources, parameter details, and sibling differentiation. Could potentially be tightened slightly, but it is well-structured and efficient for the complexity involved.

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 the return structure: 'changes[] grouped by source + total_changes count + pipeworx:// citation URIs'. It covers input parameters thoroughly, source behaviors, fallback logic, date handling, and provides a sibling comparison. This is complete for a tool with 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% with descriptions for all three required parameters. The description adds value beyond schema by explaining the enum for type, providing examples for 'since' (both ISO and relative with common values like '30d', '1y'), and clarifying that 'value' accepts ticker or zero-padded CIK. It also explains the overall fan-out logic.

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

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

The description clearly states the tool returns a 'change feed for a company in the last N days/weeks/months' aggregating from SEC EDGAR, GDELT/GNews, and USPTO. It distinguishes from the sibling entity_profile tool which returns static profiles.

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

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

Explicitly lists example queries ('What's new with X', 'latest on Y', etc.) and provides a sibling alternative: 'Use entity_profile instead when you want the static profile'. This gives clear guidance on when to use this tool versus alternatives.

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

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

Adds key behavioral details beyond annotations: memory scoping by identifier, persistent for authenticated users, 24-hour retention for anonymous sessions. No contradictions with annotations (idempotentHint, non-readOnly).

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

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

Four concise sentences, front-loaded with primary purpose. Every sentence adds value, no 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?

Complete for a simple storage tool: covers purpose, when to use, behavior (persistence), and pairing with siblings. Output schema not needed.

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

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

Schema covers both parameters fully. Description enhances with concrete key examples (subject_property, target_ticker) and value flexibility, adding practical guidance beyond schema descriptions.

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

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

Clearly states verb 'save' and resource 'key-value pair', with specific context about reuse across conversations/sessions. Distinguishes from sibling tools recall and forget.

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

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

Explicitly says when to use ('when you discover something worth carrying forward') and how it pairs with recall/forget. Provides context on persistence (authenticated vs anonymous) and scoping.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds valuable behavioral context: internal cascading through multiple endpoints (replacing 2-3 manual lookups) and detailed return structure for each type (including citation URIs). 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 somewhat lengthy but well-structured: starts with example queries, states purpose, gives usage guidance, then details types. Every sentence adds value. Could be slightly more concise, but it is efficiently organized.

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

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

Fully explains what the tool returns for both supported types, including return fields and citation URIs. Also mentions internal complexity. With only 2 simple parameters and no output schema, the description provides all needed context for correct 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% with descriptions for both parameters. The description adds practical examples (AAPL, 0000320193, ozempic) and clarifies accepted input formats, which 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 clearly states the tool resolves spoken names to canonical identifiers, with concrete examples (ticker, CIK, RxCUI) and supported types. It distinguishes the tool's purpose from siblings by positioning it as the first step when an ID is needed, though no explicit sibling name is given.

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 'Use FIRST whenever you have a name but need an ID', providing clear when-to-use guidance. It does not explicitly mention when not to use or name alternatives, but the context makes it obvious that if an ID is already available, this tool is unnecessary.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds detail about probing each entity and returning ranked list with score, confidence, signal density, which provides useful behavioral context beyond annotations.

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

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

Two sentences, front-loaded with core function, then use case and output. No fluff, 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?

With 4 params, no output schema, and annotations present, the description covers the tool's operation (probes each entity), output structure (ranked list with fields), and usage context. Adequate for a comparative tool, though could mention internal calls to ai_visibility_check more explicitly.

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%, but the description adds contextual details: entities array first entry treated as subject, conditional API key requirement for Anthropic, and role of context parameter. This adds meaning beyond schema descriptions.

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

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

The description clearly states it compares AI visibility across multiple entities, probes each with ai_visibility_check, ranks by score, and surfaces most/least recognized. It differentiates from siblings like ai_visibility_check (single entity) and compare_entities (general comparison).

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

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

The description explicitly mentions usefulness for competitive AI-marketing audits and gives an example question. It implies distinction from single-entity probe (ai_visibility_check) but does not explicitly list when-not-to-use or other 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 provide readOnlyHint, idempotentHint, etc. The description adds valuable behavioral notes: bundlephobia's first measurement can take 5-30s, partial failures degrade gracefully, and sources_failed lists timeouts. 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 key information. Each sentence adds value, though some could be more concise. Structured well with use cases and edge cases noted.

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 complexity (composite check, two sources, potential delays), the description thoroughly covers returns (summary block, advisories, alternatives) and failure modes. Schema coverage is 100%, and no output schema needed as return values are described.

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

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

Schema covers both parameters with descriptions (package name with scoped packages, version with default to latest). The description adds context about scoped packages being accepted and version default behavior, providing slight value beyond schema.

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

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

The description clearly states the tool's purpose: a composite check for npm packages using deps.dev and bundlephobia. The verb 'scan' and resource 'dependency' are clearly defined, and the description distinguishes it from sibling tools by focusing on npm ecosystem and composite 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 states when to use: for questions like 'is X safe/popular/small' or 'what does adding lodash cost me'. Also specifies NPM only in v1 and mentions graceful degradation for partial failures, providing clear guidance.

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

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

Annotations already indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds critical behavioral details: uses BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation flag, and includes character offsets for verification.

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 concise with three well-structured sentences. Front-loads the primary purpose and key details. Every sentence adds value without redundancy.

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

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

Despite no output schema, the description explains return information (passages with offsets and scores). It covers the char cap and truncation behavior. Given the tool's complexity and sibling context, the description provides sufficient context for appropriate use.

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

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

Schema coverage is 100% but description adds valuable context: explains 'text' as document to search, provides examples for 'query', and clarifies 'limit' default and range. Also mentions output format (passages with offsets and scores) 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 states it performs semantic search inside a fetched record. It specifies the action (search) and the resource (text), and distinguishes from siblings like ask_pipeworx_grounded by explaining the pair workflow.

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 this tool: when the record is too large for the prompt. Provides context about saving context and returning only relevant passages. Also suggests pairing with ask_pipeworx_grounded. Could be improved by mentioning when not to use it.

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

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

The description adds significant behavioral context beyond annotations, including account requirements, type-specific filtering, delivery limits (10/day SMS), webhook behavior (signing secret, auto-disable after 10 failures), and that it returns a subscription id. 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 well-structured with groupings for types and delivery, but it is lengthy. However, each sentence adds value, and the main action 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?

Given the tool's complexity, the description is highly complete, covering prerequisites, all subscription types, parameter formats, delivery channels, return value, and important caveats (account requirement, SMS cap, webhook behavior). No output schema exists, but the description adequately describes the return.

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?

Despite 100% schema coverage, the description enriches parameter understanding with detailed examples for each type (e.g., sec_8k with item codes, polymarket_edge with topic) and clarifies delivery options (email, SMS, webhook) with specifics like phone verification and webhook signing.

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: 'Create a proactive monitoring subscription to a live-data event stream.' This is specific and distinguishes it from sibling tools like list_subscriptions, unsubscribe, 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?

The description provides clear usage context, such as the requirement for a Pipeworx OAuth account, supported subscription types, and delivery channel options. However, it does not explicitly guide when to use this tool over alternatives, though the context is sufficient for correct selection.

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

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

Annotations already indicate read-only, idempotent, and open-world hints. The description adds that the tool returns category-bucketed example questions with exact tool+argument shapes from a live catalog. This significantly enhances the agent's understanding of what to expect 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 well-structured, starting with synonyms/phrases that users might say, then stating the purpose, and ending with usage guidance. It is slightly lengthy but each sentence serves a purpose. The front-loading of user phrases is effective for matching queries.

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 fully explains what the tool returns (category-bucketed example questions with tool+argument shape) and covers all necessary context: when to use it, how to focus it, and what it draws from. It is complete for an onboarding 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?

With schema coverage at 100%, the baseline is 3. The description adds value by listing example values for the topic parameter ('finance', 'pharma', 'betting') and clarifying that omitting it returns a cross-category spread. This goes beyond the schema's minimal 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's purpose as the onboarding entry point for new agents to discover what Pipeworx can do. It uses specific verbs like 'suggest' and 'return' and distinguishes itself from siblings by being positioned as the first tool to use when you don't know what Pipeworx 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?

The description provides explicit guidance on when to use the tool ('Use this FIRST when you do not yet know what Pipeworx can do for you') and explains that it can be called with or without the topic argument. It could be improved by contrasting with similar tools like 'discover_tools' or 'ask_pipeworx' to clarify when not to use it.

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

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

Adds critical behavior beyond annotations: ownership enforcement, deactivation instead of deletion, and availability of historical events via recent_alerts. No contradictions.

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

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

Two concise sentences with no fluff; efficiently conveys all necessary 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?

Fully covers input, behavior, side effects, and relationship to sibling tools. Appropriate for a simple single-parameter tool with 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 covers 100% of parameters; description adds no additional meaning to the 'id' parameter beyond what schema already provides.

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

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

Clearly states the verb 'Cancel' and resource 'subscription by id'. Distinguishes from sibling 'subscribe' and notes relation to '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?

Explicitly states ownership enforcement limiting usage to own subscriptions. Implicitly guides against canceling others' subscriptions but lacks explicit alternatives for deletion.

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, etc.), the description details the return format: verdict, structured form, actual value with citation, and percent delta. It also notes limitations (v1 supports only US public company financial claims). 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 moderately long but front-loaded with purpose and examples. Every sentence provides value, though some redundancy could be trimmed. It remains well-structured and 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 a simple input schema (1 param, no output schema), the description fully explains behavior, return values, domain, and usage scenarios. Annotations cover read-only and idempotent aspects. No gaps.

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

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

The single parameter 'claim' has a schema description, and the tool description adds rich context with example phrasings and domain specification. Schema coverage is 100%, so baseline is 3; the description elevates it by clarifying the expected natural-language input.

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 validates natural-language claims against authoritative sources, specifically company-financial claims via SEC EDGAR + XBRL. It provides example phrasings and distinguishes itself from siblings by being a dedicated claim verification 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?

Explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and gives natural-language examples. It also mentions replacing multiple sequential calls, but does not explicitly state when not to use it or list alternatives for non-financial claims.

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