agentery

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

With no annotations provided, the description carries the full burden of behavioral transparency. It thoroughly explains resolution behavior (exact match only, no fuzzy replacement), error handling (unresolved_inputs, corrected_call, recovery with compared_with_market_peers), mixed provider types, and the structure of the response (evidence-scored cards, how_to_connect, reported_success). This level of detail is exemplary.

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

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

The description is front-loaded with the main purpose but becomes verbose with technical details about edge cases. While every sentence adds value, it could be more concise. It scores 3 for being adequate but not optimally efficient.

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

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

Given the tool's complexity and the absence of an output schema, the description is remarkably complete. It covers return structure (cards, evidence, success metrics), error recovery scenarios, and post-usage actions (report outcome). It also mentions inline suggested_alternatives, ensuring the agent has all necessary context to invoke the tool correctly.

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

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

Although the schema covers the agent_ids parameter with 100% description coverage, the description adds significant meaning: it clarifies that agent_ids are aliases for handles or IDs, accepts a comma-separated string, and enforces a 2-6 count. It also explains that inputs are resolved to real providers, adding important context beyond the schema.

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

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

The description clearly states the tool's purpose: 'Call this to decide between shortlisted agents.' It specifies the verb (compare/decide) and resource (agents), and implicitly distinguishes from sibling tools like search_agents and research_capability by indicating it is used after 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?

The description explicitly advises using this tool 'after search_agents or research_capability' and mentions that inline suggested_alternatives are returned when a compared provider is over budget or weakly matched. It provides clear context for when to use, though it does not explicitly state when not to use.

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

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

No annotations provided, so description carries full burden. Explains output is ranked and empty args work, but omits details like data freshness, response format, or error handling. Adequate but not thorough for a tool without 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 with no fluff. First sentence defines purpose, second adds context and pairing advice, third clarifies default behavior. Front-loaded and efficient.

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

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

Covers purpose and usage well, but lacks output structure description since no output schema exists. Missing details on returned fields or pagination. Adequate for a simple tool but not fully complete.

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

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

Schema coverage is 100% with one parameter described. Description adds minimal value by confirming empty args behavior. Baseline 3 is appropriate as no significant extra meaning is added.

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 returns 'capability queries that returned ZERO results' ranked by miss count, using specific verbs like 'see' and 'aggregated'. It distinguishes itself from siblings like search_agents by focusing on nonexistent agents.

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 ('to see unmet-demand signals') and suggests pairing with niche_report/market_gaps. Lacks explicit exclusions or alternative selection guidance, but provides clear 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It extensively details the matching process, confidence levels, pricing evidence ladder, exclusion criteria, and conditional behavior (withholding pricing when uncertain). It also declares read-only status at the end. This is highly transparent.

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

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

The description is somewhat lengthy but every sentence adds value. It is well-structured, starting with the primary purpose, then detailing return fields and pricing ladder, and ending with guidance on alternatives. While not extremely concise, it is appropriately detailed for the tool's complexity.

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

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

Given the tool has only 2 parameters and no output schema, the description is remarkably complete. It explains all return fields in depth, including match_certainty, niche details, alternatives, pricing status with an evidence ladder, pricing_coverage, and adjacent_pricing. It also references sibling tools, providing full context for usage.

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

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

Schema coverage is 100%, but the description adds significant meaning beyond the schema. It explains that 'query' is an alias for 'task' for backward compatibility, provides example values ('reconcile supplier invoices'), and mentions that pricing-intent boilerplate is stripped before matching. This enriches the parameter understanding.

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

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

The description clearly states the tool's purpose: to map a natural-language task to a canonical Agentery niche for buyers, sellers, or classification. It uses specific verbs ('map') and resources ('canonical Agentery niche'), and distinguishes from sibling tools like research_capability and niche_report by mentioning alternatives.

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 vs alternatives. It suggests using research_capability for a full market read plus pricing and provider shortlist in one call, and mentions following suggested_next_call to niche_report for the full market read. This helps the agent decide between 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?

No annotations provided, so description carries full burden. Discloses return fields but does not mention read-only nature, error handling, parameter requirements (at least one needed), or rate limits.

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 sentence, no redundant information, front-loaded with purpose. Highly efficient.

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

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

Covers tool purpose and return fields adequately given no output schema or annotations. Minor omission is not explicitly stating parameter mutual exclusivity or read-only behavior, but acceptable for a simple retrieval tool.

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

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

Schema coverage 100% (baseline 3). Description adds value by explaining parameters as identification methods and confirming they are alternatives, with examples implicitly matching schema.

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

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

Clearly states the tool retrieves a public directory card for a single agent by handle or registration number, listing specific fields returned. Distinguishes from siblings like 'search_agents' (multiple agents) and 'get_agent_profile' (different view).

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 'call this for the public directory card of one agent', implying usage context. However, does not explicitly exclude alternatives or mention when not to use, though sibling names provide indirect 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?

No annotations provided, so description carries full burden. Describes fields comprehensively, including null behavior for vendor endpoints and reported_success calculation. No mention of auth or side effects, but for a read operation this is sufficient.

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

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

Description is detailed but slightly verbose. It packs useful information but could be more concise. Still, it is 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?

No output schema, so description must cover return value. It thoroughly describes all fields including trust signals, integration details, and usage instructions. 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?

Only one parameter (agent_id) with schema description covering 100%. The description reinforces its use but does not add extra semantics 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 specifies the tool's purpose: 'drill into ONE agent after search_agents or compare_agents: full evidence-scored profile'. It distinguishes from siblings by stating it provides detailed profile information for a single agent, contrasting with search/compare tools.

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

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

Explicitly states when to use: 'after search_agents or compare_agents'. Also advises to 'call report_outcome afterwards' after using the listing. No explicit 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?

With no annotations provided, the description fully discloses behavioral traits: it is an index level, not a market price or tradeable asset. It explains that when data is thin, it returns honest statuses (insufficient_comparables, etc.) instead of fabricated percentages, and that it never substitutes another cohort. It also states it reads the same canonical series as the website, ensuring 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 a single paragraph of moderate length. It is packed with essential information without unnecessary words. While it could benefit from bullet points for scopes, it remains clear and every sentence contributes meaning. It is not overly verbose.

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

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

The description is comprehensive given the tool's complexity (multiple scopes, response modes, tier filtering, niche resolver). It outlines returned fields for each scope, explains status handling, and confirms consistency with the website. No output schema exists, but the description adequately covers return values.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by explaining how the niche resolver works (natural-language task) and what the 'full' response_mode adds (exact sub-0.01% moves, per-tier detail, repricing counts). This extra context improves parameter understanding 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 returns the current level of the Agent Economy Price Index or a niche's price index. It distinguishes between 'aepi' and 'niche' scopes, and provides specific details about returned fields. The verb 'call this for the CURRENT level' is precise and distinguishes it from sibling tools like get_price_index_history.

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

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

The description explicitly says 'Call this for the CURRENT level', indicating when to use it. It explains the two scopes and what each returns. While it doesn't explicitly state when not to use it or list alternatives, the context of the sibling tools implies usage boundaries, and the description is clear enough for 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?

With no annotations, the description carries full burden. It discloses output is index levels (base 100), not prices, explains response includes window change and gap flags, and returns honest status when data insufficient. It does not explicitly state read-only but implies it.

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

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

Well-structured and front-loaded with core purpose. Each sentence adds value without redundancy. Slightly verbose but not wasteful.

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 covers response contents (date, index_level, window change, gap flags, status) and edge cases (insufficient data). Missing details like ordering or field types, but comprehensive overall.

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. The description adds context for parameters (e.g., 'aepi' vs 'niche', 'tier' usage) but doesn't significantly extend beyond schema descriptions which are already clear.

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 dated index series for charting/analysis, specifies it's for AEPI or niche indexes, and distinguishes it from siblings like get_price_index. It uses specific language such as 'canonical DATED index SERIES' and 'index level (base 100), never a price.'

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 call this tool, such as for charting or analyzing movement. It implies use over get_price_index for historical data but doesn't explicitly list when-not-to-use or name alternatives, though the sibling list is given. It also mentions honest status to guide usage in edge 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?

With no annotations, the description carries full burden. It discloses that results include gap_score, why, crowding, listing count, market_pulse, and pricing rollup. It also describes behavior with empty args. No destructive or authentication details are needed for a read-only analysis 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?

The description is well-structured and front-loaded with the main purpose. Each sentence adds value, though a minor redundancy exists ('crowded niches are excluded, so a 'gap' is never crowded'). Overall, it efficiently conveys necessary information without significant waste.

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

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

Given the tool has 3 parameters (none required), no output schema, and two distinct modes, the description is fairly complete. It explains result fields, default behavior, and parameter options. It could mention the range of sector values or that 'hot' mode ignores crowding, but overall it meets the needs for correct invocation.

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

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

Schema coverage is 100% so baseline 3. The description adds value by explaining the 'rank' enum values in detail (gaps vs hot), specifying defaults (limit=15), and describing the 'sector' filter with examples. This semantic enrichment goes beyond the schema's concise 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 finds under-served markets (whitespace with money and few competitors) and distinguishes two ranking modes: default 'gaps' and 'hot' for momentum. It explicitly differentiates from sibling tool 'niche_report' by noting that empty args return a ranked overview.

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

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

The description explains when to use each mode: 'gaps' for whitespace with money, 'hot' for market pulse tracking. It notes that crowded niches are excluded in gaps mode and that empty args return an overview. However, it does not explicitly state when to use alternatives like 'demand_signals' or 'find_niche'.

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 the description carries full burden. It details return fields, data quality conditions (e.g., null when thin), the evidence ladder for pricing, and resolution of approximate niche names. However, it does not mention idempotency or side effects, which are not required for a read-only report but could be inferred as non-destructive.

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

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

The description is a single dense paragraph that front-loads the purpose and key information. While every sentence is valuable, it could benefit from bullet points or structure for easier parsing. Length is justified by the complexity of the return fields.

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 thoroughly enumerates all return fields (market_pulse, movement, index_series, pricing_status) with explanations, linking to other tools (find_niche's evidence ladder). It addresses edge cases ('each null when data is thin') and provides cross-references to sibling tools, making it self-contained for selecting and invoking the tool correctly.

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

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

Schema coverage is 100%, but the description adds significant value beyond the schema: it explains that 'niche' accepts slugs, approximate slugs, or natural-language names and is resolved to canonical form; for 'response_mode', it describes the default and what each mode returns (compact 5KB block vs full everything). This helps agents understand parameter behavior and options.

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's purpose as a deep-dive into one market niche before building or investing, and distinguishes it from the sibling tool 'research_capability' which combines market, pricing, and shortlist in one call.

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 clearly specifies when to use this tool ('when you already know the niche') and provides an alternative ('for market + pricing + shortlist in one call use research_capability'). It also directs users to 'market_gaps' for valid slugs.

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 fully bears the transparency burden. It details niche resolution, data quality tiers, legacy fields, and edge cases (short series, thin samples), giving a comprehensive view of behavior.

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

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

The description is long (7-8 sentences) but each sentence adds essential detail. Could be slightly more concise, but the density of information justifies the length.

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

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

Despite lacking an output schema, the description fully explains return fields (pricing_by_tier, index, index_by_tier, niche_resolution), edge cases, and references sibling tools for context. It is complete for the tool's complexity.

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

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

Schema description coverage is 100%, but the description adds extra meaning: niche resolution (approximate, natural-language), canonical slug return, and sector being ignored if niche is given. This enriches the schema definitions.

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

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

The description explicitly states 'Call this to learn what a capability normally COSTS before choosing', specifies the resources (pricing distribution, index, etc.), and distinguishes from sibling tools like find_niche by referencing the same evidence ladder.

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

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

It tells the agent when to use the tool ('before choosing') and provides context on scopes (whole-economy vs niche/sector) and conditions for index_by_tier. However, it doesn't explicitly list alternatives or when not to use.

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

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

With no annotations, the description fully carries the transparency burden. It discloses behavioral traits: 'Reads each agent's analysed site profile; never invents capabilities; returns 'unclear' where evidence is missing,' which is clear and honest about limitations.

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-loading key information (purpose, restrictions) in the first sentence and adding behavioral details in the second. Every sentence serves a purpose with no wasted words.

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

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

Given the tool's complexity (nested objects, 3 params, no output schema), the description covers purpose, usage restrictions, behavioral guarantees, and return format (structured, scored matches with reasons and cautions). It is complete for effective tool selection.

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 description adds minimal new meaning beyond the schema. It provides context but doesn't elaborate on individual parameters beyond what's already in the input schema.

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

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

The description clearly states the verb 'return' and resource 'ranked agent candidates for EACH step', specifying the inputs (business context and workflow steps). It distinguishes itself from siblings like 'search_agents' and 'compare_agents' by focusing on workflow-specific agent ranking.

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 marks the tool as 'PARTNER-ONLY (Bearer key required)' and targets 'app builders assembling automations', providing clear usage context. While it doesn't explicitly state when not to use or list alternatives, the context makes it evident.

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 and excels at disclosing behavioral traits: correlation with retrievals, weighting rules, aggregation requirements (5+ reporters), rate limit doubling for active reporters, and the x-agentery-key header identity mechanism. This provides comprehensive 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?

The description is a single dense paragraph but efficiently conveys all necessary information without redundancy. It could benefit from structuring (e.g., bullet points) for easier parsing, but the content is front-loaded and every sentence adds value.

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

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

Given the tool has 6 parameters, no output schema, and no annotations, the description is remarkably complete. It covers reporting mechanics, matching criteria, aggregation, rate limit effects, and identity persistence, leaving no significant gaps in understanding for an AI agent.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value beyond the schema by explaining how parameters are used in the backend (e.g., correlation of agent_id, impact of note and latency_ms on weighting, and the meaning of error_class). This enhances understanding for the agent.

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 report whether an agent worked after use. It specifies the action (report) and the resource (outcome of agent usage), and implicitly distinguishes from sibling tools like search_agents or compare_agents by focusing on post-use 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?

The description provides explicit context on when to use: after using a listed agent, and explains that reports are correlated with recent retrievals. It mentions which retrievals count and that unmatched reports are stored but unweighted, guiding proper usage. However, it lacks explicit when-not conditions or comparisons to 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?

No annotations provided, so description carries full burden. It thoroughly discloses what the tool returns (three parts), that it reuses existing engines, what it does NOT do (run comparison), and mentions caching and result_fingerprint. It is complete for a read/research 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?

The description is relatively long but well-structured with numbered points and front-loaded ('START HERE for agent procurement'). Every sentence adds value; no redundancy. Could be slightly more compact but remains 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 complexity (8 parameters, 15 sibling tools), the description is comprehensive: it explains the output structure, behavior, limitations, and relationships to other tools. No output schema exists, but the description covers return values adequately.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds additional context for several parameters (e.g., provider_type's soft-ranking behavior, default sort, alias for task), providing 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 states exactly what the tool does: it collapses multiple sub-tools (find_niche, niche_report, price_benchmark, search_agents) into a single call to produce a resolved market, pricing context, and provider shortlist. It distinguishes from siblings by naming them and specifying when to use each.

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

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

Explicitly says 'START HERE for agent procurement', tells when NOT to use this tool (when finer control is needed, use lower-level tools), and provides an alternative for comparison (compare_agents). Clear context and 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?

No annotations provided, so description carries full burden. Discloses result structure, alias handling, and post-use behavior (report_outcome). Lacks explicit mention of rate limits or authentication, but covers key 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?

Description is front-loaded with key guidance and dense with information. Slightly verbose but each sentence adds value, appropriate given tool complexity.

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

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

Given 7 parameters, 14 siblings, and no output schema, description is remarkably complete. Explains output structure, cross-references sibling tools (research_capability, get_agent_profile, report_outcome), and provides workflow guidance.

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 significant value: alias handling for query, default sort behavior, examples for filters and billing, and detailed explanation of max_monthly_usd and require_public_price parameter behavior.

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 performs targeted free-text search over a directory, distinguishes from research_capability by specifying it's for when you already know what you want, and details output features like match_score and match_reasons.

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 (when you know what you want) and when not to (new task, use research_capability instead). Also guides on filtering by price, sorting, and calling report_outcome after use.

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

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

Despite no annotations, description discloses return fields (price, liveness, upvotes, how_to_connect) and behavior of cheaper_only parameter. Does not explicitly state read-only, but implied by context. Lacks explicit mention of non-destructive nature.

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

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

Single informative paragraph with front-loaded purpose. Each sentence adds value; no redundancy. Could be slightly more concise but still 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?

In absence of output schema, description fully explains output contents. Covers all parameters, usage scenarios, and edge cases (cheaper_only behavior with free agents). Complete for a lookup tool.

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

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

Schema coverage is 100% so baseline is 3. Description adds value by explaining cheaper_only behavior in detail and noting agent_id accepts handle/id aliases. Limit and agent_id are straightforward.

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

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

Description clearly states the tool provides substitutes for an agent when expensive, unreachable, or poor fit, with specific resource (agent_id) and output details. Distinguishes from siblings by noting alternatives are surfaced automatically in research_capability and compare_agents.

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 call (agent too expensive, unreachable, poor fit) and when not to (alternatives surfaced automatically elsewhere). Provides clear context for tool selection.

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