DC Hub — Data Center Intelligence MCP Server

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds valuable behavioral context: data freshness (refreshed Fridays 14:00 UTC) and output components (composite score, hyperscale_ready flag). 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 4 sentences, front-loaded with purpose and output. Every sentence provides unique value; no redundant or verbose phrasing.

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

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

Given the tool's simplicity (2 optional parameters, no output schema), the description fully covers what it does, what it returns, and when data is refreshed. No gaps.

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

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

Schema coverage is 100%; both 'limit' and 'horizon' have descriptions. The description reinforces the horizon values (30/60/90) but adds no new parameter semantics beyond the schema. Baseline score is appropriate.

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

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

The description clearly states the tool ranks data center markets by deployable AI capacity (100MW) within specific time horizons (30/60/90 days). It specifies the action (ranks), resource (markets), and constraints, and explicitly distinguishes from sibling tools by naming alternatives.

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

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

The description provides explicit use cases (AI capex planning, GPU cluster siting, hyperscaler deal forecasting) and explicit exclusions with named alternatives (rank_markets for general rankings, grid_transition_radar for grid emergence).

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds significant behavioral context: returns honest 404 for out-of-coverage points, explains representative_point is centroid of largest-area member (never geometric center), and mentions site_evaluation_handoff. 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 detailed and front-loaded with the main purpose, but it is relatively long. Nevertheless, every sentence adds value, covering modes, edge cases, and return fields. Minor reduction in verbosity could improve conciseness, but it remains 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?

With no output schema, the description fully enumerates return fields (_entity, total_acres, per-member breakdown, contiguous flag, representative_point, hosted_parcel, site_evaluation_handoff) and explains behavior for edge cases (out-of-coverage). It is sufficiently complete for an agent to use the tool correctly.

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

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

Although schema coverage is 100%, the description adds substantial meaning: clarifies the lat/lon vs geometry choice, explains aliases (lng for lon, latitude/longitude), and states capacity_mw is passed through to site_evaluation_handoff. This goes beyond the schema's basic descriptions.

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

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

The description clearly states 'Structured read of a parcel BOUNDARY' and explains two modes: passing a GeoJSON or using lat/lon to find the hosting parcel. It distinguishes itself from siblings like analyze_site and get_refined_queue, making the purpose unmistakable.

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

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

Explicitly says when to use this tool: 'Use when you HAVE a boundary or a point on a specific parcel' and contrasts with analyze_site for general site score and get_refined_queue for interconnection queue. Also notes coverage limitations (Loudoun County first) and honest 404 behavior.

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 and idempotentHint annotations, the description discloses return value structure, FREE vs Pro tier differences, candidate_id behavior (frozen mint, expiration), and links to alternative tools for specific factors.

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

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

The description is well-structured and front-loaded with the core use case. It is relatively long but every sentence adds value; slight improvement could be achieved with bullet points, but it remains 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?

Given the tool's complexity (11 parameters, no output schema), the description covers all necessary aspects: usage, parameter details, return values, tier limitations, and sibling references, fully meeting the agent's needs.

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?

Even though schema coverage is 100%, the description adds significant context: required/optional conditions, typical ranges (50-500 MW), aliases (lng for lon), and behavioral details (candidate_id ignores lat/lon, expirations).

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: analyzing a single lat/lon for data-center suitability in one call. It uses specific verb-resource pairing and explicitly distinguishes from siblings like compare_sites and find_alternatives.

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

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

The description provides explicit when-to-use guidance ('when a user has ONE specific lat/lon') and when-not-to-use ('Do NOT use to compare 2+ sites or find alternatives') with named alternatives, along 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?

Discloses all key behavioral traits: free tier changes (10 calls unbound vs 50/day bound), recoverability, marketing opt-in default off, and that rejected emails don't break functionality. 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 well-structured with clear sections, but is lengthy. Front-loads purpose effectively. Every sentence adds value, but could be tightened.

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

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

Covers all aspects: preconditions, side effects, error recovery, parameter details, consent requirements, and return value. No output schema is needed given the narrative completeness.

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

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

Schema coverage is 100%, but description adds critical semantics: email must be real and explicitly given, api_key can be omitted to bind current session, marketing_opt_in requires explicit consent. This goes far beyond the schema.

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

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

The description clearly states the tool's purpose: binding a DC Hub key to a human's email for recoverability and receipt routing. It distinguishes from siblings by specifying the action and context.

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

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

Explicitly states when to call (once human shares email), provides fallback for free tier gate, warns against invented emails, and explains that rejection is non-blocking. Includes a script for asking the human.

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 creation of a key, recovery via email, and return fields. Annotations (readOnlyHint=false) confirm mutation. However, it does not explicitly state whether multiple calls create multiple keys, though idempotentHint=false implies non-idempotence. Slight gap in clarity.

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?

Dense but well-structured, starting with core action, then usage, then params. Could be slightly more concise by removing redundant phrasing, but every sentence contributes meaning.

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?

Comprehensive for a simple tool: includes when to use, param explanations, return format, daily limit, upgrade path, and alternative tool. No output schema needed; description suffices.

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 significant value beyond the schema: explains client_name for attribution and email for recoverability, with examples. Covers both parameters fully, and the description clarifies their purpose and optionality.

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 mints a free DC Hub dev key, specifying the verb 'Mint' and the resource. It distinguishes from siblings like 'unlock_more_data' and 'recover_my_key' by context, making the purpose unambiguous.

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

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

Explicitly tells when to call: 'the moment you hit a paywall or a 1-result preview'. It also mentions the alternative 'unlock_more_data' for upgrading and explains the free tier limitations, providing clear context for 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds significant value by explaining the physics-based nature (e.g., light in SMF-28 fiber, route_factor 1.4), the confidence tiers (published | tracked | inferred), and the behavior of dropping expired/unknown candidate_ids with fail-closed candidate_contract. No contradiction with annotations.

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

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

The description is relatively long but well-structured, front-loading the main purpose and then providing necessary details. Every sentence adds value given the tool's complexity. Slight verbosity in the return structure description but still acceptable.

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 (4 optional parameters, no output schema), the description is thorough: it explains the return entity structure (pairs, clusters, viable_count, etc.), the candidate contract, confidence tiers, and even provides examples. It also points to sibling tools for follow-up actions, making it a complete specification.

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

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

Schema coverage is 100%, so baseline is 3. Description adds extra context beyond schema: for sites parameter, explains labeling and cand_ tokens; for candidate_ids, explains resolution to frozen mint; for max_latency_us, gives default and typical sync replication range; for min_confidence, explains tiers and default. This extra detail justifies a 4.

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

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

The description clearly states the tool's purpose: physics-bounded latency clustering for 2-8 sites, returning viable low-latency clusters and pairwise RTT floors. It distinguishes itself from siblings like plan_fiber_leadin and get_fiber_readiness by focusing on deterministic pruning before detailed routing.

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 the tool ('when your human wants to know which of N candidate sites can form a synchronous / low-latency cluster') and when not to (not an engineered latency quote). Provides alternatives (plan_fiber_leadin for actual routing, get_fiber_readiness for single-site readiness). Includes examples and explains the candidate contract.

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 and idempotentHint. Description adds constraints (2-4 ISOs, comma-separated, specific list) and return structure, which enhances 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?

Description is verbose but well-organized, front-loading purpose. Every sentence adds value, though example could be placed after parameter details for slightly better flow.

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 single parameter, no output schema, and comparison tool complexity, description covers purpose, usage, parameters, return structure, and exclusions comprehensively.

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

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

Schema already describes parameter with 100% coverage. Description adds example, valid values list, and max count, providing extra context beyond schema.

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

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

Description clearly states the tool's purpose: 'side-by-side of 2-4 ISO grids' with specific metrics. Uses strong verb 'compare' and distinguishes from siblings get_grid_intelligence 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?

Explicitly provides when to use (user wants side-by-side comparison) and when not to use (ranking all grids or single-ISO deep brief), with 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 declare readOnlyHint and idempotentHint. Description adds that it runs analyze_site internally, explains paid/pro tier behavior, and details the return structure. No contradiction.

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

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

The description is long but well-structured, with front-loaded purpose, example, param explanations, and exclusions. Some detail on return values could be trimmed, but overall efficient.

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

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

Despite no output schema, the description comprehensively covers the return shape, including nested objects and derived fields. It also addresses edge cases like paid vs free tier and provides enough context for correct invocation.

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

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

Schema coverage is 100%, so baseline is 3. Description adds an example and explains the alternative 'sites' array format, but does not significantly augment the schema already provided.

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 side-by-side winner picker across power, gas, fiber, market, and risk dimensions for 2-4 candidate parcels. It distinguishes from siblings by explicitly noting not to use for a single site or to rank entire 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 states when to use (narrowed to 2-4 parcels, wants comparison) and provides alternatives for single site (analyze_site) and market ranking (rank_markets). Includes 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?

Discloses behavioral traits beyond annotations: progressive disclosure, default cheap mode, paid key for full autopsy. Annotations already indicate read-only and idempotent, so the description adds valuable 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?

Description is concise (three sentences) with front-loaded purpose. Every sentence adds value, no redundancy or fluff.

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

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

Despite no output schema, the description clearly lists what is returned (deals, verdict, time-to-power) and the paid key upgrade. For a tool with two parameters, this is fully complete.

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

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

Description fully explains the comparables parameter with default 'none' and escalation to 'summary' or 'full', and the limit parameter. Schema has 100% coverage, but the description adds meaning about typical use and cost implications.

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 tracks data-center M&A/capex deal flow with DCPI grid-reality verdict overlay. It distinguishes from sibling tools like get_market_dcpi_rank and list_transactions by combining deal data with verdicts.

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 (to get deals with DCPI verdict) and mentions progressive disclosure with comparables levels, but does not explicitly state when not to use or 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 readOnly, idempotent, non-destructive. The description adds behavioral context by stating it returns tool families with when-to-use notes and that it's a navigation layer, not an exhaustive catalog. This goes beyond annotations by describing output format and role.

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 compact with only a few sentences, front-loaded with the core purpose and action. It efficiently covers when to use, what it returns, and its relation to the canonical list. Minor redundancy but overall well-structured.

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

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

Given the tool's simplicity (one optional param, no output schema), the description is sufficiently complete. It explains the return type (tool families with notes and flagship tools), the filtering option, and the relationship to tools/list. No additional details are necessary for an agent to use it correctly.

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

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

Schema coverage is 100% and the parameter 'query' is described in both schema and description consistently. Description adds no new meaning beyond what the schema provides, meeting the baseline for full 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 explicitly states it is a meta-tool for navigating tools by family, listing specific families and distinguishing from other tools. It uses a specific verb ('navigate') and resource ('DC Hub's 60+ tools by FAMILY'), avoiding 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?

Explicitly advises 'Call this FIRST when you are unsure which tool fits a task' and explains the workflow of then calling the chosen tool. It also clarifies when not to rely on it (canonical list is tools/list), providing clear usage boundaries.

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

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

Description adds value beyond annotations: specifies that it returns full file contents as text, details returns (CSV rows or GeoJSON FeatureCollection with fields like DCPI score, target MW, market, coordinates, notes). No contradictions with readOnlyHint, idempotentHint, destructiveHint.

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

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

Description is well-structured with clear directives and examples, though slightly verbose. Could be trimmed slightly but still effective.

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

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

For a tool with one parameter and no output schema, the description fully covers purpose, parameter details, return format, and fields. No gaps given low complexity.

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

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

Schema coverage is 100% but description adds meaning: notes default format is 'csv' and provides context for 'geojson' (GIS tools like QGIS), enhancing understanding beyond the schema.

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

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

The description clearly states the tool exports saved DC Hub shortlists for offline use, gives an example, and distinguishes from siblings 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?

Explicit usage guidelines: use for bulk-download when user wants offline analysis; do not use for in-chat listing or saving new sites. Names alternatives list_saved_sites and save_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 indicate read-only, idempotent, non-destructive. Description adds specific return fields and that it's a citable summary, providing extra 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?

Two concise sentences with front-loaded purpose and efficient detail.

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

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

Given low complexity (1 param, no output schema), description sufficiently explains return fields and how to get more data via alternative tool or URL.

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

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

Schema covers the id parameter fully with description; description adds no new parameter info beyond schema, so baseline 3.

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

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

The description clearly states the tool fetches a DC Hub record for an ID from the search tool, and distinguishes it from get_facility by noting the return format and alternative.

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

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

Explicitly tells when to use the tool (after search) and when not to (for full specs, use get_facility or open URL).

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

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

Annotations already declare read-only, idempotent, non-destructive. Description adds return format (similarity_score, match_reasons, key_differences) and ranking behavior.

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

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

Two sentences plus a param summary, no fluff. Front-loaded with purpose, then example, then constraints. 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?

Covers all key aspects: purpose, when to use, return shape, and exclusions. Minor gap: no mention of matching on optional dimensions (match_on) but output schema is not provided so it's acceptable.

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

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

Schema coverage is 100% so baseline is 3, but description adds an unlisted parameter (capacity_mw) and implies 'name' as a param while schema only has facility_id, causing potential confusion. Value added is partially offset by inaccuracy.

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?

Explicitly states finding similar nearby options for a facility, distinguishes from siblings like score_facility and compare_sites via concrete exclusions.

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 (likes one facility, wants alternatives) and when not (scoring or head-to-head comparison), 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?

While annotations already indicate readOnlyHint=true and non-destructive behavior, the description adds critical context: the PDF URL is valid for ~7 days, no login needed, and details the return structure including survey fields. This goes well beyond the annotations.

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

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

The description is well-structured—starting with purpose, then example, then parameter details, then return value. However, it is slightly verbose, repeating some information (e.g., lat/lon ranges). A bit more trimming could improve conciseness.

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

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

Despite 10 parameters, no output schema, and no nested objects, the description is comprehensive: it covers all parameters, provides an example, details the return structure, gives usage notes, and explains when to use this tool versus the alternative. It fully equips an AI agent to select 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 100%, but the description adds meaningful value beyond the schema by explaining which parameters are required (lat/lon despite not being marked required in schema), providing aliases (lng, latitude, longitude), and giving context like latency_target defaulting to nearest carrier hotel. Example usage further clarifies 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?

The description clearly states it generates a shareable, branded multi-page Site Analysis PDF for one lat/lon. It uses specific verbs and resources (generate, site analysis PDF) and explicitly distinguishes itself from sibling tool 'analyze_site', which only returns a numeric score.

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

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

The description explicitly says 'Use when a user wants a SHAREABLE, branded multi-page Site Analysis PDF' and directly names the alternative 'For just the numeric suitability score (no PDF), use analyze_site instead.' This provides clear context and exclusion.

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

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

Annotations already declare readOnlyHint true, idempotentHint true, destructiveHint false. The description adds context that it is a curated index (not live telemetry), which provides behavioral nuance beyond the annotations. No contradictions.

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

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

The description is moderately concise with clear front-loading of purpose. It includes a helpful note and alternative, but could be slightly trimmed. Still, 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 no parameters, no output schema, and the complexity of describing a curated index, the description covers purpose, content, examples, limitations, and alternatives completely. The agent can fully understand when and why to use this tool.

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

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

The tool has zero parameters; schema coverage is 100%. The description correctly implies no input is needed. Since there are no parameters to document, baseline 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 it is a curated roster of AI platforms and agent frameworks, specifying what it contains (platforms, recommended tools, auth tier) and distinguishing it from unrelated tools like get_backup_status. The verb+resource is specific, and examples (Claude, Cursor) clarify scope.

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

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

The description explicitly tells the agent to use it to see supported platforms and how to connect them, and also warns against using it for uptime/backup health, providing the specific alternative get_backup_status. This is excellent when-to-use and when-not-to-use 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 provide readOnlyHint, idempotentHint, destructiveHint. The description adds detailed behavioral context: what metrics are included (backup status with time/integrity, data freshness with color codes, heartbeat score, call volume, cadence), and emphasizes the tool is for platform 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?

The description is reasonably concise for the amount of information conveyed. It front-loads the key outputs and includes usage guidance. The phrase 'Try: get_backup_status' is slightly redundant but not harmful. 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 no output schema, the description thoroughly explains return values: backup status (last successful, age, integrity check), data freshness across 49 sources (green/yellow/red), agentic heartbeat score (0-100), MCP call volume, and DCPI cadence. It also includes usage context and sibling tool distinction, making it fully informative for an agent.

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

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

Input schema has 0 properties, so no parameters to describe. Schema description coverage is 100%. Baseline for 0 params is 4. The description does not need to add parameter info.

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 platform health metrics including backup status, data freshness, agentic heartbeat, MCP call volume, and DCPI cadence. It distinguishes itself from sibling 'get_changes' by specifying it is for platform/infra health, not specific dataset freshness.

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 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; use get_changes'). Provides an alternative tool name.

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, idempotentHint, and non-destructive. The description adds significant behavioral context: caching generated_at for next call, returning portfolio block for keyed callers, and specific data types. No contradictions.

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

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

The description is dense but every sentence adds value. It front-loads the core purpose, then details return content and usage. No fluff or repetition.

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

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

Without an output schema, the description thoroughly explains return content. It covers the key outputs and the conditional portfolio block. It omits error handling or edge cases, but for a read-only tool with good annotations, this is sufficient.

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

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

Schema already describes both parameters well (100% coverage). Description adds extra meaning: default for 'since' is 24h, shorthand values, and the practice of passing back generated_at. This enriches the parameter semantics beyond schema.

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

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

The description clearly states the tool's purpose: incremental sync to pull only changes since a timestamp. It explains the specific data returned (DCPI movers, new facilities, M&A deals) and distinguishes from a full fetch. The verb 'get' aligns with resource 'changes'.

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

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

The description explains when to use (to avoid re-fetching all data) and how to use (pass since parameter with ISO-8601 or shorthand). It implies not to use for full data sync. However, it does not explicitly state when not to use or list alternatives among siblings.

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

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

Goes beyond annotations by disclosing that all values trace to federal sources, missing data is declared unavailable (never estimated), radius behavior beyond 25 km returns 'unavailable_exceeds_radius', and seismic is US-only. No contradiction with readOnlyHint or idempotentHint.

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

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

Well-structured with clear front-loading: first sentence captures purpose. Each sentence adds value (sources, example, return shape, behavior, alternatives). Slightly lengthy but efficient; 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 complexity (nested return, multiple data sources), the description is comprehensive. It details the return shape, data availability handling, geographic scope, and alternatives. Without an output schema, the description fully compensates.

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

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

Schema coverage is 100%, so baseline is 3. Description adds context beyond schema: explains that radius_km defaults to 25 and its behavior, and that lat/lon are site coordinates. Also mentions aliases but schema already lists them. Adds value but not dramatically.

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 seismic and climate intel for a lat/lon, explicitly tying it to data-center structural bracing and cooling design. It distinguishes from siblings by naming alternatives (get_disaster_risk, get_composite_site_score) and specifying data sources (USGS ASCE 7, NOAA).

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 seismic + climate intel for data-center design. Provides when-not: for natural-hazard ratings use get_disaster_risk, for blended verdict use get_composite_site_score. Includes an example call and details on radius and geographic limitations.

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

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

Beyond annotations (read-only, idempotent), description discloses critical behaviors: it only scores over validated factors, never imputes missing ones, lists which factors are live, and explains that water is 'unavailable' only outside basin coverage. It also clarifies the return structure including verdict and coverage map.

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 efficient and front-loaded: starts with purpose, then contrasts with siblings, gives an example, and enumerates the return format. Every sentence adds value, no fluff.

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

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

Given the tool has no output schema, the description completely covers return values (composite_score, verdict, confidence, coverage map, etc.), explains the factors, and handles edge cases like unavailable factors. It also addresses parameter aliases, making it fully self-contained.

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

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

Schema coverage is 100%, so baseline is 3. The description adds a usage example but does not provide additional parameter semantics beyond what the schema already describes. The example is helpful but not a semantic addition.

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

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

Description states clearly that the tool provides a single 0-100 site suitability/risk verdict with per-factor coverage, and distinguishes it from sibling tools like analyze_site and compare_sites. The verb 'scores' and resource 'composite site score' are specific and informative.

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

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

Explicitly states when to use this tool ('when a user wants ONE honest 0-100 site suitability/risk verdict') and when not to use it, providing direct alternatives: 'Use analyze_site for full data, compare_sites for 2-4 sites, rank_markets for whole-market ranking.' This is clear guidance.

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

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

Discloses output structure (top_markets, candidate_facilities, factor_breakdown, summary_text, citation_url) beyond annotations. Annotations already indicate readOnly and idempotent, which are consistent. 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?

Every sentence adds value. Purpose is front-loaded, followed by example, parameter explanation, output structure, and usage exclusions. 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?

Given complexity and absence of output schema, the description is remarkably complete: covers input, output, usage boundaries, and examples. 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?

Adds meaning beyond the schema: explains the 'context' parameter as free-text including MW, geography, workload, etc., and gives an example. Schema coverage is 100%, but description enriches it.

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's purpose: to answer open-ended siting questions with a single call, providing a ready-to-quote answer. Distinguishes from siblings like analyze_site and rank_markets by specifying when not to use them.

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

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

Explicitly describes when to use ('when a user asks an open-ended siting question') and when not to use ('Do NOT use for a single specific lat/lon or to rank by ONE criterion only'). Also provides 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, idempotentHint, destructiveHint. Description adds: live query (never estimated), returns coverage field indicating data availability, county-level resolution, and detailed output structure. 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?

Description is informative and front-loaded with purpose, but includes detailed output structure and caveats which lengthens it. Still efficient, every sentence adds value.

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

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

Despite no output schema, the description fully documents the return structure with keys, types, and ranges. It covers coverage handling, resolution, and source. Sufficient for accurate invocation.

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

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

Schema has 100% coverage with aliases documented. Description adds an example call and clarifies alias relationships (lng for lon, etc.), providing extra user guidance beyond the schema.

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

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

Description explicitly states the tool returns natural-hazard/disaster risk for a lat/lon, lists specific hazards (flood, wildfire, etc.), and cites authoritative source (FEMA NRI). It distinguishes from sibling tools like get_water_risk and get_composite_site_score.

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: for disaster risk of a lat/lon. Explicit alternatives: for water stress use get_water_risk, for composite score use get_composite_site_score. Also notes coverage limitations for points outside US NRI.

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 and idempotentHint. Description adds attribution requirement and specific return fields, adding value 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 usage context and includes example. Slightly long but efficient, 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 3 params, no output schema, and rich annotations, the description covers purpose, usage, exclusions, attribution, and example, making it fully adequate.

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

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

Schema description coverage is 100%. Description clarifies iso as required (though schema marks no required params, a minor inconsistency) and provides an example. Adds modest value.

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

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

The description clearly states the tool provides live energy pricing for 7 US ISOs and explicitly distinguishes from siblings (get_grid_data, get_grid_intelligence, get_gas_economics).

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?

Begins with 'Use when...' and explicitly states what NOT to use it for, listing alternatives and specific exclusion criteria.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds valuable context by detailing the response fields (power capacity, cooling type, etc.) and confirming it returns exactly one facility, which augments the annotations 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 well-structured, starting with a clear purpose statement followed by a list of fields and usage examples. It is slightly longer than necessary but remains efficient and front-loaded.

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

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

Given no output schema, the description adequately lists expected response fields, clarifies the single-facility return, and distinguishes from search_facilities. All necessary context for correct agent selection and invocation is provided.

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

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

Schema description coverage is 100%, so the schema already documents each parameter. The description adds light context by noting that id, slug, and name are alternative lookups and including example values, but does not significantly deepen parameter understanding.

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

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

The description clearly states it returns 'full metadata for one facility' and lists specific fields (name, operator, address, etc.), with a distinct verb and resource. It also explicitly differentiates from the sibling 'search_facilities' by stating 'do NOT use to search or list many facilities'.

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

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

The description provides explicit usage examples ('Try: get_facility id=equinix-dc1-ashburn') and clearly states when not to use this tool (for searching/lists, use search_facilities). It also identifies the primary lookup parameters (id, slug, name).

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context: explaining that only DCPI market-health has temporal series, static dimensions are declared static, and coverage is unavailable when no snapshot history exists. This goes 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 well-structured: usage guidance first, then return info, integrity notes, and params. It is concise for the amount of information delivered, though the integrity section could be slightly trimmed. Front-loading the use case is 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?

Given the tool's complexity (temporal delta, multiple dimensions, static vs dynamic), the description covers the return shape, integrity constraints, and alternatives. Missing output schema is compensated by an inline return structure example. Could mention error cases or requirement to specify either facility_id or market.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by clarifying the mutual exclusivity of facility_id and market (using 'OR') and providing a default for 'since' (7d) and examples of valid values, enhancing parameter understanding.

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

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

The description explicitly states the tool's purpose: detecting temporal changes in a facility's or market's risk profile. It uses specific verbs like 'what has CHANGED' and 'returns REAL DCPI market-health delta' and clearly distinguishes from static-trained models and point-in-time alternatives.

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

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

The description provides explicit when-to-use guidance ('temporal question static-trained models can't answer') and when-not-to-use guidance by naming specific alternative tools (get_composite_site_score, get_disaster_risk, get_climate_intel) for point-in-time 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds details: returns GeoJSON FeatureCollection with specific properties, and example shows it's a mapping tool. 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 thorough but well-structured: purpose, example, parameter explanations, return format, and exclusions. Could be slightly shortened without losing value, but front-loaded effectively.

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 compensates with full GeoJSON structure and property details. Addresses alternatives among 60+ siblings. All parameters explained with context. Complete for a query 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 covers all 4 parameters with descriptions (100% coverage). Description adds usage patterns: lists carrier enums explicitly, explains market parameter with pairing suggestion, and gives concrete 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?

Description starts by specifying exactly when to use the tool: scoring fiber depth, mapping long-haul routes, assessing dark-fiber availability. Example usage distinguishes it from siblings 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?

Explicitly states do-not-use cases: 'Do NOT use to count fiber providers at a single facility (use get_facility) or for IX interconnection-density scores (use analyze_site).' Also provides affirmative use cases and 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 indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds detailed return object shape (score, near_net_bucket, nearest_carrier_km, carrier_count, top_carriers, single_carrier_risk, etc.). 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 front-loaded with the core purpose, followed by an example, parameter details, return structure, and exclusions. Every sentence serves a clear purpose with no wasted words.

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

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

Despite no output schema, the description details the return object fields and distinguishes from sibling tools. It addresses the single-site use case completely, given context signals show 100% schema coverage and annotations provide additional context.

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

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

Input schema covers all 6 parameters with descriptions (100% coverage). The description adds value by specifying ranges (lat -90..90, lon -180..180, radius_km 5-200), defaults (radius_km default 50), and clarifying aliases (lng, latitude, longitude). Also states lat and lon are required, though schema doesn't enforce it – a minor inconsistency but still additive.

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

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

The description clearly states the tool provides a fiber-readiness verdict for one parcel/site using lat/lon. It uses a specific verb 'get' and resource 'fiber_readiness', and differentiates from siblings like get_fiber_intel (for routes) and analyze_site (for multi-factor scores).

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

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

Explicitly says 'Use when you need the FIBER-READINESS / connectivity verdict for ONE parcel or site' and provides a concrete example. It then lists exclusions: 'Do NOT use to map carrier ROUTES between metros (use get_fiber_intel) or for a full multi-factor site suitability score (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, idempotentHint=true, destructiveHint=false, covering safety. The description adds behavioral context: it computes economic scenarios, returns a specific structure, and requires a market slug from another tool. No contradictions. While it doesn't detail rate limits or auth, the annotations sufficiently cover the behavioral profile, and the description adds meaningful output and usage 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?

The description is around 120 words, which is appropriately sized for a moderately complex tool. The main purpose is stated first, followed by parameter instructions and output structure. It is clear but could be slightly more structured (e.g., bullet points for the return fields). Still, every sentence contributes value, and there is no wasted wording.

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

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

Given no output schema, the description fully enumerates the return fields ('{market, henry_hub_spot_usd_mmbtu, ... scenarios_usd_per_mwh: {new_ccgt_6400, ... custom}, data_basis}'). It links to related tools (get_gas_index, get_grid_data) and covers optional parameter usage. For a tool with two parameters and complex output, this description is highly complete and self-contained.

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

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

Schema coverage is 100% (both parameters have descriptions), so baseline is 3. The description adds value beyond the schema by explaining that the optional heat_rate_btu_per_kwh is for a 'custom scenario' and providing examples ('e.g. 6800 (avg CCGT)'). It also gives the operational context that the output is 'the number a BTM developer compares against a grid PPA', which clarifies the meaning of parameters in a real-world scenario.

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 computes 'Behind-the-meter / gas-fired power ECONOMICS' for US data-center markets, listing specific output metrics. It explicitly distinguishes from sibling tools by saying 'Do NOT use for the electricity grid fuel mix (use get_grid_data) or the per-state gas suitability score (use get_gas_index)'. This provides unambiguous purpose and differentiation.

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

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

The description tells when to use the tool ('a BTM developer compares against a grid PPA') and when not to (listed exclusions with explicit alternatives). It also notes that it 'Pairs with get_gas_index' for further context. The parameter descriptions in the schema (reproduced from the description) clarify that market slugs come from rank_markets/get_market_dcpi_rank, providing clear prerequisites.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds detailed output fields (dcgi, gas_access_score, etc.), the verdict system, and attribution requirements. 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 moderately long but every sentence serves a purpose (definition, usage modes, exclusions, attribution). It is front-loaded with the acronym explanation. Minor wordiness reduces conciseness slightly.

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

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

No output schema exists, so the description fully compensates by listing all return fields (dcgi, gas_access_score, etc.) and explaining both single-state and national modes. It also covers attribution requirements and use-case scope.

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

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

Schema coverage is 100% but the description adds significant meaning: it explains that omitting 'state' yields a national ranking, mentions the optional 'limit' parameter's range, and provides an example invocation. This goes well beyond the schema's 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 retrieves the Data Center Gas Index (DCGI), a per-state natural-gas suitability score. It distinguishes itself from siblings by being the 'gas analog to DCPI' and explicitly contrasts with electricity grid or live pricing tools.

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

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

The description provides explicit when-to-use and when-not-to-use guidance, including which sibling tools to use instead (get_grid_data, get_grid_intelligence, get_energy_prices). It also gives a concrete example 'Try: 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 declare readOnlyHint, idempotentHint, destructiveHint. The description adds transparency on return fields, null handling ('never fabricated'), omitted data (gas storage, LNG, firm pipeline capacity) with reasons, and per-field data_basis labels. 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 front-loaded with purpose and usage, then lists components and return fields. It is comprehensive but slightly lengthy; a more concise summary could be achieved without losing critical details. However, it earns its length by providing necessary context.

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, lack of output schema, and 100% schema coverage, the description is highly complete. It explains return fields, omitted data, null handling, and provides example queries, enabling the agent to fully understand the tool's capabilities and limitations.

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

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

Schema coverage is 100% (both parameters described in schema). The description adds value by specifying accepted formats (e.g., 'TX', 'Texas', 'Virginia'), noting an alias ('state' for 'region'), and implying the parameter is required (though schema says 0 required, which is a minor inconsistency but not harmful).

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: 'Use when a human asks about gas-fired or behind-the-meter power economics for a data center in a US state.' It distinguishes itself by explicitly mentioning it is the GAS analogue of get_grid_intelligence and specifies not to use it for electricity grid headroom or DCGI score alone, referencing 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?

The description provides explicit when-to-use guidance with example queries, and when-not-to-use with specific alternative tool references (get_grid_intelligence, get_gas_index). This leaves no ambiguity for the agent.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, indicating safe read-only behavior. The description adds that data is 'raw real-time telemetry for one ISO', providing context beyond annotations. No contradiction exists.

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

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

Single sentence that is tightly packed with essential information, front-loading the purpose and scope. Uses parentheses for exceptions and alternatives efficiently, with no wasted words.

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

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

Covers scope (7 ISOs), metrics, data source (EIA hourly RTO), and exclusions. Lacks explicit mention of output format, but for a real-time telemetry tool, the description is sufficient for an agent to decide. Good given no output schema.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the iso parameter with examples ('Pass iso=PJM') and mentioning typical metrics, but does not provide extensive additional semantics beyond the schema's property descriptions.

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

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

Clearly states the tool provides real-time electricity grid data for 7 US ISOs, specifying the exact metrics (fuel mix, demand, 24h demand curve). It distinguishes from sibling tools by explicitly stating when not to use it and suggesting alternatives like get_grid_intelligence or get_energy_prices.

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 guidance: requires iso parameter (with examples), warns against using for power-availability or pricing analysis, and directs to specific alternatives (get_grid_intelligence, get_energy_prices, get_grid_scoreboard). This helps the agent choose correctly.

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 and idempotentHint=true, but the description adds rich behavioral context: how balancing authorities differ from ISOs, special case for PJM-DOM, and the exact return fields. No contradiction.

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

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

The description is detailed but well-structured, front-loaded with the primary use case. It could be slightly shorter, but every sentence adds value given the complexity of the tool.

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

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

Despite no output schema, the description lists all return fields and explains regional nuances. Together with aliases and constraints, it fully equips the agent to use the tool correctly.

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

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

Schema coverage is 100% and the description adds significant meaning: explains that iso and region are aliases, lists valid values, and gives a concrete example. This goes beyond what the schema provides.

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

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

The description provides a specific use case phrase ('can I get N MW of power...') and an example, making it crystal clear what the tool does. It also distinguishes itself 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?

Explicitly states when to use (single-ISO queries for capacity and timeline) and when not to use (comparisons or global rankings), naming alternative tools. This is ideal 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?

Beyond annotations (readOnlyHint, idempotentHint), the description discloses live data, sources, limitations (e.g., Brazil no gas share, Australia/Singapore unranked), and attribution requirements. This adds valuable 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?

The description is comprehensive but verbose, with multiple parentheticals and a long final sentence listing sources. It could be more concise while retaining 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?

For a zero-parameter tool with no output schema, the description fully covers what the tool returns: grids, metrics, ranking order, sources, and limitations. No gaps remain.

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

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

With zero parameters and 100% schema coverage, baseline is 4. The description adds no parameter info (unnecessary) but provides rich detail on output semantics, which is sufficient for this parameterless tool.

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

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

The description clearly states the tool provides a live global grid scoreboard ranking grids by renewable and gas shares and fuel mix. It explicitly distinguishes from sibling tools compare_isos and get_grid_data, making the purpose unambiguous.

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

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

The description provides explicit guidance on when to use this tool (e.g., to find the greenest or most gas-reliant grid for siting a data center) and when to use alternatives (compare_isos for pairwise, get_grid_data for single ISO).

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 and idempotentHint, and the description adds context about the data source (HIFLD/EIA) and return structure (distance + capacity). No contradiction; the description complements the annotations well.

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 with a clear structure: purpose, asset types, return details, example, and usage caveat. It earns its place but could be tightened slightly.

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

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

No output schema, but the description mentions return values (distance + capacity) and data joining. Given the complexity of multiple asset types, this provides sufficient context for the agent to understand what to expect.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds an example with lat=33.45, lon=-112.07, radius_km=25 but does not expand on parameter behavior beyond what the schema provides. Adequate but not exceptional.

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

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

The description clearly states it returns nearby infrastructure assets (substations, transmission lines, pipelines, power plants) for a location, and explicitly distinguishes from analyze_site by warning against using it for a single 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 explicit example usage with lat, lon, radius_km and clearly states when not to use it (do NOT use for a single scored site-suitability verdict, use analyze_site). This helps the agent choose correctly among siblings.

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

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

Annotations already set readOnlyHint, idempotentHint, and destructiveHint. The description adds details on real-time nature, return fields (index, percentile, trends, components), and single-market scope, fully disclosing behavior.

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

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

Four sentences efficiently convey purpose, return data, usage example, and alternative tools. Front-loaded and 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?

While the description covers high-level purpose and return values, the critical mismatch between suggested parameters and schema undermines completeness; an agent cannot correctly invoke the tool based on provided info.

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 description suggests a 'market' parameter with an example, but the input schema defines no properties. This contradiction misleads about required inputs, making parameter semantics poor despite 100% 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 tool returns a composite market health score (0-100) and distinguishes it from siblings like get_market_intel and rank_markets, making its purpose unambiguous.

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

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

Explicitly provides usage context with an example call and warns against using for full market metrics or ranking, guiding the agent to appropriate alternatives.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description adds value by detailing what data is returned (generation capacity, ERCOT's data center load) and sources. It could mention potential limitations like data update frequency or pagination, but overall adds 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 detailed but front-loaded with the core purpose. Each sentence adds value, though it could be slightly more compact. Still, it is well-structured and informative without being excessively 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 output schema, the description explains the main return fields (queued_load_total_gw, queued_load_data_center_gw) and provenance. However, it does not specify the full output structure (e.g., whether other fields exist like timestamps or subregion breakdowns). Adequate but could be more complete.

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

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

Schema already describes the iso parameter with 100% coverage, but the description adds that passing iso=ERCOT returns additional fields (queued_load_data_center_gw). This extra semantic detail goes beyond the schema, justifying a score above baseline 3.

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

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

Description clearly states it provides an ISO interconnection queue snapshot of total queued generation capacity. It distinguishes from siblings by explicitly naming alternatives (get_grid_intelligence, grid_transition_radar) and 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?

Explicitly says when to use (queue-depth site-selection and AI/data-center-load saturation intel) and when not to use (single-site time-to-power or forward-looking emergence), naming specific alternative tools. 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 indicate readOnlyHint, idempotentHint = true, which the description does not contradict but instead adds valuable behavioral details: the token-budgeted filling order, return structure with sections, omitted field, and citation info. This goes beyond annotations to describe exactly how the tool behaves.

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

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

The description is front-loaded with purpose, then details behavior, output format, and parameter specifics, followed by exclusions. Every sentence adds value; the length is justified by the tool's complexity. No redundant or tautological phrases.

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

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

Given no output schema, the description fully compensates by detailing the return structure (sections with id, title, text, tokens, as_of, cite; used_tokens; omitted). It provides example invocation, parameter constraints, and context signals. No gaps remain for agent comprehension.

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

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

Schema description coverage is 100%, but the description adds specific enum values for 'iso' (e.g., ERCOT, PJM) and numeric bounds for 'max_tokens' (200-8000), plus a default. It also summarizes the return object structure, providing 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 starts with a clear verb phrase 'Use when an agent needs a WHOLE-grid briefing it can drop straight into its context window', specifying exactly what the tool does and the resource (grid context for US ISOs). It explicitly distinguishes from sibling tools by listing alternatives like get_grid_data, get_grid_intelligence, compare_isos, and get_grid_scoreboard, making the purpose unambiguous.

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

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

The description provides explicit guidance on when to use ('when an agent needs a WHOLE-grid briefing') and when not to use, with direct references to specific sibling tools for alternative uses. It also includes an example call, making the usage context very 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 readOnlyHint, idempotentHint, destructiveHint = false. The description adds context beyond annotations: explains greedy filling under max_tokens budget, priority ordering, and return structure (sections with token counts, as_of, cite). 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, followed by example, params, return structure, exclusions. Slightly verbose but each sentence serves a purpose. Well-organized.

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

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

No output schema, but description explains return format (sections object). Includes example, params, exclusions. Complex tool with good coverage; minor lack of error handling info but overall complete.

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

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

Schema coverage is 100% (both params described). Description adds operational context: market is required (though schema missing required array), valid slugs come from rank_markets; max_tokens range and default, and priority order. Adds value beyond schema.

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

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

The description clearly states it provides a 'whole-market briefing' with a structured context pack (sections with token counts, as_of, cites). It distinguishes from siblings by naming alternatives: 'Do NOT use for a single metric (use get_market_dcpi_rank), the raw structured metric set (use get_market_intel), or cross-market ranking (use rank_markets); this is the narrative briefing pack.'

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 an agent needs a WHOLE-market briefing' and when not to: 'Do NOT use for a single metric, raw structured metric set, or cross-market ranking.' It names specific alternative tools for those cases.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds value by mentioning the narrative block's content, length (~100 words), and licensing (CC-BY-4.0), which is helpful but not critical beyond annotations.

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

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

Two sentences, no wasted words. The first lists all output components, the second gives usage context + citation instructions. Perfectly structured for quick scanning.

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 outputs (verdict, scores, narrative). It covers the narrative's length, style, and licensing. Could briefly explain the scores' meaning, but the level of detail is sufficient for an agent to understand what to expect.

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 only one parameter and 100% schema description coverage, the baseline is 3. The description adds value by specifying that valid slugs come from rank_markets or get_market_dcpi_rank, providing guidance on parameter selection beyond the schema.

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

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

The description clearly states the tool provides a DCPI rank for a single market with a verdict, composite score, and narrative block. It explicitly distinguishes from similar tools like rank_markets and compare_isos, making its purpose unambiguous.

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

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

The description explicitly says when to use (answer 'should I build here?') and when not to use (ranking many markets or comparing ISOs), with clear alternatives provided (rank_markets, compare_isos). This is exemplary usage guidance.

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

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

The description goes beyond annotations by detailing the return object structure (market, country, capacity_mw_total, etc.). It also specifies the constraint of querying a single market. Annotations already mark the tool as read-only and idempotent, so the description adds context on output shape and usage 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 concise yet comprehensive, with clear structure: usage context, example, parameter explanation, return object list, and exclusions. No redundant sentences.

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

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

Given 4 parameters, 100% schema coverage, and no output schema, the description fully explains the return format and usage context. It covers when to use, how to use, and what to expect, making it complete for the tool's complexity.

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

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

Schema description coverage is 100%, so parameters are well-documented in the schema. The description provides an example for the 'market' parameter and lists the return fields, but does not add significant new semantics for 'metric', 'period', or 'compare_to' beyond what is in the schema.

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

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

The description explicitly states 'Use when a user asks about ONE data-center market' and provides concrete examples. It distinguishes from sibling tools by specifying 'Do NOT use to rank multiple markets (use rank_markets) or for a single facility (use get_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?

Clearly indicates when to use (single market query) and when not to use (ranking, facility). Includes an example invocation and mentions alternatives like rank_markets and get_facility.

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

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

Annotations already indicate read-only, non-destructive, idempotent behavior. The description adds context on dual-mode output (with/without market parameter), data source citation, and field lists, going beyond annotations 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 dense but front-loaded with purpose. It includes examples, exclusions, and return structure in a single paragraph; minor improvement could be structuring into sections, but no wasted sentences.

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

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

Despite no output schema, the description fully explains both return formats, lists key fields, notes citation, and excludes sibling tools. Complete for the tool's complexity and context.

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

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

Schema covers the single optional parameter with description. Description adds value by clarifying market name/slug format, providing examples, and explaining omission behavior, exceeding schema scope.

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

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

The description clearly states the tool's purpose: retrieving metro-level fiber profiles for US data-center markets, with specific actions (ranking or deep dive). It distinguishes from siblings by explicitly excluding parcel-level and route geometry tools.

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

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

Provides explicit when-to-use scenarios with examples, and when-not-to-use with named alternatives (get_fiber_readiness, get_fiber_intel). Also includes citation requirements.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, indicating safe read-only behavior. The description adds value by specifying the update frequency (every 30 min) and that it extracts market/operator entities. 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 two concise sentences plus an example and exclusion note. It is front-loaded with the core purpose and uses no superfluous 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?

Given 7 parameters and no output schema, the description adequately explains return fields and filtering capabilities. It covers what the tool returns and how to use it, though it could mention the default limit or pagination behavior.

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

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

Schema coverage is 100% with descriptions for all 7 parameters. The description adds limited additional meaning beyond the schema but includes a helpful usage example that demonstrates parameter combination, slightly exceeding the baseline of 3.

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

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

The description clearly states the tool retrieves curated data center industry news from 40+ trade sources, refreshed every 30 minutes. It specifies the return fields (title, summary, source, published_at, entities) and distinguishes itself from sibling tools like list_transactions and get_pipeline for structured data.

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

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

The description provides explicit guidance: filter by topic (deals/permits/outages/policy/AI), includes an example query 'get_news topic=AI limit=10', and explicitly warns against using for structured M&A deal data (use list_transactions) or construction pipeline (use get_pipeline).

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