Housing Intel

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

Annotations already indicate readonly, open world, idempotent, non-destructive. Description adds value by detailing return structure (per-model {score, confidence, signals, raw_response} + combined view) and cost note for Anthropic API key. No contradictions.

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

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

Three sentences, each purposeful. Front-loaded with purpose, then details. No wasted words. Highly concise and well-structured.

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

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

Despite no output schema, description fully explains return structure and parameter behavior. Covers all 4 parameters, provides examples, and addresses optional configurations. Complete for a probe tool with good annotations.

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

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

Schema has 100% description coverage with clear descriptions for all 4 parameters. Description reinforces and expands: entity examples, default model behavior, API key requirement only when needed, context disambiguation purpose. Adds meaning 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 probes LLMs to score visibility (0-100) per model, with specific verb 'probe' and resource 'LLMs'. It differentiates itself from sibling tools (e.g., housing, betting) by focusing on AI marketing audits and brand checks.

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 mentions use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring'. Default model and optional Anthropic (with BYO key) are explained. Lacks explicit when-not-to-use or contrast with alternatives, but context is clear.

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

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

With no annotations provided, the description carries full burden for behavioral disclosure. It clearly states the tool picks the right tool and fills arguments, implying it makes decisions autonomously. It does not disclose limits (e.g., if no data source can answer) or potential latency, but for a query tool the key behavior (auto-routing) is well-described.

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, each adding value: purpose, behavior, examples. It is front-loaded with the core action. The examples earn their place by illustrating scope. Minor improvement: could be slightly tighter (e.g., combine first two sentences), but overall efficient.

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

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

Given the tool's simplicity (single parameter, no output schema), the description is nearly complete. It covers purpose, usage, and input format. It could mention that the tool may invoke other tools (implicit from 'picks the right tool') but does not explain error handling or response format. For a query tool, this is acceptable.

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

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

Schema coverage is 100%, so baseline is 3. The description adds significant meaning: it explains that the parameter 'question' should be a natural language request, not a structured query. It provides examples that illustrate acceptable input formats, going beyond the schema's minimal 'Your question or request in natural language'.

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

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

The description uses a clear verb+resource pattern: 'Ask a question... get an answer from the best available data source.' It explains the tool's role as an intelligent router, which distinguishes it from siblings like discover_tools (which lists tools) or housing_* tools (which are domain-specific).

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

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

The description provides explicit guidance on when to use: 'No need to browse tools or learn schemas — just describe what you need.' It gives concrete examples ('What is the US trade deficit with China?'), implicitly distinguishing from direct tool calls. The context signals show many sibling tools are housing-specific, so this tool is the general-purpose question-answering alternative.

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

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

Annotations already show readOnly, openWorld, non-destructive. The description adds behavioral specifics: fan-out to packs, classification, evidence packet generation. No contradictions. It provides useful 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 a single dense paragraph but well-structured: purpose, inputs, process, use cases. Could be more concise but front-loads key info.

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

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

Given no output schema, description explains return value (evidence packet + model comparison). For a core demo tool, it covers inputs, process, and outputs. Missing error handling details but sufficient for typical use.

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

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

Schema coverage is 100%. Description reinforces depth parameter meanings (quick=2-3 sources, thorough=full) and default. For market, description clarifies accepted formats beyond schema. Adds value over 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 it researches a Polymarket bet by pulling Pipeworx data. It specifies inputs (slug, URL, question text) and outputs (evidence packet + comparison). Differentiates from siblings like ask_pipeworx or validate_claim by focusing exclusively on Polymarket bets.

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

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

The description gives explicit use cases ('should I bet on X?', 'what does the data say?', 'is there edge?') and notes it is the core demo product. However, it does not explicitly state when not to use it or compare to alternatives like ask_pipeworx.

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

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

Discloses return fields: latest level, 3-month change, 12-month change, all-time peak, drawdown from peak, softening flag, and ranking. Also explains automatic series ID selection. Annotations (readOnlyHint=true) are consistent, but description adds significant behavioral context beyond that.

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

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

Description is moderately long but well-structured: starts with main purpose, then outputs, usage hints, and metro list. Every sentence provides value, though could be slightly more 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?

No output schema, so description fully covers return values and behavior. It also details the automatic series ID mapping and lists all 20 metro options. Given the tool's complexity (comparing multiple indices), the description is complete.

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

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

Schema coverage is 100%, so baseline is 3. Description adds value by listing available metros (Atlanta, Boston, ...), noting case-insensitivity, and providing usage examples. Does not elaborate on _fredKey beyond schema, but that is acceptable.

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 compares Case-Shiller home price indices across multiple US metros. It specifies the verb 'compare', the resource 'Case-Shiller home price indices', and the scope 'the 20-city composite'. This distinguishes it from sibling housing tools like 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?

Provides explicit usage examples: 'Use for "which metros are softening"...' Also notes that it automatically picks the right FRED series IDs, reducing caller burden. Lacks explicit when-not-to-use instructions but 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?

No annotations provided, so description carries burden. It explains outputs but does not mention side effects, rate limits, or authentication needs. Adequate but not thorough.

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, front-loaded with purpose, no redundancy. Every sentence adds essential information.

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

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

Covers all aspects: purpose, parameters, return data, and output format (paired data + URIs). No output schema but description compensates 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 coverage is 100%, baseline 3. Description adds value by giving concrete examples and explaining what data each type returns, exceeding schema clarity.

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 2-5 entities side by side, specifies two entity types with distinct data fields, and positions itself as an efficiency tool replacing 8-15 sequential calls.

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

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

Describes when to use (comparing entities efficiently) and implies avoiding when individual data needed, but lacks explicit when-not-to-use or alternatives like resolve_entity.

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?

No annotations are provided, so the description carries the full burden. It mentions 'Returns the most relevant tools with names and descriptions', which is basic. However, it does not disclose search semantics (e.g., whether it uses semantic search or keyword matching), pagination behavior, or any side effects. A score of 3 is appropriate as it adds some value but lacks rich behavioral detail.

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

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

Three sentences with no wasted words. Each sentence serves a purpose: stating what the tool does, what it returns, and when to use it. Efficient 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?

Given the tool's simplicity (search with 2 params, no output schema), the description is sufficiently complete. It explains purpose, usage, and behavior. Minor gap: it does not mention how results are ordered (relevance?) or what happens on no results, but overall adequate.

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

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

Schema coverage is 100%, with both parameters already described in the schema. The description adds a natural language example for 'query' and mentions default/max for 'limit', which is helpful but does not add significant new meaning beyond the schema.

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

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

The description clearly states 'Search the Pipeworx tool catalog' and 'returns the most relevant tools with names and descriptions', with a specific verb and resource. It distinguishes from siblings by being the only search tool for the tool catalog, while sibling tools are domain-specific housing tools or memory operations.

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

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

Explicitly says 'Call this FIRST when you have 500+ tools available and need to find the right ones for your task', providing clear when-to-use guidance. Also implies it's for discovery before using other tools, differentiating from sibling tools which are for specific tasks.

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?

With no annotations, the description carries the full burden. It explains the bundling behavior, return format (pipeworx:// URIs), and performance implication (too slow to include federal contracts). Could be improved by explicitly stating it's a read-only operation, but still provides good context.

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

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

Four sentences, each serving a clear purpose: purpose statement, content list, return format, usage guidance. No redundancy, well 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 no output schema and no annotations, the description covers the tool's purpose, bundled data sources, return format, and a key exclusion (federal contracts). It lacks details about data freshness or error scenarios but is mostly complete for a profile tool.

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

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

Schema coverage is 100% with detailed descriptions for both parameters (type enum and value format). The description adds no extra semantic value beyond the schema, meeting the baseline adequacy.

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 states it provides a full entity profile bundling multiple data sources in one call, listing specific data types (SEC filings, XBRL, patents, news, LEI). It distinguishes from sibling tools like compare_entities and resolve_entity by its aggregative nature.

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 (instead of 10-15 sequential calls) and when not to (for federal contracts, recommending usa_recipient_profile). Also implicitly suggests using resolve_entity first if only a name is available, based on parameter description.

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?

No annotations exist, so the description must carry the full burden. It states the action is deletion (destructive), which is clear. However, it doesn't disclose side effects (e.g., whether deletion is permanent, if cascading deletion occurs, or any authorization requirements).

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 sentence with 5 words, no filler, and immediately conveys the core action. It is front-loaded and earns its place.

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

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

Given the tool's simplicity (1 required param, no output schema, no annotations), the description is adequate but minimal. It lacks context on return value or error conditions, which could be helpful for a delete operation.

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

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

Schema coverage is 100% with one parameter 'key' described as 'Memory key to delete'. The description adds no further detail beyond the schema, but since coverage is high, the baseline is 3; the description is concise and aligned, earning a 4 for clarity.

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

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

The description uses a clear verb ('Delete') and resource ('stored memory by key'), exactly matching the tool name 'forget'. It distinguishes from siblings like 'remember' (create) and 'recall' (retrieve).

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

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

The description implies when to use (when you want to delete a memory) but does not specify when not to use or provide alternatives. For example, no guidance on whether the key must exist or what happens if it doesn't.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral details: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format'. It explains the action flow, which is 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?

The description is two sentences plus a bullet list of use cases. It is front-loaded with the main purpose and succinctly covers key points without 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?

For a tool with two simple parameters and no output schema, the description covers the main workflow: fetch, extract, output. It mentions the output is a single text blob ready for site-root/llms.txt. It does not detail the exact markdown format, but that is standard. Overall, it is sufficiently complete for this tool's complexity.

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

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

Schema coverage is 100% with clear descriptions. The description does not add new semantic context about the parameters beyond what the schema provides. For example, 'max_links' is described in schema as 'Maximum number of link entries to include (default 25, max 50).' The description mentions extracting 'key links' but doesn't tie it to the parameter. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Generate a production-ready llms.txt file for any URL'. It specifies a specific verb ('generate') and resource ('llms.txt file'), and the context of AI crawlers. This distinguishes it from sibling tools, which cover different domains like housing or betting research.

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

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

The description provides explicit use cases: indexing a client's site, drafting for own project, or auditing competitor. This context helps the agent decide when to use it. However, it does not explicitly mention when not to use it or alternative tools, but given the sibling list is diverse, this is acceptable.

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

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

Annotations are empty, so the description carries full burden. It transparently lists all data sources and conditions (national vs. metro-level, optional API keys). 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 a single sentence listing multiple metrics, which is efficient. It front-loads the purpose. Slightly long due to enumeration but earns its length.

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

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

Given the moderate complexity (5 parameters, no output schema), the description covers the key outputs and optional inputs. It could mention that _hudKey is optional, but that is already in the schema. Overall adequate.

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

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

Schema description coverage is 100%, so the schema already describes each parameter. The description adds context by grouping outputs (e.g., 'metro-level FHFA HPI if metro_name provided') but does not add new meaning beyond the schema.

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

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

The description uses specific verbs ('Check') and lists concrete resources (mortgage rate, median home price, HPI, earnings, payment, income limits). It clearly distinguishes itself from sibling tools like housing_market_snapshot or housing_rental_analysis by enumerating the metrics covered.

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

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

The description implies usage by listing what metrics are returned and conditionally mentions metro_name for HPI. However, it does not explicitly state when not to use this tool or suggest alternatives among siblings.

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

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

With no annotations, the description carries full burden. It states the tool uses BLS data (no key needed), which is helpful. However, it does not disclose any limitations (e.g., data frequency, delay, or what happens if no data found). A neutral score is appropriate as it adds some context but misses behavioral specifics.

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

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

The description is two sentences, front-loaded with key information. It efficiently lists indicators and data source. No wasted words, but could benefit from a brief note on what the tool returns.

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 no output schema and is relatively simple, the description provides enough context for an agent to understand its inputs and data source. However, it lacks information on output format or how to interpret results, leaving some ambiguity.

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

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

The schema covers the only parameter (_fredKey) with full description, so baseline is 3. The description adds context that FRED key is accepted but not used because BLS is free, which explains the parameter's presence and behavior. This is adequate but not exceptional.

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

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

The description clearly states it provides labor market indicators relevant to housing, listing specific metrics and the data source. It distinguishes from siblings like housing_market_snapshot (broader market data) and housing_signal_scan (signals), but could be more precise about its distinct purpose.

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 it should be used for obtaining labor market context for housing analysis, but does not explicitly state when to use it vs. alternatives. No exclusion criteria or sibling comparisons are provided, leaving the agent to infer usage context.

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

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

The description discloses that the tool combines data from two sources (FRED and BLS) and notes a key difference in authentication key naming compared to the standalone attom pack. Since annotations are empty, the description carries full burden, and it provides useful behavioral context without 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 moderately concise, front-loading the main purpose. It contains a few sentences that could be tightened (e.g., the note about _attomKey), but overall it efficiently conveys the key information without being verbose.

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

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

Given the tool's moderate complexity (2 params, no output schema), the description covers the inputs well and explains the data sources. It lacks details on output format or return values, but without an output schema, the description is still fairly complete for an agent to understand what the tool does.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by explaining the effect of metro_name (triggers FHFA HPI) and that metro_name supports top 50 US metros. This goes beyond the schema's generic 'Metro area name' 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 verb 'Get' and the resource 'national housing market snapshot', listing specific data points included. It distinguishes from siblings by mentioning that it combines FRED and BLS data, and contrasts with other tools like housing_affordability_check.

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

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

The description explains that when metro_name is provided, additional metro-level HPI is included, and that national data is always included. It does not explicitly say when not to use this tool or name alternatives, but the context of sibling tools implies distinct use cases.

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

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

No annotations exist, so the description carries full burden. It discloses the meta-pack nature and key naming convention, but does not mention that it aggregates multiple API calls (performance implications), rate limits, or whether data is real-time vs cached. Annotations would have helped here.

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 and front-loads the purpose. The note about _attomKey is a concise, valuable caveat. Could be slightly more concise by removing the example URL, but overall efficient.

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

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

Given the tool has 3 required parameters, no output schema, and no annotations, the description adequately explains the tool's purpose and a critical usage detail. However, it lacks information about what the output contains, which would help agents decide if the response meets their needs. The schema covers all parameters, so the description meets minimum viability but has room for improvement.

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

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

The input schema already has 100% coverage with descriptions for each parameter. The description adds no additional parameter semantics beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states the tool provides 'complete property analysis combining ATTOM data' and lists specific data types (property details, AVM, sales history, tax assessment). This distinguishes it from siblings like housing_market_snapshot or housing_affordability_check, 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 implies use when a comprehensive property report is needed, and the note about _attomKey vs _apiKey provides important usage context. However, it does not explicitly state when to use alternatives (e.g., if only a specific data type is needed) or when not to use this tool.

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

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

No annotations exist, so the description must disclose behavioral traits. It correctly notes that the HUD key is optional and that ATTOM uses a different key parameter. However, it does not mention any side effects, rate limits, or whether the tool modifies data.

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 sentence with a brief parenthetical note, effectively conveying the core functionality without redundancy. It is 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 moderate complexity (5 parameters, no output schema), the description covers the main data sources but omits details like return format, error conditions, or typical response structure. The schema is well-documented, but the description could be more complete.

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

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

Schema coverage is 100%, so the schema already describes all parameters. The description adds value by explaining the purpose of _hudKey (optional) and _attomKey (for ATTOM), and by noting that state_code is used for HUD FMR lookup. This matches the 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 states the tool provides rental market analysis including estimated rent, fair market rents, and CPI rent trends, clearly identifying the data sources (ATTOM, HUD, BLS). However, it does not differentiate itself from siblings like housing_market_snapshot or housing_affordability_check, which might overlap in purpose.

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 mentions that HUD data requires a key and that ATTOM uses a specific parameter (_attomKey), but provides no guidance on when to use this tool vs. alternatives. There is no explicit when-not-to-use or comparison to siblings.

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

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

Annotations are empty, so description carries full burden. It discloses that the tool checks 45+ indicators and returns flagged anomalies, which is moderately transparent. However, it doesn't mention latency, rate limits, or what happens on API failure (e.g., if _fredKey is invalid). 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 concise and front-loaded with the core purpose. It lists covered indicators efficiently. One minor issue: the list of indicators could be slightly shortened or referenced, but overall it's well-structured.

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

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

Given the tool has only one required parameter and no output schema, the description adequately explains the scope (45+ indicators, categories) and the output nature ('returns flagged anomalies'). It is complete enough for an agent to decide to invoke it for anomaly detection in housing data.

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 the single parameter _fredKey, which is described as 'FRED API key'. The description adds no further parameter info, so baseline 3 applies. The description mentions coverage of indicators but does not elaborate on parameter usage or formats.

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 'comprehensive housing market signal scan' covering 45+ indicators, lists specific categories, and says it 'returns flagged anomalies'. This is specific verb+resource, and it distinguishes itself from sibling tools like housing_market_snapshot which likely provide a snapshot without anomaly detection.

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

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

The description implies use for detecting market signals or anomalies, but provides no explicit guidance on when to use this vs. alternatives like housing_affordability_check or housing_market_snapshot. No exclusions or when-not-to-use are mentioned.

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

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

No annotations provided, so description carries full burden. It discloses rate limiting and that the tool is free. Missing details about whether feedback is private or visible to team, or if confirmation is returned. Still strong.

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 compact sentences front-load purpose and usage, then add constraints (rate limit). Every sentence essential, 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?

Despite having nested objects and no output schema, description covers purpose, input format, usage constraints, and behavioral traits. Agent can confidently select and invoke this tool.

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

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

Schema coverage is 100% with good parameter descriptions. Description adds extra usage guideline for message (no verbatim prompt), which provides value beyond schema. Context parameter is optional and explained well.

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 explicitly states the tool sends feedback to Pipeworx team, enumerates specific use cases (bug reports, feature requests, missing data, praise), and distinguishes from sibling tools which perform data retrieval or 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?

Clearly instructs when to use (feedback) and how to phrase the message (describe tools/data used, omit end-user prompt). Also mentions rate limit of 5 messages per day per identifier, guiding usage frequency.

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

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

Adds value beyond annotations by detailing caching behavior (5min-1h), data source (CF analytics-engine), aggregation method (no PII), and self-aggregating nature. 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?

Three efficient sentences with front-loaded purpose. No fluff; every clause adds information (use cases, caching, privacy, window semantics).

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 parameterless (optional window) tool with no output schema. Covers return value (top tools, packs, call volume), caching, use cases, and privacy.

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 3. Description adds semantic guidance ('shorter windows for hot items, longer for steady-state'), improving beyond 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 returns top tools, packs, and call volume over recent windows, with specific use cases. It distinguishes itself from siblings like discover_tools and ai_visibility_check.

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

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

Explicitly lists three distinct use cases (discovering hot data sources, confirming canonical choices, aligning use cases) with context on when each window size is appropriate.

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

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

Beyond annotations (readOnlyHint, destructiveHint), the description details the tool's behavior: walks child markets, searches across events, groups them, checks monotonicity, and returns ranked opportunities with trade direction and reasoning. This fully discloses behavioral traits.

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 succinct (several sentences) and well-structured with bold labels for modes. Every sentence adds value, avoiding fluff while conveying 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?

Given no output schema, the description sufficiently describes return values (ranked opportunities with trade direction+reasoning). For a tool with moderate complexity, this covers inputs, modes, and output summary completely.

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

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

With 100% input schema coverage, the description adds significant meaning: explains the two modes, provides examples for both 'event' (slug or URL) and 'topic' (seed question with illustration), clarifying parameter use 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 the tool finds arbitrage opportunities by checking monotonicity violations. It distinguishes two modes ('event' and 'topic'), specifying the resource (Polymarket, related markets) and action (checking ordering), making purpose unambiguous.

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

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

The description provides explicit guidelines for when to use each mode: 'event' for single event, 'topic' for cross-event scenarios. It explains why cross-event mode is necessary for cases where events are separate, but does not explicitly compare to 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 provide readOnlyHint, openWorldHint, destructiveHint. Description adds V1 details: lognormal model from FRED + live coinpaprika, scanning and grouping, computing model probability, ranking by |edge|, and suggesting direction. 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 dense but well-structured, front-loading purpose and process. Could be slightly shorter but 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?

Despite no output schema, description adequately explains return value (top N ranked by edge magnitude with suggested trade direction). Parameters fully described, annotations cover safety, process clear.

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

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

Schema coverage is 100% with descriptions. Description adds default values (10, 1wk, 0.5) and clarifies meaning 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 scans high-volume Polymarket markets, finds where Pipeworx data disagrees with market price, and returns top edges with suggested trade direction. It is specific and distinct from siblings like polymarket_arbitrage.

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

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

The description explicitly states it's built for the 'what should I bet on today' question, but does not provide explicit when-not-to-use scenarios or alternatives among siblings.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds value by detailing return values (leg-by-leg prices and spread) and typical spread range (2-25pp). It does not contradict annotations and provides useful behavioral context beyond what annotations alone convey.

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

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

The description is moderately concise, effectively front-loaded with the core purpose. It contains several sentences, but each adds necessary detail about modes, usage, and output. Minor room for trimming, but overall efficient and well-structured.

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

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

Given the lack of an output schema, the description fully explains the return format: leg-by-leg prices in raw probability and spread in percentage points. It covers both modes, parameter interactions, and expected outcomes. For a tool with three optional parameters, the description is thorough and leaves no critical gaps.

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

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

Schema has 100% coverage with descriptions for all three parameters. The description enhances meaning by explaining the two modes, clarifying that topic provides pre-mapped shortcuts, and that explicit parameters override topics. It also gives format examples (e.g., 'KXFED-26OCT'), adding practical value beyond the schema.

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

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

The description clearly states the tool's function: cross-venue spread between Kalshi and Polymarket for the same resolving question. It specifies two distinct modes (topic shortcuts and explicit pairing), which differentiates it from sibling tools like polymarket_arbitrage and polymarket_edges. The verb and resource are unambiguous.

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

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

The description explains when to use the tool: to capture arb signals due to price differences between venues. It details the two modes (topic and explicit custom pairings). However, it does not explicitly mention when not to use it or provide direct alternatives, though the context of siblings (e.g., polymarket_arbitrage) implicitly suggests different use cases.

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

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

No annotations provided, so description carries full burden. Description correctly states it is a retrieval operation (no side effects implied). Lacks details on behavior when key not found, or performance with many memories. Minimal but sufficient for a simple read tool.

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, clear and front-loaded with main action. Every sentence adds value: first explains functionality, second gives usage context. No wasted words.

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

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

Given simple tool with 1 optional parameter, description covers core behavior. Could mention return format (e.g., string or object) but not essential. Adequate for agent to use correctly.

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

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

Schema coverage is 100%, with description for 'key' in schema. Description adds nuance: 'omit to list all keys' clarifies behavior. No extra semantics beyond schema, but adequate since schema already documents parameter.

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

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

Description clearly states it retrieves a memory by key or lists all memories, with verb 'Retrieve' and resource 'stored memory'. Distinguishes from sibling 'remember' (store) and 'forget' (delete). Slightly less precise because it doesn't specify if 'omit key' means empty or absent key.

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

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

States when to use: 'to retrieve context you saved earlier'. Implicitly suggests not for storing (use 'remember') or deleting (use 'forget'). Could be more explicit about alternatives, but context signals show clear siblings.

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

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

No annotations provided, but description discloses parallel fan-out to three sources, date formats accepted, and return structure (changes, count, URIs). Lacks error/absence handling, but otherwise transparent.

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

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

Concise, well-structured, front-loaded with purpose. Every sentence adds value; 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?

No output schema, but description sufficiently explains return type (structured changes, count, URIs). Contextual signals indicate 3 required params; description covers all aspects needed for selection and invocation.

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

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

Schema coverage is 100%, baseline 3. Description adds value by explaining `since` accepts both ISO and relative formats with examples, and clarifies that `value` can be ticker or CIK, going 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 'What's new about an entity since a given point in time' with specific verb+resource, and distinguishes from sibling tools by detailing the multi-source data retrieval (SEC EDGAR, GDELT, USPTO).

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 usage guidance: 'Use for 'brief me on what happened with X' or change-monitoring workflows.' No explicit when-not or alternatives, but sibling tools are sufficiently differentiated.

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

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

No annotations provided, so description must carry the burden. It discloses persistence behavior (persistent vs 24-hour) but does not mention any side effects, storage limits, overwrite behavior, or privacy implications. Adequate but not comprehensive.

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, front-loaded with purpose, then usage context. No unnecessary words.

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

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

Given simple key-value storage with no output schema and no nested objects, the description covers essential aspects: what, why, and persistence nuance. Minor gaps in storage limits or overwrite behavior, but overall complete for this tool's complexity.

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

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

Input schema has 100% coverage with descriptions for both parameters. Description adds context about the purpose of storing (findings, preferences, notes) but does not add significant meaning beyond the schema. Baseline 3 applies.

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

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

Description clearly states verb ('Store'), resource ('key-value pair in session memory'), and purpose ('save intermediate findings, user preferences, or context across tool calls'). Distinguishes from siblings like 'forget' and 'recall' by explicitly mentioning memory storage.

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?

Describes when to use (save context across calls) and mentions persistence behavior for authenticated vs anonymous sessions. Does not explicitly exclude alternatives or state when not to use, but the context is clear enough.

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

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

Describes inputs and outputs but does not disclose read-only behavior, auth needs, or rate limits. Since no annotations exist, description partially covers behavioral aspects.

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?

Extremely concise with two sentences, front-loaded with purpose and key details, 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?

Covers all necessary aspects for a simple lookup tool: what it does, accepted inputs, and returned outputs. Could mention behavior on ambiguous matches but overall complete.

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

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

Schema coverage is 100%, so baseline is 3. Adds value by providing examples (ticker, CIK, name) and explaining the accepted formats, going 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?

Clearly states it resolves entities to canonical IDs, specifies v1 supports companies, and mentions it replaces 2-3 lookup calls, distinguishing it from sibling tools.

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

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

Provides clear context for when to use (when resolving company entities) but does not explicitly state when not to use or mention alternatives among siblings, though differentiation is clear.

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

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

The description adds behavioral context beyond annotations: it mentions probing each entity with ai_visibility_check, ranking, and output details (score, confidence, signal density). Annotations already indicate read-only and idempotent, which are consistent.

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

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

The description is two sentences, front-loaded with the core purpose, and includes an illustrative example. It is concise but could be slightly tighter (the example question adds length).

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

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

Given no output schema, the description adequately describes the output (ranked list with score, confidence, signal density). It covers the tool's operation and results, though lacks details on score ranges or significance.

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 extra meaning: 'First entry treated as the "subject" for narrative; rest are competitors', which is not in the schema. This enhances understanding.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, using ai_visibility_check, ranks by score, and surfaces most/least recognized. This is specific and distinct from siblings like ai_visibility_check (single entity) and compare_entities (different comparison).

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

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

The description explicitly says 'Useful for competitive AI-marketing audits' and gives an example question, indicating when to use. It does not explicitly mention when not to use or alternatives, but the context is clear enough.

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

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

No annotations provided, so description carries full burden. Discloses internal steps (NL parsing, entity resolution, data lookup, comparison) and output structure (verdict, extracted form, actual value with citation, percent delta). Lacks mention of error handling or limitations (e.g., only US companies, specific metrics).

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 states purpose and scope, second details return value and efficiency benefit. No redundant words, 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?

With no output schema, description adequately explains return values (verdict, extracted form, actual value, citation, percent delta). Covers supported claim types and sources, but omits error handling or limitations. Sufficient for a 1-parameter tool with high schema coverage.

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

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

Schema description coverage is 100% with parameter 'claim' described. Description adds value by explaining claim types (company-financial) and the fact-checking process, beyond the schema. Provides examples in both schema and 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 verb 'fact-check' and the resource 'natural-language claim' against authoritative sources. It specifies scope: company-financial claims (revenue, net income, cash) for public US companies via SEC EDGAR + XBRL. This differentiates it from sibling tools like 'ask_pipeworx' or '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?

Explicitly states it replaces 4–6 sequential agent calls, implying when to use it for efficiency. Implicitly restricts usage to company-financial claims for US public companies via SEC EDGAR. Does not provide explicit when-not-to-use or list alternatives, but context is clear.

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