DC Hub — Data Center & Energy Intelligence

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

Annotations already declare readOnlyHint=true, so the description's main addition is the refresh schedule (Fridays 14:00 UTC) and output fields summary. This adds useful behavioral context beyond annotations without contradiction, but does not detail rate limits or other constraints.

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 concise at five sentences, front-loading the core purpose and outputs. It could be slightly more compact, but structure is logical and each sentence serves a distinct purpose (purpose, outputs, refresh, use cases, exclusions).

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

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

For a tool with no output schema and low schema coverage, the description covers high-level purpose, outputs, and exclusions adequately. However, it lacks parameter details and exact return format, which a moderately complex tool like this would benefit from for complete agent understanding.

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 two parameters (limit, horizon) with 0% description coverage. The description mentions 'next 30/60/90 days' which hints at horizon but does not explicitly define either parameter's meaning, range, or default. The agent is left to infer what values to provide.

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

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

The description clearly states the tool ranks data center markets by deployability of 100MW AI training capacity within 30/60/90 days, listing specific outputs. It also explicitly distinguishes from sibling tools by stating what not to use it for, making the purpose highly specific and unambiguous.

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

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

Usage guidelines are explicit: it provides when to use (AI capex planning, GPU cluster siting, hyperscaler deal forecasting) and when not to use (general best-markets ranking, forward grid-emergence), with alternatives named (rank_markets, grid_transition_radar). This gives 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.

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

Annotations declare readOnlyHint=true, which the description reinforces with 'read'. Although no additional behavioral traits like side effects or rate limits are mentioned, the description adds context on the return format and multi-factor nature, which is sufficient given the annotation coverage.

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

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

The description is a single coherent paragraph that starts with purpose, includes an example, then lists parameters and return fields. Every sentence adds value without redundancy. 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?

Despite no output schema, the description enumerates all return fields with types and units. It covers input limitations, default behaviors, and explicitly references sibling tools. Highly complete for a tool of this complexity.

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

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

Input schema has 0% description coverage, but the description compensates fully by detailing each parameter: lat/lon ranges, capacity_mw range, state optional with example, boolean defaults. This adds meaningful semantics beyond the schema's type-only definitions.

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

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

The description clearly states the tool's purpose: 'full multi-factor data-center suitability read in one call' for a single lat/lon. It distinguishes from siblings by naming compare_sites and find_alternatives as alternatives for different use cases.

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

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

Provides explicit when-to-use: user has one lat/lon and wants a comprehensive suitability read. Also gives explicit when-not-to-use with named alternatives: 'Do NOT use to compare 2+ sites (use compare_sites) or to find sites that match a target (use find_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?

Description claims 'Mint' which implies a write operation, but annotations set readOnlyHint: true. This is a direct contradiction. The description does not clarify that the operation is actually idempotent or read-only.

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 adding value. Front-loaded with main purpose. Could be slightly more concise but 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 fully explains return values (api_key, header, daily_limit, upgrade_url) and overall workflow. Covers all necessary context for a simple key-claiming 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 has 2 parameters with 0% description coverage. Description explains both params: client_name is the agent/app name, email is optional for recovery. Provides full context beyond schema.

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

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

Description clearly states 'Mint a FREE DC Hub dev key instantly' with specific verb 'Mint' and resource 'FREE DC Hub dev key'. It is distinct from sibling tools which are data retrieval and analysis 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 tells when to use: 'Call this the moment you hit a paywall or a 1-result preview'. No explicit when-not, but context is clear. Mentions it's the fastest path from anonymous to identified.

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

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

Annotations already mark readOnlyHint=true, so the description adds value by specifying return structure and that it replaces N sequential calls. It provides clear behavioral context beyond annotations 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 well-structured with purpose, usage, param spec, return spec, and exclusions. It is slightly verbose but every sentence adds value.

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

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

Given one parameter and no output schema, the description fully specifies the parameter constraints and return fields (isos, comparison with detailed sub-fields, as_of). No gaps.

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

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

Schema has 0% coverage for the single parameter 'isos', but the description fully compensates: explains it uses comma-separated values, lists 2-4 from an explicit set of ISO codes, and provides an example.

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 precisely states it performs a pairwise side-by-side comparison of 2-4 ISO grids for fuel mix, demand, prices, carbon intensity. It clearly distinguishes from siblings like 'get_grid_scoreboard' and 'get_grid_intelligence'.

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

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

The description explicitly states when to use this tool (pairwise comparison) and when not to (ranking all grids, interconnection-queue brief), naming alternative tools. It includes an example call.

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

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

Annotations already indicate readOnlyHint=true, so no destructive behavior. Description adds detail about return structure including sites, winner, and decision_rationale. Does not contradict annotations.

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

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

Well-structured with purpose, example, parameter explanation, return fields, and usage boundaries. A bit verbose but every sentence adds value. 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?

Given no output schema and only one parameter with no schema description, the description fully covers purpose, parameters, return structure, and usage constraints. Leaves no ambiguity for the 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 has only 'locations' with no description, and description compensates by explaining the format (semicolon-separated lat,lon pairs, 2-4 max). However, description also mentions 'capacity_mw' as a parameter, which is absent from the input schema, creating confusion. This reduces clarity despite some added value.

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

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

Clearly states the tool compares 2-4 candidate parcels side-by-side with a recommended winner, including specific factors like grid, fiber, water, etc. Distinguishes from siblings analyze_site (single site) and rank_markets (market 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?

Explicitly says when to use (narrowed to 2-4 parcels) and when not to use (single site or market ranking), with direct alternatives mentioned. Provides an example query.

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

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

Annotations already indicate readOnlyHint=true. The description aligns by describing a read operation (returns data). It adds behavioral context about paid key unlocking additional details, which is useful. No contradictions.

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

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

Two sentences plus an example, 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?

Given no output schema and simple parameter, the description covers key return fields and mentions paid key limitations. Lacks details on DCPI verdict format or error handling, but sufficient for a focused 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 (limit) with 0% schema description coverage. The description's example 'limit=15' implies it controls the number of results, adding meaning beyond the raw 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: tracking data-center M&A/deal flow with DCPI grid-reality verdict. It specifies what is returned (buyer, seller, value, market, DCPI verdict, time-to-power) and differentiates from siblings like get_market_dcpi_rank or list_transactions.

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 a concrete usage example ('Try: deal_autopsy limit=15'), which helps agents understand invocation. However, it does not explicitly contrast with alternatives or 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?

Adds value beyond annotations by explaining return format (CSV rows or GeoJSON FeatureCollection) and listing included fields. Consistent with readOnlyHint.

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?

Information-dense but not overly concise; front-loads purpose and usage, then details parameters and return. 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?

Fully covers purpose, usage, parameter, return format, and exclusions for a simple 1-param tool with no output schema.

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

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

Adds meaning to the single parameter 'format' by explaining default and options, compensating for 0% schema coverage.

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 'export' and resource 'saved DC Hub shortlist', and explicitly distinguishes from sibling tools like list_saved_sites and save_site.

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

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

Explicitly says when to use ('when a user wants to pull...') and when not to use ('Do NOT use to list sites in-chat...'), with a concrete example.

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

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

Annotations already provide readOnlyHint: true. The description adds return format details (similarity_score, match_reasons, key_differences) but introduces parameter mismatches (mentions 'name' and 'capacity_mw' not in schema; omits 'match_on' and 'exclude_operator'). This reduces clarity for the agent.

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 relatively concise (3-4 sentences) and front-loaded with purpose. Minor redundancy ('Params:' listing) but generally efficient.

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

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

For a tool with 5 params, no output schema, and 0% param descriptions, the description covers usage, return format, and exclusions. However, it fails to address all parameters (match_on, exclude_operator) and contains inaccuracies, leaving gaps.

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

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

Schema coverage is 0%, so description must compensate. It explains facility_id, radius_km, limit, but introduces undocumented params (capacity_mw, name) and omits match_on and exclude_operator. The claim that facility_id is required contradicts schema showing 0 required params.

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

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

Description clearly states the tool finds similar nearby options given a seed facility, with a specific verb ('find alternatives') and resource ('facility'). It distinguishes from siblings like compare_sites and score_facility by stating what it does and does not do.

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

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

Explicitly says when to use (user likes one facility and wants similar options) and when not to use (scoring one site or head-to-head comparison). Provides an example, making it easy for an agent to decide.

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

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

Annotations already declare readOnlyHint=true, but description adds value by noting it reflects real calls, not a fixed list, and lists recognized MCP clients. No contradiction.

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

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

Description is detailed but not overly long, front-loading purpose and then providing usage guidance. The 'Try: get_agent_registry' is slightly redundant but does not detract significantly.

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 input parameters and no output schema, description is fairly complete: explains return values and provides usage context. Could mention output format but not essential.

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?

Tool has 0 parameters, so description doesn't need to explain them. Baseline 4 is appropriate as schema coverage is 100% and no parameter details are necessary.

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 returns a live roster of AI platforms/agent frameworks that have called DC Hub with metrics like citation counts and authentication tier. Distinguishes from sibling tool get_backup_status by explicitly stating what it is NOT for.

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

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

Explicitly says when to use (benchmarking which agents discover the platform) and when not to use (platform uptime/backup health), and names the alternative tool get_backup_status.

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, so the safety profile is clear. The description adds value by detailing the specific metrics returned (db backup, freshness colors, heartbeat score, etc.) and clarifying this is platform/infra health, not content. No contradictions.

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

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

Two sentences: the first efficiently lists all metrics, the second provides usage guidance and differentiation. No unnecessary words; every sentence earns its place.

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

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

For a tool with no parameters and no output schema, the description covers all relevant aspects: what metrics are returned, usage context, and what not to use it for. It is complete and informative.

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

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

The input schema has zero parameters, so description coverage is 100%. The description does not need to add parameter semantics, but it does not detract. Baseline for zero params is 4.

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

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

The description clearly states the tool returns platform health metrics including database backup status, data freshness, agentic heartbeat, MCP call volume, and DCPI cadence. It distinguishes itself from sibling tools by explicitly saying not to use for specific dataset freshness, recommending get_changes instead.

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

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

The description provides explicit guidance on when to use ('trust/uptime signals before relying on the platform in production') and when not to use ('Do NOT use for the freshness of a specific dataset'), along with a specific alternative tool (get_changes).

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

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

Annotations indicate readOnlyHint=true, and description adds behavioral details about incremental sync, return categories, and caching pattern. No contradictions; fully transparent for a read operation.

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 key purpose, no fluff. Every sentence adds value: purpose, return content, usage example.

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 0% schema coverage, the description covers purpose, usage, and return categories adequately, but lacks explanation for 'limit' parameter and return structure details.

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 0%, so description must document parameters. It thoroughly explains 'since' (ISO-8601, shorthand, default), but 'limit' is not described, leaving a gap.

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 is for incremental sync, specifying what changes are tracked (DCPI market movers, facilities, deals, news) and how it differs from full re-fetch. Distinguishes itself from sibling tools by focusing on delta updates.

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 describes when to use (for delta instead of full fetch), provides syntax for 'since' parameter with examples, and advises caching 'generated_at'. Does not explicitly state when not to use, but context is clear.

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

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

Annotations indicate read-only; description adds details about return structure, licensing (CC-BY-4.0), and that it's a consolidated response. No contradictions, but could explicitly state no side effects.

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

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

Well-structured with example, parameters explanation, and output breakdown. Slightly long but efficiently packed; front-loaded with core usage.

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 when to use, input format, output shape, citation, and exclusions. No output schema but description provides detailed structure. Complete for a complex recommendation tool.

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

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

The single parameter 'context' has 0% schema description coverage; the tool description compensates by explaining it as free-text describing MW, geography, workload, etc., adding significant meaning.

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: answering open-ended siting questions with a single call, and distinguishes it from siblings like 'analyze_site' and 'rank_markets'.

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 (open-ended siting questions) and when not to (single lat/lon or single-criterion ranking), with specific alternative tools named.

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

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

Annotations already indicate readOnlyHint=true, so description adds value by detailing the scope (10 ISOs) and data types. No contradictions; no destructive behavior implied. Slightly more context beyond annotations earns a 4.

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 tightly written sentences. The first states purpose and scope; the second provides negative guidance with tool alternatives. 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 has three optional parameters and no output schema, the description should clarify parameter defaults or behavior with no input. It does not. The data types are hinted but not formally listed. Adequate but incomplete for an agent to use confidently.

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 0%, but the description does not explain the parameters (iso, state, data_type) or their allowed values. The listed data types loosely imply possible values for data_type but lack specificity. The agent gets minimal help understanding parameter usage.

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

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

The description clearly states the tool retrieves energy pricing data across 10 specific ISOs, listing data types (retail rates, natural gas, real-time grid status). It explicitly distinguishes from sibling tools by naming alternatives, leaving no ambiguity.

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

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

Provides explicit guidance: use for pricing-focused queries; do not use for fuel mix, demand, or grid headroom, and names specific sibling tools as alternatives (get_grid_data, get_grid_intelligence). This is exemplary.

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, so the description doesn't need to reiterate that. It adds value by disclosing the detailed data returned and emphasizing it returns a single facility. No contradictions.

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

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

The description is a single, dense paragraph with no wasted words. It efficiently conveys the tool's purpose, output, and constraints. Very minor improvement possible by separating boolean parameter descriptions.

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

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

Given 3 parameters and no output schema, the description thoroughly explains the output fields (name, operator, address, etc.) and usage constraints. It provides complete context for an agent to correctly use the tool.

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

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

Schema description coverage is 0%, so the description must compensate. It explains that facility_id can accept an ID or slug, which is helpful. However, it does not describe the optional boolean parameters include_power and include_nearby, leaving a gap.

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 full metadata for one facility and lists specific fields. It distinguishes itself from the sibling search_facilities by emphasizing it returns a single facility, not a list.

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 'Returns ONE facility in full; do NOT use to search or list many facilities (use search_facilities).' Also provides concrete examples with id and slug, giving clear guidance on when and how to use it.

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

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

Annotations already indicate readOnlyHint=true. The description adds that it returns a GeoJSON FeatureCollection, which is useful context. No contradictions or missing safety info.

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: front-loaded with use cases, includes a clear example with parameters, and lists return format. No unnecessary 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, the description describes the return format. It covers purpose, parameters, usage guidelines, and distinguishes from siblings. Complete for a read-only tool with simple parameters.

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 0%. The description provides detailed enum values and context for two parameters (carrier, route_type) but does not mention the third (include_sources). This adds significant value beyond the schema, though incomplete.

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: scoring sites for fiber depth, mapping long-haul routes, and assessing dark-fiber availability. It provides a concrete example and distinguishes from sibling tools like get_facility and analyze_site.

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 states when to use the tool (fiber intelligence tasks) and when not to use it (for single-facility counts or interconnection density), naming specific alternative tools.

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

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

Annotations already indicate readOnlyHint=true. The description adds return value details (score, near_net_bucket, etc.) and parameter constraints (range, default), which are beyond structured data. It does not mention authentication or rate limits, but these are not critical for a read-only 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 with front-loaded purpose, example, parameter details, and return shape. It is slightly lengthy but each part adds value, and given schema lacks descriptions, the length is justified.

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 includes full return shape. It covers inputs, outputs, use cases, and exclusions with sibling differentiation. Error cases are absent but acceptable for a simple 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 has 0% description coverage, but the description fully compensates by detailing lat/lon ranges, required status, and radius_km default and range. This adds complete meaning beyond the bare 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: to provide fiber-readiness/connectivity verdict for a single parcel/site using lat/lon. It differentiates from siblings by explicitly mentioning that get_fiber_intel is for routes and analyze_site for multi-factor scores. The example further clarifies usage.

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 need fiber-readiness verdict for one parcel') and when not to use, with direct references to alternatives (get_fiber_intel, analyze_site). This provides clear guidance for agent selection.

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

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

Annotations already set readOnlyHint=true, and description adds behavioral context: it returns a breakdown for a state or national ranking, and requires attribution (CC-BY-4.0). No contradictions.

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

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

Description is front-loaded with purpose and key details. Every sentence adds value: purpose, usage, example, exclusions, attribution. No filler.

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 enumerates returned fields (dcgi, gas_access_score, gas_cost_score, pipelines, operators, verdict) and verdict values. Complete for a read-only 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 0%, but description compensates by explaining state parameter (2-letter, e.g., TX) and its effect on output. It also mentions optional limit parameter for national ranking, though does not specify its exact behavior (e.g., number of states).

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

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

Description clearly states tool retrieves the Data Center Gas Index (DCGI), a 0-100 per-state natural-gas suitability score. It distinguishes from siblings like get_grid_data and get_grid_intelligence by explicitly stating what the tool is for and what it is not.

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

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

Provides explicit when-to-use (gas suitability) and when-not-to-use (electricity grid, live gas pricing) with specific alternative tool names (get_grid_data, get_grid_intelligence, get_energy_prices). Includes example call: get_gas_index state=TX.

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

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

Annotations already indicate readOnlyHint=true (safe read). Description adds that the tool provides 'raw real-time telemetry for one ISO,' implying low-latency, unaggregated data. 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?

Two sentences: first specifies scope and data types, second provides usage boundaries. No filler, 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 no output schema, description covers scope (ISOs, data types) and exclusions. Missing details on return format or data freshness, but adequate for a data-retrieval tool with readOnlyHint.

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 0% parameter description coverage. Description does not explain the meaning of 'iso', 'metric', or 'period' parameters beyond listing possible ISO values. For a tool with low schema coverage, the description should compensate but fails to provide parameter semantics.

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

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

Description explicitly states it provides 'real-time electricity grid data' (fuel mix, demand, prices) across 10 ISOs, and clearly distinguishes from sibling tools by specifying what not to use it for (power-availability, retail pricing).

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 guidance: do not use for power-availability/interconnection-queue analysis (use get_grid_intelligence) nor for retail/gas pricing (use get_energy_prices). Clearly states the tool is for raw real-time telemetry.

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 (safe read). The description adds value by listing the comprehensive return fields, explaining DCPI scores, and noting no mutation. It does not contradict annotations.

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

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

Well-structured: usage trigger, example, parameter details, return schema, exclusions. Every sentence adds value, though slightly long. 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?

Given the tool's complexity (many return fields, no output schema), the description is very complete: lists all return fields, explains parameters, and sets boundaries for when to use. Fully prepared for an agent to invoke correctly.

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

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

Schema coverage is 0%, but the description clearly explains that 'region_id' is the primary parameter, lists allowed values, and notes that aliases (iso/region) are accepted. This adds significant meaning beyond the bare 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 explicitly states the tool's purpose: answering questions about power availability for a single ISO. It uses a specific verb+resource ('get grid intelligence for one ISO') and distinguishes from siblings like 'compare_isos' and 'get_grid_scoreboard'.

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?

Clear when-to-use ('Use when a user asks...') and when-not-to-use ('Do NOT use to compare 2+ ISOs...') with explicit alternatives named ('use compare_isos', 'use get_grid_scoreboard').

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 data sources (EIA, Elexon, ENTSO-E, AEMO), ranking methodology (apples-to-apples for US/GB/EU, AU unranked due to data limitations), and attribution requirements. No contradiction with annotations (readOnlyHint).

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

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

Long but well-structured, front-loading purpose and key details. Every sentence adds value, though slightly 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 no parameters and no output schema, the description fully explains what the tool returns, the geographical coverage, ranking logic, and data sources.

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?

No parameters in schema, so description does not need to add parameter info. It adds value by describing the output content (rankings, fuel mix, demand) and data freshness.

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 a live global grid scoreboard ranking grids by renewable and gas share, and distinguishes itself from sibling tools like 'compare_isos' and 'get_grid_data'.

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

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

Explicitly tells when to use: to find the greenest or most gas-reliant grid for data center siting, and contrasts with pairwise comparison or single ISO queries.

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 annotations already set readOnlyHint=true, which the description aligns with by stating it returns raw nearby assets. The description adds behavioral details such as returning distance+capacity and joining to HIFLD/EIA, which is valuable 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 concise with two sentences. The first sentence effectively front-loads the purpose and scope, and the second provides a concrete example and usage guidance. 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?

With 6 parameters and no output schema, the description covers the main functionality, gives an example, and notes data sources (HIFLD/EIA). It lacks details on return format and some parameters, but is fairly complete for the tool's purpose.

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

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

The input schema has 0% description coverage for parameters. The description explains radius_km and lat/lon through the example, but does not cover other parameters like layer, limit, or min_voltage_kv. The description provides some meaning but not fully compensating for the lack of parameter descriptions.

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

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

The description clearly states the tool returns nearby infrastructure for a location, listing specific resources (substations, transmission lines, pipelines, power plants) with details like count, voltage, and fuel. It distinguishes itself from the sibling tool analyze_site by explicitly stating it should not be used for a single scored site-suitability verdict.

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

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

Provides an explicit usage example with parameters (lat=33.45, lon=-112.07, radius_km=25) and a clear when-not-to-use instruction, directing the agent to use analyze_site for site-suitability verdicts. This is excellent guidance.

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

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

Annotations already declare readOnlyHint=true. The description adds valuable context about what the tool returns (index value, percentile rank, trend direction, component scores) and gives an example call, all consistent with a read-only operation.

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, no fluff, front-loaded with the core purpose. Every sentence adds value: purpose, components, usage guidance, and an example.

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, 0 parameters, and simple structure, the description adequately covers what the tool returns and how to use it, including an example. No obvious gaps.

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

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

The input schema has no parameters (100% coverage), so baseline is 4. The description includes an example with a 'market' parameter, which is not in the schema, but this does not detract from the fact that no parameter documentation is needed.

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 returns a 'real-time composite market health score (0-100)', specifies the aggregated components, and distinguishes itself from siblings by explicitly stating what not to use it for (e.g., get_market_intel for full metrics, rank_markets for 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?

Provides explicit when-to-use (to get the composite health number) and when-not-to-use (do not use for full metric set or ranking), including specific alternative tool names (get_market_intel, rank_markets).

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

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

Annotations already indicate readOnlyHint=true. The description adds transparency by listing data sources and computed metrics (share, TTP months). No contradictions; it suitably complements annotations with behavioral 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 with no redundancy. Front-loaded with core purpose, then sources, parameter usage, and use cases/exclusions. Every sentence earns its place.

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

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

Despite no output schema, the description clearly outlines what the tool returns (queue snapshot, metrics). It explains when to use alternatives, providing complete context for a tool with one optional parameter.

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 0% with only a string parameter 'iso'. The description adds meaning by listing the 7 valid ISO values and explaining that passing an iso drills down to a single ISO. This compensates well for the lack of 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 provides an ISO interconnection queue snapshot with specific metrics (total large-load MW queued, data-center share %, top BUILD subregions, TTP months) and lists data sources. It distinguishes from sibling tools like get_grid_intelligence and grid_transition_radar by specifying different use cases.

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 (site-selection, competitive intel) and when not to use, providing specific alternative tools (get_grid_intelligence for single-site TTP, grid_transition_radar for forward-looking emergence). Also explains parameter usage (pass iso to drill down).

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

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

Beyond the readOnlyHint annotation, description adds outputs (composite_score, narrative), licensing (CC-BY-4.0), and behavioral constraints (single market only). No contradiction with annotations.

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

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

The description is concise, dense with information, and structured with initial purpose then usage boundaries. Slightly dense but 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?

Covers outputs, usage boundaries, licensing, and attribution. Lacks return format details but output schema is absent; description is sufficient for the tool's simplicity.

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

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

Only one parameter (market_slug) with 0% schema coverage. Description implies it identifies the market but does not explicitly define it or provide examples, leaving some ambiguity.

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 DCPI rank for a single market with specific outputs (verdict, composite_score, narrative) and distinguishes from siblings like rank_markets and compare_isos.

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

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

Explicitly says when to use (single market depth) and when not (ranking many markets, comparing ISOs), and provides context on coverage (100+ markets, 10 ISOs) and attribution requirement.

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, covering safety. Description adds scoping (232 global markets) and return fields, providing transparency 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?

Front-loaded with usage statement, followed by example, param explanation, return format, and exclusions. Every sentence adds value; no waste.

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

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

Adequately covers market parameter and return fields, but fails to explain other three parameters. For a tool with 4 params and no output schema, the description is incomplete.

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

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

Only explains the 'market' parameter with examples and slug format. Does not explain 'metric', 'period', or 'compare_to' at all, leaving them undocumented despite 0% schema coverage.

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 data about ONE data-center market, listing specific data points and giving an example. Also explicitly distinguishes 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?

Explicitly states when to use ('when a user asks about ONE data-center market'), what not to use for (ranking multiple markets, single facility), and provides an example query.

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 refresh rate (30 min), data sources, returned fields, and filtering options. Annotations already indicate readOnlyHint=true, and the description adds behavioral context without contradicting annotations. No destructive behavior mentioned, consistent with read-only 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?

Extremely concise: three sentences covering purpose, features, usage example, and exclusions. No filler, front-loaded with key information. Every sentence adds value.

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

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

With 7 optional parameters and zero schema descriptions, the description covers basic use (filter by topic, limit) but omits details on query, source, date range, and relevance scoring. The example only demonstrates one filtering dimension, leaving agents potentially underinformed for advanced queries.

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 0% (no parameter descriptions), so the description must compensate. It mentions filtering by topic and gives an example with 'topic=AI', but the schema has 'category' and 'query' instead of 'topic'. This inconsistency may confuse agents. Other parameters (query, source, date_to, min_relevance) are not explained.

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 curated data center industry news from 40+ sources, specifies fields returned, and distinguishes itself from siblings like list_transactions and get_pipeline, making purpose and scope 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?

Explicitly states when to use (for industry news) and when not to (for structured M&A deals or construction pipeline), directly naming alternative tools. Also provides an example call (get_news topic=AI limit=10) for immediate 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?

Adds context beyond readOnlyHint annotation: describes return fields, pagination, and scope (540+ projects, 369 GW). 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?

Single paragraph but front-loads purpose and usage, efficiently lists parameters with examples. Slightly dense but effective.

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

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

Provides sample return structure, explains pagination, covers all 7 parameters with examples, and gives clear usage context—complete for a tool with no output schema.

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

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

With schema description coverage at 0%, the description compensates by listing each parameter, allowed values (status enum, ISO-2 country), examples, and usage for pagination.

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 forward-looking construction pipeline data, with specific examples and distinguishes from sibling tools for operational facilities and M&A deals.

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

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

Explicitly says when to use (user asks about what's being built/announced/permitted) and when not to use (already-operational facilities, M&A deal flow), providing alternative tool names.

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

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

Annotations already indicate readOnlyHint=true. Description adds detailed behavioral context: returns capacity totals, breakdown by fuel type, capacity factor, top projects with details, state RPS target, and data source. Also explains optional lat/lon for proximity filtering.

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 compact (few sentences) but packs all essential information: use case, example, parameters, return structure, and exclusions. No redundant or filler content; each sentence contributes value.

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

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

Despite lacking output schema, description fully describes the return object structure (capacity_mw_total, by_fuel, capacity_factor_pct, top_projects array, state_rps_target_pct, source). This is sufficient for an agent to understand and use the tool's output.

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

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

Schema description coverage is 0%, but description fully compensates by explaining each parameter: energy_type (enum of solar/wind/combined or omit), state (2-letter US code), and optional lat+lon for 50-mile radius. This provides clear guidance beyond bare schema types.

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 tool is for obtaining renewable energy capacity and feasibility data for a single US state, with specific use cases: siting data centers, sizing PPAs, and assessing RE100/24-7-CFE. It distinguishes itself from siblings like get_grid_data (live generation) and get_grid_scoreboard (non-US).

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

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

Explicitly says when to use (for US state renewable energy assessment) and when not to use (for live grid generation or non-US regions), providing alternative tools. Includes an example query to illustrate usage.

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

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

Annotations already provide readOnlyHint=true, so description complements by detailing what the tool returns (program name, value, eligibility, expiration, source statute). It adds behavioral context beyond annotations.

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

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

Description is concise: two sentences plus an example and alternative. Front-loaded with purpose, then details, then guidance. No wasted words.

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

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

For a tool with one parameter, no output schema, but moderate complexity (enumerates incentive types), the description covers all needed aspects: what it returns, how to use it, and when to choose alternatives. Complete for agent understanding.

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 0% (no parameter descriptions in schema), but description compensates by explaining that 'state' is a US state abbreviation and provides an example ('VA'). This adds significant meaning for the single 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 provides 'Data center tax incentive packages by US state' and lists specific types (sales-tax exemptions, property-tax abatements, etc.). It distinguishes from sibling tool analyze_site by noting this covers only tax, while analyze_site covers multiple factors.

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

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

Explicitly states when to use: for tax incentives by US state. Gives an example call: 'get_tax_incentives state=VA'. Also provides when not to use and directs to alternative: 'for a combined multi-factor site read... use analyze_site'.

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, so the description's behavioral contribution is limited. It adds context about the data sources and returned fields but does not discuss rate limits, authentication, or side effects beyond what annotations imply.

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 at four sentences, front-loading purpose and outputs, with practical examples and a clear sibling reference. No unnecessary words or repetition.

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

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

The description explains return values (stress score, drought category, outlook, cooling assessment) in enough detail for a simple tool, and orients the user within the site evaluation context. It lacks details on error cases or county-level input mechanism but is otherwise 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 has no parameter descriptions (0% coverage). The description partially compensates by explaining that state and lat/lon are used for queries and provides examples. It does not fully document all parameters (e.g., county is mentioned but not a parameter) or specify constraints like ranges or required fields.

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 retrieves USGS water stress index and Drought Monitor risk for US locations, specifying input methods (state, county, lat/lon) and outputs (stress score, drought category, outlook, cooling-water assessment). It differentiates from sibling tool analyze_site, indicating it covers only the water factor.

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 example usages and explicitly states when to use this tool (single water factor) versus analyze_site for combined multi-factor assessment. It does not cover all alternative sibling tools but gives sufficient guidance for its primary use case.

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

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

Annotations indicate readOnlyHint=true, and description confirms it's a non-mutating radar. Adds context about paid key requirement for full thesis and describes output components.

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?

Packed with useful info, well-structured with main purpose upfront. Slightly long but each sentence adds value. Could be trimmed slightly, 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?

For a complex tool with no output schema, description covers key outputs and dependencies (paid key). Missing parameter details (limit) and output format specifics, but sufficient for agent understanding.

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 two undeclared parameters (limit, max_months) with 0% coverage. Description only mentions max_months=24 in an example; no explanation of limit. Does not fully compensate for schema gaps.

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?

Clear verb+resource: 'Forward-looking radar' for emerging hyperscale-friendly grids. Distinguishes from siblings by contrasting with 'where capacity landed' reports and explicitly naming alternatives for related tasks.

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 (forward-looking emergence) and when not to use (current queue snapshot or present-day market ranking) with sibling tool references. Provides an example invocation.

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. Description adds value via refresh rate (10-min), data source (dchub news pipeline), and extraction method (regex). No contradiction.

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

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

Two sentences packed with information; front-loaded with purpose. Slightly dense but efficient. Could trim 'live feed of' but overall 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?

Provides enough context for a live feed tool: source, update frequency, classification, actors. Missing behavior of 'limit' parameter and return format, but acceptable given no output schema and simple semantics.

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 parameter 'limit' is undocumented in description. Schema has 0% description coverage, so description should have explained its purpose (e.g., max number of deals to return). Missing this information.

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

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

Clear verb 'tracker' with specific resources listed (Stargate, OpenAI, etc.) and explicit distinction from 'list_transactions' and 'deal_autopsy'.

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 (tracking AI capex events) and when not to use (full historical M&A, single-deal teardown), with tool alternatives named.

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 explains the return structure (array with fields), sources the data from a persistent shortlist built by save_site, and notes it's an in-chat read-back, complementing the readOnlyHint annotation without contradiction.

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

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

The description is concise yet comprehensive, front-loading the purpose, providing examples, noting parameters, describing the output, and listing exclusions in a single, well-structured paragraph.

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, zero parameters, and annotations already providing readOnlyHint, the description fully covers all necessary context: when to use, what it returns, and what not to 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?

The input schema has zero parameters, and the description accurately states 'Params: none', so no additional parameter explanation is needed.

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 identifies the tool as retrieving a user's saved shortlist with specific examples of user queries ('What sites have I saved?') and explicitly distinguishes it from tools that add or export sites.

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 states exactly when to use (when user asks to see saved sites) and provides two explicit alternatives for when not to use (save_site for adding, export_dataset for downloading), making tool selection unambiguous.

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

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

Annotations already indicate readOnlyHint=true. The description adds valuable context: over 2,000 tracked deals from 2019, disclosed values only where public (many private deals undisclosed), and lists return fields. No contradictions with annotations.

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

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

Description is about 4 sentences, front-loaded with purpose, includes an example, and every sentence adds value. No redundancy or 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 10 parameters and no output schema, the description provides the dataset scope, return fields, and filter hints. Parameter details are incomplete but the overall context is strong enough for an agent to understand and 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?

Schema coverage is 0% so description must compensate. It mentions filters by year, min_value_usd, region, buyer, or target, but omits parameters like limit, offset, seller, date_to, date_from, deal_type, max_value_usd. The example helps but not all parameters are explained.

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

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

The description clearly states it returns M&A and capital transactions in the data center sector with specific fields (deal name, buyer, seller, value, date, market, target operator, type). It distinguishes from sibling tools like hyperscaler_deals and deal_autopsy by explicitly excluding their use cases.

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 guidance on when to use (broad M&A and capital-deal flow with filters) and when not to (hyperscaler-specific or single-deal post-mortem), with named alternatives. Includes an example call (list_transactions year=2026 min_value_usd=1000000000) for clarity.

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

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

Annotations declare readOnlyHint=true, which aligns with the tool's planning nature. The description adds important behavioral context: outputs are indicative auto-routed corridors, not engineered alignments, and are subject to further verification. This sets proper expectations.

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 but includes an example, parameter details, and a warning. While not ultra-compact, every sentence adds value and the main purpose is front-loaded. Minor improvement could be using bullet points for clarity, but it's well-structured for a paragraph.

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 explains the return values (length, geometry, diversity, cost) and notes the indicative nature. It also provides alternatives for related tasks. For a tool of this complexity, the description is comprehensive.

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 0%, so the description must explain parameters. It does so thoroughly: from and to accept lat,lng or street addresses, n ranges 1-6 with default 4, fibre values are specified, and bore_m is an optional integer. This adds essential meaning beyond the schema's type constraints.

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: planning N diverse fibre lead-in routes from a data-center site to a POP. It provides a concrete example and explicitly distinguishes from sibling tools (analyze_site and get_fiber_intel) by stating what not to use it for.

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 includes explicit usage guidance: when to use (to get diverse fibre routes) and when not to (for site-suitability or fiber-provider footprints), with specific alternative sibling tool names. The example further clarifies correct invocation.

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, consistent with operation. Description adds that it returns a ranked list across 232 markets and details the return structure, providing 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?

Description is front-loaded with key purpose and example. Slightly lengthy but every sentence adds value; could be tightened without losing clarity.

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

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

Given no output schema and 4 parameters, description covers purpose, parameter details, return structure, sibling differentiation, and example. Fully equips agent to select and invoke correctly.

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

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

Schema has 0% description coverage; description fully compensates by listing allowed criteria values, region values, limit range (1-50), and min_capacity_mw usage, with defaults. Example demonstrates parameter usage.

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

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

The description clearly states the tool produces a ranked list of top N markets by criteria, with specific verb 'rank' and resource 'markets'. It distinguishes from siblings like get_market_intel and analyze_site.

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

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

Explicitly specifies when to use ('top N markets for X') and when not to use (deep read on one market or scoring lat/lon), with alternative tools named (get_market_intel, analyze_site). Example provided.

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 annotation declares readOnlyHint=true, indicating a read-only operation, but the description explicitly states 'this WRITES one site to your account', creating a direct contradiction. This misleads the agent about the tool's side effects.

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 and well-structured: it starts with purpose, then parameter details, return value, and exclusions. It earns its place with an example and differentiation, though it could be slightly tighter.

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

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

Given the tool has 7 optional parameters, no output schema, and moderate complexity, the description covers purpose, parameters, return value, exclusions, and provides an example. This is fairly complete, though the annotation contradiction undermines trust.

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 0%, so the description must compensate. It lists the key parameters (lat, lon, name, state, market, target_mw, notes) and labels some as optional, but does not specify constraints, formats, or allowed values beyond the schema types. The example illustrates usage, but detail is insufficient.

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

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

The description clearly states the tool saves a candidate data-center site to the user's account. It uses a specific verb ('Save') and resource ('site'), and distinguishes from siblings by explicitly listing when not to use it (list_saved_sites, export_dataset, score_facility).

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 guidance on when to use (saving a site for tracking) and when not to use (reading shortlist, downloading, scoring). It provides an example and explicitly names alternative tools.

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

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

Annotations already declare readOnlyHint=true, indicating no side effects. Description adds that the tool returns composite score, tier classification, peer comparison, and per-dimension detail, which is useful context. No contradictions.

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

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

Description is moderately sized, front-loaded with purpose and example, then parameter details and exclusions. Each sentence adds value, though could be slightly tighter.

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

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

No output schema, so description covers return values (composite, tier, peer comparison, detail) and dimension list. Adequate for a scoring tool, though return format details are missing.

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

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

Schema has 2 params with 0% description coverage. Description explains the weighting parameter with its default ('balanced') and three other options, adding meaning beyond schema. However, it mentions 'facility_id or name' but schema only has facility_id, and says 'required' while schema shows none required, a minor inconsistency.

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 scores ONE existing facility across 7 dimensions, with an example. It explicitly distinguishes from sibling tools by listing alternatives (analyze_site, compare_sites, find_alternatives) for different use cases.

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 guidance on when to use ('user wants an independent 0-100 grade for ONE existing facility') and when not to use (raw lat/lon, comparing sites, finding similar sites), naming specific sibling tools.

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

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

Annotations already declare readOnlyHint=true, so the description's safety profile is covered. The description adds value by stating the tool returns specific fields (name, provider, lat/lon, etc.) and emphasizes it searches across many facilities. No contradictions or missing 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 a single paragraph of three sentences, front-loading the core purpose and search capabilities. The example is helpful but makes the description slightly longer than necessary. Every sentence adds value; no tautology or filler.

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 10 parameters, no output schema, and no parameter descriptions, the description is incomplete for an agent to correctly invoke the tool. It lacks information on parameter formats, constraints (e.g., max vs min capacity), pagination (limit/offset), and the full output structure. The example partially compensates but leaves many details unspecified.

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 0% — none of the 10 parameters are described in the schema. The description only illustrates a few parameters in the example (country, state, min_mw, status) but the schema shows min_capacity_mw, not min_mw. Most parameters (city, tier, limit, query, offset, operator, max_capacity_mw) are completely undocumented in the description, leaving the agent with no guidance on their meaning or usage.

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

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

The description uses a specific verb ('Search') and clearly states the resource ('21,000+ global data center facilities across 170+ countries') along with search dimensions (location, capacity, operator, etc.). It also distinguishes itself from siblings 'get_pipeline' and 'get_facility', making the tool's unique purpose unmistakable.

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

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

Explicitly states when to use ('find EXISTING facilities') and when not to use ('do NOT use for the forward-looking construction pipeline ... use get_pipeline' and 'for the full profile of one facility ... use get_facility'). Also provides a concrete example (country=US state=VA min_mw=10 status=operational) to guide usage.

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

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

Description states 'Subscribe to movement alerts' and 'SUBSCRIBES to future movement', which is a write operation, but annotations declare readOnlyHint=true. Contradiction detected.

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, front-loaded with purpose, includes an example, no superfluous text. Efficient and clear.

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

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

Fully covers the tool's action, usage, parameter semantics, and context (not for reading, subscription nature). No gaps for an agent to invoke correctly.

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

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

With 0% schema description coverage, the description compensates by explaining each parameter (market name, channel types, destination format) and providing an example. However, it does not enumerate allowed values or validate formats beyond examples.

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

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

The description clearly states the purpose: 'Subscribe to movement alerts for a DCPI market (PRO)' — specific verb and resource. It differentiates from sibling tools by explicitly mentioning get_market_dcpi_rank for reading.

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: channel=email with destination email, or channel=webhook with destination URL. Also includes an example and warns not to use for reading, directing to an alternative 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?

The description goes beyond the readOnlyHint annotation by detailing the full flow: 'find->rank->shortlist->verdict' and explains the paid key provides the synthesis decision layer (#1 pick, why, build sequence, risk flags). No contradictions with annotations.

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

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

The description is detailed but efficient, front-loading the core purpose and then providing usage guidance and exclusions. Every sentence adds value. Could be slightly tighter but is 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 5 parameters and no output schema, the description covers inputs (capacity, region, deadline), outputs (ranked shortlist, decision layer with paid key), and process flow. It is complete for a guided tool, though leaving two parameters unexplained is a minor gap.

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 0%, so description must compensate. It explains three key parameters via example (capacity_mw, region, max_months), but does not explain 'limit' or 'verdict'. While the example helps, the description could define all five parameters for full 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's a 'Guided end-to-end data-center site selection' tool that takes capacity target, geography, and deadline to produce a ranked shortlist. It distinguishes from siblings by explicitly saying not to use for a single known parcel (use analyze_site) or open-ended location question (use get_dchub_recommendation).

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 when-to-use context ('Give a capacity target + geography + deadline') and when-not-to-use with clear alternatives: 'Do NOT use for a single known parcel (use analyze_site) or an open-ended where-should-I-build question (use get_dchub_recommendation)'. It also gives a concrete example call.

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 checkout flow, session binding, cost tiers, and that subsequent calls return full data. Annotations only indicate readOnlyHint, and description adds valuable context without contradiction.

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

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

Packed with information but front-loaded; some redundancy (e.g., checkout explanation could be tighter) but every sentence earns its place.

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

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

Given no output schema, description covers return structure, pricing, session behavior, and upgrade process, fully equipping the 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 has 0% coverage, but description explains the single optional parameter 'reason' with its purpose (helps human see why the unlock matters), adding 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?

Clearly states the tool unlocks full data, specifies triggers (preview, locked tool, human request), and distinguishes from sibling 'claim_free_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?

Explicitly states when to call (preview, locked tool, want full data) and when to use alternative (claim_free_key for free tier).

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