DC Hub — Data Center & Energy Intelligence

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v2.12.7
Disambiguation2/5
Several tool clusters have heavily overlapping purposes despite detailed descriptions: analyze_site, get_composite_site_score, score_facility, compare_sites, and rank_sites all produce 0-100 site/facility scores; search, search_facilities, search_intelligence, and semantic_search all perform search. The extensive 'Do NOT use X (use Y)' guidance helps but an agent can easily misselect among 82 tools with such similar names and functions.
Naming Consistency4/5
Tool names overwhelmingly follow a consistent snake_case verb_noun pattern (get_*, search_*, analyze_*, compare_*, etc.), making the naming predictable. A handful of noun-only names (hyperscaler_deals, site_selection_canvas, grid_transition_radar, deal_autopsy, ai_capacity_index, why_dchub) deviate from the verb-first pattern, but they are still readable and the overall style is uniform.
Tool Count1/5
82 tools is an extreme count for any server, even a broad data-center intelligence platform. Many tools could be consolidated (e.g., the four search tools, five site-scoring tools, and four grid-data tools), and the sheer number will overwhelm agents and increase routing errors. This far exceeds the 25+ threshold for 'too many'.
Completeness4/5
The tool surface covers the data-center intelligence domain comprehensively: facilities, construction pipeline, market rankings, grid telemetry, power generation, interconnection queues, hosting capacity, fiber, gas, water, climate, disaster, tax, permitting, deals, news, saved sites, alerts, and meta-planning. Minor gaps exist (e.g., no direct utility interconnection application tool, no cooling-system design tool), but the two withdrawn gas tools honestly point to alternatives, so there are no true dead ends.
Average 4.6/5 across 82 of 82 tools scored. Lowest: 3.6/5.
See the Tool Scores section below for per-tool breakdowns.
- 25 of 29 community issues answered or closed in the last 6 months
- 678 commits in the last 12 weeks
- Last stable release on August 30, 2026
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under MIT License.
This repository includes a README.md file.
Tools from this server were used 6 times in the last 30 days.
This repository includes a glama.json configuration file.
This server has been verified by its author.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower. The description adds useful context by calling the corpus live and saying results are cited records, but it does not disclose result-shaping behavior such as ranking, deduplication, or whether snippets are returned.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no filler. The scope and return type are front-loaded, and the second sentence adds the key querying behavior without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema and rich annotations, the description covers the essential behavior, scope, and cited-result nature. It does not explain how to choose this tool over semantic_search, but that gap is already captured in usage guidelines and does not make the definition incomplete for calling the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents q, limit, query, and corpus. The description only adds that this is natural-language semantic search and lists corpus categories, which mirrors the schema's corpus examples rather than adding new meaning. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific action and resource: semantic search over the DC Hub live intelligence corpus, enumerating the corpus contents (news, M&A deals, facilities, market narratives) and noting that results are cited records. It is clear at call time, but it does not explicitly distinguish itself from the overlapping sibling semantic_search, so it misses the top bar.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool: when a user asks a natural-language question against the intelligence corpus, rather than a structured fact lookup. It does not state when not to use it or mention alternatives such as search_facilities, get_market_intel, or semantic_search, so routing guidance is only implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already carry the read-only, idempotent, non-destructive safety profile, lowering the burden. The description adds genuinely useful behavior beyond that: it returns ranked alternatives with similarity_score, match_reasons, and key_differences versus the target, and it clarifies discovery semantics versus scoring/comparison. However, it stops short of disclosing default radius/limit or empty-result behavior, and it does not surface the silent key-stripping behavior that the schema itself flags.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The structure is sound — use case first, then a worked example, then returns, then exclusions — and the exclusion clause is efficient. But the param-summary sentence is stale and factually wrong against the schema, so one of the four sentences is positively harmful rather than earning its place. Slightly over-packed for what it conveys.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present and 100% param schema coverage, the burden shifts to usage context, which the description covers well: when to use, what it returns, and what to use instead. The critical gap is the inconsistent param list, which could cause an agent to invoke it with invalid arguments (name, capacity_mw) that are silently stripped. For a simple read-only tool this is a notable but not fatal completeness defect.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, giving a baseline of 3, but the description's param summary actively misleads: it advertises 'facility_id or name' and 'optional capacity_mw' while the schema explicitly states 'there is no `name` param; an undeclared key is silently stripped' and contains no capacity_mw property at all. It also omits the real optional params match_on and exclude_operator. An agent following the description would pass phantom keys and get them silently dropped.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description anchors on a specific verb+resource — discovering alternative facilities similar to one seed facility — and illustrates it with a concrete query example ('Find alternatives to the Ashburn QTS campus for about 50MW.'). It also names what it is not (score_facility, analyze_site, compare_sites), so an agent can distinguish it from siblings at a glance.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The trigger condition is explicit and front-loaded ('when a user likes ONE specific facility and wants similar nearby options'), and the exclusion clause names the exact alternatives to use instead ('use score_facility or analyze_site' for single-site scoring, 'use compare_sites' for head-to-head short-list comparison). The closing line — 'this DISCOVERS candidates from a single seed facility' — leaves no ambiguity about when to invoke it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnly, idempotent, and non-destructive behavior. The description adds valuable behavioral context: 'real-time', the aggregation components, and the specific outputs (index value, percentile rank, trend direction, component scores). It does not overstate side effects and aligns with the annotation safety profile.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core definition and returns, and every sentence adds useful detail. It is slightly longer than necessary due to repeated 'one composite health number' language and both an example and a disambiguation clause, but the structure remains clear and scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers output semantics, example usage, and sibling tool routing, and an output schema exists, so return-value documentation is not required. However, the missing/contradictory parameter mechanism for selecting a market leaves a fundamental gap: the agent knows what the tool does but not how to formally supply the required market context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema declares zero parameters, yet the description suggests calling 'get_intelligence_index market=northern-virginia' and describes the tool as returning a score 'for a market'. This mismatch means an agent cannot reliably construct a valid call from the schema, and the description's parameter guidance actively conflicts with the structured input definition.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific resource ('composite market health score'), a concrete scale (0-100), and the underlying components, so an agent knows exactly what the tool computes. It also explicitly contrasts itself with get_market_intel and rank_markets, making sibling differentiation strong.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a concrete invocation example, states what questions it answers, and explicitly says when NOT to use it by naming two alternatives: get_market_intel for the full metric set and rank_markets for ranking multiple markets. This is clear and actionable routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description itself is rich, disclosing HMAC signatures, saving the secret, watermark initialization, delivery failure auto-disable, and ~2h evaluation cadence. However, the annotations declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, while the description documents register/delete actions and stateful webhook behavior, which are mutating and not idempotent. This is a direct annotation contradiction, so the score is 1.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Although long, the description is dense and well structured: it opens with the core value proposition, explains mechanism and required security behavior, provides a runnable example, and ends with exclusions. Every sentence contributes useful information, and the most important operational constraints are front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex 7-parameter tool, the description covers the full lifecycle: how to register, what is returned, how deliveries are signed, failure behavior, evaluation frequency, and when not to use it. The presence of an output schema reduces the need to document return structure, and the description still covers the critical return fields and side effects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 meaningful value beyond the schema: it explains action defaults, maps each kind to its relevant watch parameter, enforces public HTTPS only, and warns that register returns {intent_id, secret}. This goes beyond simple restatement of param names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies a specific resource and action: registering standing intents that trigger HMAC-signed webhook pushes when matches grow, explicitly contrasting this with polling. It also names the sibling alternatives it is not (get_news, list_transactions, set_market_alert), so an agent can distinguish it from related tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit when-to-use guidance: machine-to-machine push notifications for standing queries, with a concrete example invocation. It also states exclusions, directing agents to get_news/list_transactions for one-shot reads and set_market_alert for email alerts, making the decision boundary clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite annotations being sparse (readOnlyHint=false, destructiveHint=false, idempotentHint=false), the description discloses significant behavioral traits: re-minting restarts daily allowance and orphans history, keys are not durable for hosted web clients, OAuth requires a human, and measured statistics on key survival. It contradicts no annotations; annotations correctly flag this as not read-only, not idempotent, not destructive at the boolean level, and the description adds crucial nuance beyond those flags.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely long and densely packed, with multiple all-caps sections and embedded metrics. While every section carries real guidance, the sheer volume makes it hard for an agent to parse quickly, and key operational facts (call when hitting paywall, set X-API-Key, don't re-mint) are buried among cohort statistics and conditional client caveats. It is not concise, though it is structured with ★ markers.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity—two optional params, a return object, and wildly different client contexts—the description covers all necessary branches: OAuth-capable clients, header-capable clients, paste-a-URL connectors, lost-key recovery, and post-mint next steps. The output schema exists, so return values need not be restated, and the description references the key fields (api_key, connect_url, etc.) appropriately. Nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and both parameters are described in the schema, so baseline is 3. The description adds meaningful context: email makes the key recoverable across sessions and is the durable anchor for hosted clients, while client_name is for attribution. It explicitly states the key still mints without an email and that email should only be an address the human explicitly gave. This exceeds schema-only semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: to mint a free DC Hub dev key with one call, returning an api_key to set as X-API-Key. It distinguishes itself from siblings like recover_my_key and unlock_more_data by explicitly naming alternatives. However, the purpose is buried under extensive pre-mint guidance, so an agent scanning for the verb may initially find it less crisp.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit when-to-use guidance: call it the moment you hit a paywall or partial preview, and explicitly says do NOT call it if you already hold a key, naming recover_my_key as the alternative for lost keys. It also provides clear when-not-to-use conditions for OAuth/handshake-capable clients and paste-a-URL connectors, directing those to sign-in or connect_url respectively. This is unusually thorough usage routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, so the description adds value by revealing the output nature: raw nearby assets joined to HIFLD/EIA, with distance+capacity per asset. It doesn't contradict annotations and gives useful context about what the tool does with the data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Dense and front-loaded: the first sentence covers purpose and scope, followed by output details, example questions, an example call, and a guardrail. Slight redundancy with the title, but the structure is efficient and every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Combined with the rich input schema and output schema, the description covers the asset layers, return metrics, data provenance, and the key sibling distinction. It doesn't mention default radius_km, but that is delegated to schema annotations and is a minor omission for a tool this well specified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%: every property has a description. The description adds a worked example and explains radius_km as configurable, but it does not add per-parameter meaning beyond the schema. Baseline 3 is appropriate when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource: 'Nearby infrastructure for a location' and enumerates four asset categories with specific metrics (count, max voltage_kv, distance, capacity). It also explicitly distinguishes itself from analyze_site by labeling its output as raw assets rather than a scored verdict.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides a concrete example invocation and a direct exclusion: 'do NOT use for a single scored site-suitability verdict (use analyze_site)'. This routes agents to the correct sibling for scoring while conveying this is the geo-spatial lookup tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds important behavioral nuance by warning that avg_time_to_power_months and avg_queue_wait_months are different measurements and must be quoted by name — a subtle trap that the schema alone would not reveal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the primary use case and every sentence carries value — example, parameter guidance, return shape, metric warning, and exclusions. It loses one point because some content duplicates the input schema's valid-value list and the output schema's field list.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a comparison tool with a single parameter, annotations, and an output schema, the description is complete: it states when to use, provides a concrete example, explains the difference between two confusing metrics, and explicitly routes the agent away from inappropriate uses. Nothing needed for correct invocation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and already lists the valid ISO values and the 2-4 range. The description repeats this information and adds an example call, but does not add meaningful semantics beyond the schema. This meets the baseline for full schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'side-by-side of 2-4 ISO grids' with the exact comparison dimensions listed. It clearly distinguishes from siblings by naming get_grid_intelligence and get_grid_scoreboard as the alternatives for different use cases.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says when to use: when a user wants a side-by-side in one call instead of N sequential get_grid_intelligence calls. It also provides explicit do-not-use conditions with named alternatives: do not use for global ranking (use get_grid_scoreboard) or single-ISO deep briefs (use get_grid_intelligence).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover readOnly, idempotent, and non-destructive behavior, so the description does not need to repeat those. It adds useful context: one round trip, source EIA-860 + state RPS, the 50-mile radius behavior for lat/lon, and the exact returned shape. This is strong supplementary disclosure 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense and front-loaded with the routing decision, followed by use cases, an example, return fields, and exclusions. Everything earns its place, though the 'one round trip' and 'routing it through the planner would only cost steps' points are slightly redundant.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description fully covers when to use, when not to use, example parameter usage, return structure, data source, and sibling alternatives. With no required parameters and a complete input schema, nothing essential is missing for an agent to call this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 mostly restates what the schema already says: energy_type values, 2-letter state code, and optional lat/lon for nearest projects within 50 miles. The worked example adds minor interpretive value but no real new semantic layer.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific resource and verb: retrieving one US state's renewable fuel mix, capacity, capacity factor, top projects, and RPS target. It clearly distinguishes itself from execute_plan, get_grid_data, and get_grid_scoreboard, so an agent can identify the intended call without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance is included: use for siting, PPA sizing, state fuel mix, and RE100/24-7-CFE feasibility; do not use for live grid generation (get_grid_data) or non-US regions (get_grid_scoreboard). It also warns against routing through execute_plan when a direct call is cheaper, giving clear when/when-not advice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly/idempotent annotations, the description discloses important behavior: refresh=true re-scores against the current baseline, returns saved_score/current_score/score_delta_since_saved, and the explanation lets the agent interpret whether site changes or population changes caused a score delta. It also notes API-key scoping. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense and well-structured: it opens with the action, then explains the key behavior and rationale, then closes with the API-key scoping. Every sentence contributes useful decision-making information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the rich annotations, full parameter schema coverage, and presence of an output schema, the description covers the important behavioral context an agent needs: refresh semantics, score delta interpretation, and scoping. Nothing critical is missing for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds meaningful semantics beyond the schema: it explains the refresh=true default, the re-scoring behavior, the returned delta fields, and contrasts refresh=false as returning saved snapshots. This adds real value for an agent deciding how to set the parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves a saved shortlist and emphasizes the re-scoring behavior, which distinguishes it from simple list/get operations. It does not explicitly name or contrast a sibling tool, but 'Retrieve a saved shortlist (Phase 5)' is specific enough for an agent to understand the core resource and action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear usage context: this is 'the reliable way to maintain a siting campaign across days/weeks.' It explicitly frames when the tool is valuable, although it does not state when not to use it or name alternatives such as list_saved_sites or save_to_shortlist.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, idempotent, non-destructive behavior. The description adds valuable context beyond that: it covers only the tax factor for one US state, returns specific program types, and requires citing the statute with DC Hub attribution.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but well structured and front-loaded with the trigger, example, parameters, return shape, attribution requirement, and exclusions. Most sentences carry useful information, though a few phrases like 'that drive where capex lands' add minor color without critical value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter read-only lookup, the description is complete: it states the return object shape, the program type enum, source attribution, and the boundaries versus sibling tools. No essential calling information is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description mainly restates what the schema says: state is a US state abbreviation and is required. It adds a small example (state=VA) but no meaningful new parameter semantics. There is also a minor mismatch where the description claims required while the JSON Schema's required array is empty.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb and resource: retrieving data-center tax-incentive packages by US state. It also explicitly distinguishes the tool from analyze_site and rank_markets, so an agent can tell which tool is relevant.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives an explicit trigger ('what tax breaks does <state> give data centers?'), a concrete example, and clear exclusions: do not use for combined multi-factor site reads or market ranking. The correct alternatives are named with criteria, leaving no ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly/idempotent/non-destructive hints, the description discloses that the output includes an ISO rollup, grid-headroom leaderboard, and that the transition thesis requires a paid key. It also characterizes the predictive nature of the signal (BUILD verdict + headroom + time-to-power), adding meaningful 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compactly structured: purpose, returns, paid upgrade, predictive positioning, example invocation, and explicit exclusions. Although somewhat long, each sentence serves a distinct function and is front-loaded with the core definition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (2 optional params, no enums, output schema provided) and the description covers purpose, output contents, paid-key behavior, representative example, and routing to alternatives. Nothing needed for correct invocation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents limit and max_months. The description adds only a 'Try: max_months=24' usage example and a semantic tie to time-to-power, which meets the baseline but doesn't deepen parameter meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb+resource: a forward-looking radar that returns emerging US markets+ISOs with a near-term emergence signal. It explicitly distinguishes itself from retrospective reports and names siblings get_interconnection_queue and rank_markets, so there is no ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly tells agents when to use it ('where should I be looking next') and when not to use it, naming alternatives: 'Do NOT use for the current ISO queue snapshot (use get_interconnection_queue) or a present-day market ranking (use rank_markets).' This is strong routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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 covered. The description adds meaningful behavioral context by warning that results are 'INDICATIVE auto-routed road corridors — NOT engineered alignments; subject to survey, DBYD and carrier confirmation'. This discloses uncertainty and limitations beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose, followed by the question it answers, an example, parameter summary, return summary, caveats, and exclusions. It is longer than necessary partly because the parameter recap overlaps with the schema, but every section adds either clarity, usage routing, or caveats, so the length is largely justified.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has an output schema and safety-relevant annotations, the description is complete: it provides an example, explains the core outputs, discloses the indicative nature of the results, and names the sibling alternatives to avoid. Nothing needed to invoke the tool correctly is missing, and the caveat about survey/DBYD/carrier confirmation adds important real-world context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the schema already documents all five parameters clearly, including formats, defaults, and ranges. The description's param recap largely duplicates the schema, though it adds the concrete from/to example and clarifies the relationship between fibre count and cost estimation. This meets the baseline for high schema coverage but does not substantially extend it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb and resource: 'Plan N diverse, road-following fibre lead-in routes' from a candidate site to a carrier hotel/POP. It states the exact question it answers and explicitly distinguishes itself from nearby siblings by saying to use analyze_site and get_fiber_intel for other use cases. The example with concrete addresses further anchors the purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear when-to-use context: answering 'can I get N diverse fibre routes into this site, how far, how much, and where do they share a corridor?'. It also names exclusions and alternatives explicitly: 'Do NOT use for a single site-suitability score (use analyze_site) or fibre-provider footprints (use get_fiber_intel)'. This routes an agent to the correct tool without ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only/idempotent/non-destructive safety, and the description adds rich behavioral context beyond them: the TWO return tiers (tier_1_same_region vs tier_2_cross_region), the drift_is_systemic decision rule with its tactical implication (prefer cross_region vs tactical_ok), the DC Hub reduction note, and API-key scoping. This lets the agent act on results, not just parse them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is longer than average but front-loads the drift trigger and packs every sentence with function: tiers, systemic flag, scope limitation, next step. The middle section is slightly run-on, but there is no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter tool with an output schema, safety annotations, and a decision rule, this is complete: trigger, output shape, interpretation guidance, scope constraints, and how to widen the pool are all covered. Nothing an agent needs to call it correctly or act on its results is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3; both parameters are already well-documented in the schema, including the default for drifted_site_ref (lowest-scoring site). The description reinforces that shortlist_name is scoped to the current shortlist and frames drifted_site_ref as the DRIFTED slot, but adds little syntax-level meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: 'get replacement candidates from the rest of that shortlist' when a saved site DRIFTS. It distinguishes itself from siblings by naming its trigger (get_shortlist refresh or set_shortlist_alert firing) and its scope ('THIS shortlist only'), so an agent can tell it apart from tools like find_alternatives or rank_sites.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The trigger condition is explicit and vivid: use it when a saved site's national standing dropped, surfaced by get_shortlist refresh or a set_shortlist_alert firing, so 'the alert becomes an action' (Phase 5). It references save_to_shortlist for widening the pool, but does not explicitly name exclusions or contrast alternatives like find_alternatives, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context beyond those: refresh cadence ('Refreshed Fridays 14:00 UTC'), composite-score composition ('depth + diversity + power'), and a data-availability caveat ('cooling-type signals where facility data carries them'). 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core ranking purpose, then supplies return fields, refresh timing, use cases, and exclusions in compact sentences. Every sentence earns its place; there is no repetition of the input schema or annotation fields.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with two optional parameters, an output schema, and read-only annotations, the description covers what the tool returns, what the ranking means, when it was refreshed, when to use it, and when to use alternatives. Nothing an agent needs to select or invoke it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the input schema already documents limit and horizon with ranges and defaults. The description adds conceptual framing by tying horizon to '30/60/90 days' and 'deployable_mw,' but it does not add parameter-specific syntax beyond the schema. Baseline 3 is appropriate because the schema carries the parameter-documentation burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'ranks data center markets' by 'where 100MW of AI training capacity can land in the next 30/60/90 days.' It is immediately distinguishable from siblings by explicitly stating what it is not ('Do NOT use for a general best-markets ranking... or forward grid-emergence').
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit use contexts ('AI capex planning, GPU cluster siting, hyperscaler deal forecasting') and explicit alternatives with the condition that selects them: use rank_markets for general best-markets ranking and grid_transition_radar for forward grid-emergence. This leaves no ambiguity about when to invoke this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint true, so the safety profile is covered. The description adds context by specifying the output format, the 'public summary' nature, and the connector format, which goes beyond the bare structured fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no filler. The tool's action and input source are front-loaded, followed by output format and a useful pointer to an alternative. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With one required parameter, an output schema, and read-only/idempotent annotations, the description covers what the tool does, where the id comes from, what it returns, and how to get richer data. No critical gap remains for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the schema already explains the id is a facility slug from a prior search result with an example. The description repeats the same guidance without adding new parameter semantics, matching the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource ('Fetch a DC Hub record for an id') and clearly distinguishes it from get_facility, which provides full structured specs. It also names the sibling search tool as the source of the id, so an agent can tell exactly what this tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It says when to use the tool: for an id returned by the `search` tool, to get a citable public summary. It also explicitly points to the alternative (get_facility or open the url) when full structured specs are needed, making the selection criteria clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds valuable behavioral context: the market filter returns ONLY routes touching that metro, and the response is a GeoJSON FeatureCollection ready for Leaflet/Mapbox. This goes beyond the structured metadata without contradicting it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is longer than average but every sentence carries weight: usage triggers, a worked example, parameter detail, return format, and exclusion guidance are all present. It is front-loaded with the use case and logically organized, though a few clauses could be trimmed without losing meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers usage, parameters, return format, and alternatives. The optional include_sources parameter is only documented in the schema, but that is fine since schema coverage is 100%. No critical operational details like pagination or rate limits are mentioned, but for a read-only GeoJSON tool with high schema coverage, the description is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 enriches this by enumerating all allowed carrier values, the four route_type options, concrete market examples, and the 'either endpoint within ~1.2°' behavior for the market filter. This adds real meaning beyond the schema's brief field descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states specific verbs and resources: scoring candidate sites for fiber depth, mapping long-haul routes between metros, and assessing dark-fiber availability. It explicitly distinguishes itself from get_facility and analyze_site with clear routing to alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use context ('Use when scoring... mapping... assessing...') and explicit when-not-to-use exclusions ('Do NOT use to count fiber providers at a single facility (use get_facility) or for IX interconnection-density scores (use analyze_site)'). This leaves no ambiguity about selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only, idempotent, non-destructive behavior, so the description only needs to add context. It does so by listing the output structure and the notable attribution requirement for quotation under CC-BY-4.0. It doesn't disclose potential failure modes or limits, but that's a minor gap given 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core result, then adds the citation-relevant narrative detail, then the usage and exclusion guidance. Every sentence carries useful information without padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple enough: one fully documented parameter, a rich output schema, and annotations covering safety. The description completes the picture with scope, use cases, exclusions, and attribution instructions, leaving no important gap for an agent deciding to call it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%: the single market_slug parameter is fully documented with examples and a note that valid slugs come from other tools. The description adds nothing param-specific beyond emphasizing 'single market,' so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action and resource: getting a single market's DCPI rank with a defined verdict and numeric scores. It explicitly distinguishes itself from siblings by noting this is ONE market in depth, not rank_markets or compare_isos.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says when to use it ('should I build here?' with structured reasoning and citable prose) and what not to use it for, naming the alternatives rank_markets and compare_isos. This gives an agent clear routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnly, idempotent, non-destructive behavior, so the bar is lower. The description adds valuable behavioral context: the dataset covers 2,000+ deals from 2019-present, values are only included where public, many private deals are undisclosed, and the tool focuses on broad deal flow. This goes well beyond the annotations without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose, then moves through returned fields, filters, example use, and exclusions. Every sentence adds practical value for selecting and invoking the tool, and there is no wasted or redundant content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 10-parameter, filterable transaction-list tool with an output schema, the description covers the domain, return fields, filter options, data limitations, example usage, and sibling exclusions. Nothing critical is missing for an agent to select and invoke this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 all 10 parameters thoroughly. The description adds a useful example (min_value_usd=1000000000) and clarifies the absence of a `year` parameter, but most parameter meaning is properly carried by the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly defines the tool as returning M&A and capital transactions in the data center sector, enumerates the returned fields, and explicitly distinguishes it from hyperscaler_deals and deal_autopsy. An agent can understand exactly what this tool does and how it differs from nearby sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes explicit when-to-use guidance with question examples, a concrete invocation example, and clear exclusions: 'do NOT use for hyperscaler-specific lease/PPA/JV activity (use hyperscaler_deals) or a single-deal post-mortem (use deal_autopsy).' It also warns that there is no `year` parameter, so the agent will not misuse filters.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint=true, idempotentHint=true, destructiveHint=false), the description discloses that the tool is deterministic ('no LLM, no network, same intent always returns the same plan'), free, and safe to log and diff. It also explains the internal routing mechanism ('Deterministic keyword routing over the tool registry'). This adds meaningful behavioral context not already present in annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is thorough but verbose, containing a large block enumerating return fields (e.g., execution_waves, alternatives, coverage_notes, replay structure) even though an output schema exists. This redundancy means not every sentence earns its place. It is front-loaded with the key 'INSPECT-ONLY' warning, but the density and length reduce conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex tool that returns a detailed plan structure, the description covers all necessary context: safety (inspect-only), determinism, cost, when to use versus execute_plan, how to sharpen routing via context hints, and the meaning of args_hint angle brackets. The output schema exists, so the description's omission of formal return specs is acceptable; nothing an agent needs to correctly decide and invoke this tool is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides 100% coverage for both parameters with detailed descriptions (intent examples, context hint keys and the lat/lon routing effect). The description largely repeats the context hint list and adds a note about not inventing args_hint, which relates to output rather than input semantics. With full schema coverage, the baseline of 3 is appropriate since the description adds marginal extra meaning for parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'INSPECT-ONLY — returns the plan WITHOUT running it', clearly distinguishing the tool from execute_plan. It states a specific verb (plan), a resource (query plan), and explicitly contrasts with the sibling that actually runs sequences. The final line 'This tool plans — it never executes' reinforces the scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit when-to-use guidance: 'Reach for plan_query only to review, log, diff or audit a plan before executing it yourself.' It names the alternative execute_plan and the exact condition for choosing it ('For a real multi-step DC Hub question call execute_plan...'). It also mentions discover_tools as an alternative for family-level browsing, leaving no ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds substantial behavioral detail beyond the sparse annotations: it never returns the key over the wire, it emails only the bound address, and the confirmation is identical whether or not a key exists (enumeration-safe). This effectively discloses side effects and privacy/security traits, and it does not contradict any annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is economical and well-ordered: purpose first, then critical behavioral caveats, then when-to-use, then parameter. Every sentence adds essential information without fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers what the tool does, how it behaves, when to use it, and the neutral confirmation return. The output schema exists, so the description need not detail the return shape. Side-effect and security-sensitive behavior are fully explained, leaving no critical gap for an agent to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the schema description already explains the email parameter's role and behavior. The description repeats this ('Pass your human's email...') but adds no new parameter-specific details, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: 'Recover a LOST DC Hub key.' The description clarifies the mechanism (re-sends key to bound email) and the outcome, and the 'LOST' qualifier helps distinguish it from key-creation or binding siblings like claim_free_key and bind_email.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: 'Use this when your human had a key, lost it, and knows the email they bound it to.' This provides clear context, though it does not name alternative tools or state when-not-to-use conditions, stopping short of a full 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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 covered. The description adds useful behavioral context: the score is 'independent,' only existing facilities are eligible, and the score covers seven named dimensions plus composite/tier/peer outputs. No contradiction with annotations exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but every sentence earns its place: use case, example, parameter summary, return summary, and explicit exclusions. The primary trigger is front-loaded, and the no-use cases are clearly separated at the end.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a read-only scoring operation with an output schema and fully documented parameters. The description covers when to use it, what it returns, what the weighting options mean, and which sibling tools to prefer in related but distinct scenarios. Nothing an agent needs to invoke it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents both facility_id and weighting including the default. The description adds a concrete example and restates the weighting options, but it also introduces 'facility_id or name' while the schema only defines facility_id, creating a minor inconsistency. The added value over the schema is modest.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('score'), a specific resource ('ONE existing facility'), and a precise output ('independent 0-100 grade across 7 dimensions'). It also distinguishes itself from siblings like analyze_site, compare_sites, and find_alternatives, so an agent can select it correctly without opening other definitions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description opens with 'Use when a user wants...' and explicitly lists exclusions with alternative tools: raw lat/lon parcels should use analyze_site, multi-site comparisons should use compare_sites, and similar-site searches should use find_alternatives. This gives the agent both positive and negative routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower — yet the description adds substantial behavioral context on top: the honest-404-with-coverage-list failure mode ('never a guess'), the staged hosted-layer rollout (Loudoun County VA first), the representative_point subtlety (centroid of the LARGEST-area member, never the multi-part geometric center which 'can land off-parcel... and poison every point-keyed read'), and the site_evaluation_handoff wiring. These are behavioral traits no annotation could express, including a rationale for a potentially surprising design choice.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense at roughly 190 words, but every clause earns its place: function, both modes, coverage rollout, failure behavior, return fields, handoff target, and sibling routing. It is front-loaded with the core verb+resource and the two-mode explanation. It is at the upper bound of acceptable length, which is justified by the tool's two-mode complexity, but it still demands a full read.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with two invocation modes, a hosted-coverage boundary condition, a multi-field return payload, and fan-out to downstream tools, the description covers every decision an agent needs: both input paths, the failure contract (404 plus coverage list), the key return-field design nuance (largest-area centroid), the handoff pipe into analyze_site + get_water_risk, and exclusions. An output schema exists to carry the formal return structure, and the failure-mode text goes beyond what structured fields could convey.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the schema already documents the mode relationship ('used with lon when geometry is omitted', 'Omit to look up the hosted parcel containing lat/lon instead') and the capacity_mw pass-through. The description reinforces the either/or framing ('pass your own GeoJSON... OR just lat+lon') but adds little meaning beyond what the parameter descriptions already provide, so the baseline-3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Opens with a specific verb+resource ('Structured read of a parcel BOUNDARY') and enumerates two concrete invocation modes: passing a GeoJSON boundary or supplying lat/lon for hosted-layer lookup. It actively differentiates itself from siblings by naming analyze_site (general site score) and get_refined_queue (interconnection queue) as the things it is NOT, so an agent can disambiguate without opening other schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit routing: 'Use when you HAVE a boundary or a point on a specific parcel and want it anchored + sized', then names the alternatives with their selection conditions — analyze_site for a general lat/lon site score and get_refined_queue for interconnection-queue data. It even explains WHY the queue tools cannot auto-join (queue rows carry NO parcel identity), which prevents a whole class of misuse.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Even with readOnlyHint and idempotentHint annotations, the description adds substantial behavioral context: fail-closed handling of expired/unknown candidate ids, deterministic pruning, inference via route_factor 1.4, and the caveat that estimates are not engineered latency quotes. The annotations and description are fully consistent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but information-dense and front-loaded with the core purpose and use case. The output-field enumeration partly duplicates the existing output schema, but the compact return summary, explicit contract, example, and alternatives make the length justified.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity, the description covers the input contract, candidate-id resolution rules, output shape, confidence provenance, failure semantics, caveats, and sibling-tool routing. Nothing critical for an agent to select and call this tool correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description reinforces key semantics like the candidate-contract fail-closed behavior and sync-replication latency ranges, but these are already present in the input schema. It adds examples but not significant new parameter meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: physics-bounded latency clustering of 2-8 sites returning viable clusters and pairwise RTT floors. It explicitly distinguishes itself from plan_fiber_leadin and get_fiber_readiness, and the 'deterministic pruning BEFORE detailed routing' phrasing makes its role unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says when to use the tool: when the human wants to know which candidate sites can form a synchronous/low-latency cluster. It also gives clear when-not-to-use guidance: do not treat results as engineered quotes, and use plan_fiber_leadin or get_fiber_readiness for adjacent needs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds genuinely valuable behavior: progressive disclosure, default comparables count, paid-key gating, escalation paths via 'summary' and 'full', and the fact that verdict text is always included. This goes well beyond the structured annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is longer than minimal but every sentence earns its place: core behavior, progressive disclosure, paid-key caveat, comparables escalation, and an example. It is front-loaded with the main purpose before diving into disclosure mechanics. Slight redundancy in the quoted questions could be trimmed, but overall it is well structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given an output schema exists and annotations carry the read-only/idempotent safety profile, the description provides everything an agent needs: what is returned, default behavior, paid-key restriction, comparables escalation, and the kind of questions it answers. No critical operational detail is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 meaningful usage nuance: 'limit' is exemplified with a default of ~15, and 'comparables' gets a clear escalation ladder (none cheap, summary for top-2 signals, full for drilling in). It clarifies cost/behavior implications, not just types — a real addition over the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description states a specific resource — data-center M&A/capex deal flow — and a distinct output: deals with DCPI grid-reality verdicts and per-deal autopsy reads. It differentiates itself from generic transaction or market tools by overlaying 'what is the real play?' on each market. The verb 'Returns' plus named output components make the tool's job unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear use-case context: answering 'who is actually buying data centers right now' and 'what is the real play behind this deal', plus a concrete 'Try deal_autopsy limit=15' example. It does not explicitly name alternatives like list_transactions or get_market_intel, so the guidance is strong on context but lacks explicit when-not-to-use exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes beyond the readOnly/idempotent annotations by explaining the tool's navigation-layer behavior, its filtered output, and its non-exhaustive relationship to tools/list. It warns that this is not the exhaustive catalog and tells the agent where to get full schemas, which is 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but mostly earns its length: it front-loads the purpose, then adds return shape, family list, usage guidance, and canonical-source caveats. The final capability-map binding note is somewhat niche but still useful, so the structure is efficient without being bloated.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a meta-tool with one optional parameter and an output schema, the description covers all essential operational context: when to call it, what it returns, how filtering works, where the authoritative catalog lives, and what to do after discovery. Nothing critical is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already covers the single optional `query` parameter with examples and meaning, so the description adds little parameter-level information beyond restating that filtering is optional. With 100% schema description coverage, the baseline score applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'navigate DC Hub's tool catalog by FAMILY instead of scanning the whole list.' It clearly identifies what the tool returns (_entity=tool_families) and differentiates itself from the canonical tools/list, making its meta-tool role distinct from sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit when-to-use guidance: 'Call this FIRST when you are unsure which tool fits a task.' It also provides an exclusionary rule by stating that tools/list remains canonical and that capability maps should be bound from tools/list, not from here, and references execute_plan/get_changes for refresh.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already establish that this is read-only, non-destructive, and idempotent. The description goes well beyond those by disclosing that results come from a live authoritative FEMA dataset, are never estimated, are county-level, and that non-US points return coverage=unavailable. This materially helps the agent reason about results and edge cases without contradicting 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but well-organized: use case, data source, example, return semantics, resolution, and alternatives. It is front-loaded with the most decision-relevant information. The main minor inefficiency is that the return-structure summary partly duplicates what an output schema would already provide, but the high-level semantic notes (e.g., 0-100 higher=worse) still earn their place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a geospatial hazard tool, the description covers everything an agent needs: input coordinates, hazards included, data provenance, geographic coverage constraints, county-level resolution, output semantics, and sibling alternatives. The rich output schema handles structural return details, and the description supplies the interpretive and routing context on top.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the parameters are already documented in the input schema. The description adds a concrete example and implicitly signals that lat/lon are needed, but it doesn't add substantially new meaning beyond the schema. The baseline-3 score is appropriate because the schema carries the parameter-documentation load.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific, actionable use case ('Use when a user wants the natural-hazard / disaster risk for a lat/lon'), names the specific resource (FEMA National Risk Index), and lists covered hazard types. It also clearly distinguishes itself from nearby sibling tools by naming get_water_risk and get_composite_site_score, so there is no ambiguity about what this tool uniquely provides.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives an explicit when-to-use statement and an explicit when-not-to-use (or use-alternative) statement: chronic water stress → get_water_risk; blended site verdict → get_composite_site_score. It also clarifies geographic coverage limitations and provides a concrete example invocation, so an agent knows exactly when and how to deploy the tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds valuable behavioral context: attribution requirement to DC Hub (CC-BY-4.0), the live/real-time nature of the data, and the 'one round trip, no planner overhead' operational characteristic.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the most important routing decision and packs a lot of useful context into a dense block. It is somewhat verbose and repeats the 'live price' concept a few times, but it earns its length given a large sibling set and the need to prevent misuse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose, when to use, when not to use, exact parameter guidance, an example, return fields, and attribution. Since an output schema exists, the return shape is already structured, so no additional return documentation is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds requiredness for iso despite the schema's required list being empty and gives a concrete example: iso=ERCOT. It does not add meaning for state or data_type beyond what the schema already describes, which is fine.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific verb+resource: live energy pricing for the 7 US ISOs, including retail rate, wholesale/LMP context, natural-gas price, and grid status. It also distinguishes itself from sibling tools by name, such as get_grid_data, get_grid_intelligence, and 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.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit when-to-use and when-not-to-use guidance, including a front-door check routing to execute_plan for siting/market-comparison questions. It names exact alternative tools for excluded cases: get_grid_data, get_grid_intelligence, and get_gas_economics, and even provides an example query.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the readOnly/idempotent annotations by disclosing a data-quality withdrawal: the $/MWh layer is no longer returned, gas_to_grid_status carries the reason, and the endpoint previously served physically impossible values. This is exactly the behavioral context an agent needs to avoid misusing cached or derived numbers.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The core purpose and parameter call are front-loaded, and the withdrawn-feature warning is clearly separated. It is longer than most tool descriptions, but the extra sentences carry important safety caveats rather than filler; a little trimming of the historical explanation would make it tighter.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only data lookup with full parameter documentation and an output schema, the definition covers what is returned, what was withdrawn, how to detect it, and which sibling to use instead. No critical information is missing for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 market and heat_rate_btu_per_kwh. The description only repeats the market=<slug> format with examples and does not add meaning beyond the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Opens with a specific verb and resource: 'Behind-the-meter / gas-fired power inputs for a US data-center market,' enumerating Henry Hub spot, regional basis differential, and delivered industrial + electric gas tariff in $/MMBtu. This precisely identifies what the tool returns and distinguishes it from related data lookups.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use it for gas-fired power inputs and gives a direct exclusion with an alternative: 'Do NOT use for the electricity grid fuel mix (use get_grid_data).' It also forbids quoting withdrawn $/MWh values or deriving them silently, which is actionable guidance for an agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool read-only, idempotent, and non-destructive, and the description adds substantial behavioral context: returned values are split by capacity_type, distinct_feeders vs geometry_rows_scanned are never conflated, sample_complete=false indicates a capped read, and out-of-coverage points return an explicit not-published answer rather than a silent zero. 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose and critical capacity_type caveat, and nearly every sentence carries substantive information. However, it is very long and dense, enumerating 18 utilities and including extended examples and exclusions, which pushes the limits of conciseness even though the content is relevant.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity, optional parameters, and output schema, the description is remarkably complete: it covers coverage geography, return structure, failure behavior, capacity_type interpretation, invocation modes, and sibling disambiguation. There is no critical context an agent would need that is absent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and each parameter is already well documented, so the baseline is 3. The description does reinforce the critical capacity_type semantics and call modes, but most of that meaning is already present in the input schema. It adds minimal new parameter-level detail beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource: 'Utility-PUBLISHED feeder hosting capacity — the MW a NAMED distribution feeder can actually take.' It clearly distinguishes this tool as the distribution FEEDER layer and names what it is not, separating it from siblings like get_grid_intelligence and get_interconnection_queue.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage guidance is explicit and actionable: it lists the three call modes (lat/lon, utility/market, no args), states the questions it answers, and explicitly says which sibling tools to use instead for transmission proximity, interconnection queues, and retirement headroom. This is far beyond a vague 'use for capacity questions.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (read-only, idempotent), the description discloses token-budget greedy filling in priority order, per-section token counts, as_of timestamps, citable URLs, and omitted sections. It even notes the outlook is Claude-written, giving agents important context about output provenance.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The definition is front-loaded with the primary purpose and uses compact sections for params, returns, and exclusions. It is longer than minimal, and the param paragraph slightly repeats schema text, but every major block earns its place for a complex tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, the description still adds complete selection context: intended use, exclusions, example invocation, token-budget behavior, return shape essentials, and citation requirement. Nothing an agent needs to decide whether to call this tool is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the schema already explains both market slug validity and max_tokens behavior including priority-order filling. The description adds a concrete invocation example, but it largely restates the schema rather than introducing new parameter semantics, so the high-coverage baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb-plus-resource: a WHOLE-market briefing context pack for a data-center market. It explicitly contrasts itself with three siblings (get_market_dcpi_rank, get_market_intel, rank_markets), so an agent can disambiguate without opening schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states exactly when to use it—when a narrative whole-market briefing is needed—and adds a do-not-use list for single metrics, raw structured metric sets, and cross-market ranking, naming the alternative tool in each case. This is explicit routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already establish readOnlyHint, idempotentHint, and destructiveHint. The description adds meaningful behavioral context by disclosing the exact return shape, the possible DCPI verdict values (BUILD/CAUTION/AVOID), and the 300+ market scope. 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: trigger condition, example, parameter clarification, return fields, and anti-usage. It is longer than minimal, and the return-field list is somewhat redundant given the output schema, but every section serves a clear purpose and it remains readable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the rich input schema, annotations, and output schema, the description is complete: it tells when to use it, what it returns, and when not to use it. The only minor ambiguity is that the schema lists no required params, but the description's wording and example make it clear that market is effectively required.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds value beyond the schema by giving a concrete invocation example, clarifying that market is a slug with examples, and noting that valid slugs come from rank_markets/get_market_dcpi_rank in the schema. It does not deeply elaborate metric/period/compare_to, but the schema already covers those.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'get market intel' for ONE data-center market, and enumerates the data dimensions (vacancy, pricing, pipeline, operators, YoY growth). It also explicitly contrasts with sibling tools rank_markets and get_facility, so an agent cannot confuse it with those.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description opens with 'Use when a user asks about ONE data-center market' and closes with 'Do NOT use to rank multiple markets (use rank_markets) or for a single facility (use get_facility).' This gives both positive trigger conditions and explicit exclusions with named alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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 meaningful behavior beyond annotations: it explains the two distinct output shapes depending on whether the market param is supplied, includes dark-fiber coverage, and includes a citation requirement ('Cite DC Hub'). The only minor gap is not stating rate limits or freshness, but that is not required given the strong annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the key use case, includes concrete examples, and packs in essential return-format details. It is dense but every sentence earns its place. It could be slightly shortened by trimming the detailed return schema (since an output schema exists), but the operational guidance justifies the length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's modest complexity (one optional parameter, no required params, output schema present, annotations covering read-only/idempotent), the description is complete. It covers when to use, what it returns in both modes, the data source/citation, and when NOT to use it. An agent has everything needed to select and invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the schema already documents the market parameter thoroughly. The description adds value by giving concrete examples ('Dallas-Fort Worth', 'dallas', 'ashburn'), clarifying slug vs name, and explaining the behavioral difference between omitting market (ranked list) vs providing it (deep dive). This goes beyond what the schema alone provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description is highly specific: it names the verb 'get', the resource 'metro fiber profile', and enumerates exact fields (carrier count, route-miles, on-net buildings, density score, tier, IX points, carrier hotels). It also distinguishes itself from sibling tools by explaining what it is NOT for (parcel-level verdicts, geometry mapping). An agent can clearly understand what this tool does and how it differs from get_fiber_readiness and get_fiber_intel.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly provides when-to-use guidance: 'Use when a user asks which US metro has the DEEPEST fiber, or wants the metro-level fiber profile of a market.' It also names the two sibling alternatives and the conditions that select them: do NOT use for parcel-level latency/connectivity (use get_fiber_readiness) or route geometry for maps (use get_fiber_intel). This is exemplary routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds meaningful behavioral context beyond annotations: news is refreshed every 30 minutes, sourced from 40+ trade publications, and returns specific fields including mentioned market/operator entities. This enriches the agent's understanding of what the tool actually does without contradicting annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but well-organized: routing guidance comes first, followed by source/refresh behavior, return fields, filters, an example, and exclusions. It is longer than strictly necessary, and phrases like 'FRONT DOOR CHECK' are slightly jargon-heavy, but nearly every sentence adds decision-relevant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity, rich input schema, output schema, and strong annotations, the description is fully complete for correct selection and invocation. It covers what the tool returns, when to use it, when not to use it, example usage, and the key category filter, leaving no critical gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description earns extra value by giving a concrete usage example ('get_news category=AI limit=10') and explicitly warning that the parameter is `category`, not `topic`. While it does not deeply explain all seven parameters, the schema already handles that, and the added disambiguation is genuinely useful.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that get_news retrieves curated data center industry news from 40+ trade sources and returns titles, summaries, sources, publication dates, and mentioned entities. It also explicitly distinguishes itself from execute_plan, list_transactions, and get_pipeline, so an agent can tell exactly what this tool is for.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit routing guidance: if news is only one input to a larger question, use execute_plan; if the user wants headlines, use get_news directly. It also names exclusions with specific alternatives: use list_transactions for M&A deal data and get_pipeline for the construction pipeline. 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds useful behavioral context about data provenance (human-verified), stage-tagging ('Enacted' / 'Proposed' / 'Speculative'), and included attribution fields (source URL, coordinates). It also notes the resource is free and full for every caller, going beyond the structured annotations without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but information-dense: it front-loads the core purpose, then lists record contents, stage tagging, examples, an exclusion, and a live rendering URL. Each sentence earns its place, though some promotional phrasing ('FREE and full for every caller', 'no other machine-readable source serves') could be trimmed without losing functional guidance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that the tool has two optional parameters, an output schema, and annotations covering safety, the description is complete. It explains what the records contain, how to filter them, when to use the tool, when not to use it, and where the data is rendered. There is no missing decision-critical information for an agent to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the two optional parameters, so the baseline is 3. The description adds practical meaning by using class=moratorium and state=MN as examples, and by mapping the class value 'tax' and 'utility_pause' to 'tax changes' and 'utility pauses'. This helps an agent understand how to use the parameters even though the schema already documents them.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states exactly what the tool does: it provides 'PERMITTING & MORATORIUM intelligence' with curated jurisdiction records covering moratoriums, zoning restrictions, tax changes, and utility pauses. It is clearly differentiated from the sibling get_tax_incentives, and the scope is specific to restrictions and risk rather than incentives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit use cases ('is there a moratorium where I want to build', 'which jurisdictions just tightened data-center zoning') and a direct exclusion with a named alternative ('Do NOT use for tax INCENTIVE programs by state (use get_tax_incentives)'). The call examples class=moratorium and state=MN also serve as concrete usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly/idempotent/destructive annotations, the description discloses keyless-call behavior (returns auth_required rather than an empty list), requires a key, and details what the response contains including live deltas and portfolio flags. This gives the agent accurate expectations for side effects and failure modes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is longer than average, but every section earns its place: auth prerequisite, use cases, example queries, parameter explanation, return payload, and exclusions. It is front-loaded with the critical key requirement and organized clearly, though slightly dense.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's auth requirement, per-account behavior, rich return data, and related siblings, the description covers all necessary context. The output schema exists, and the description still usefully summarizes the return contents and the key precondition, leaving no critical operational gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description already covers the since parameter fully, including accepted values, default, and how to use the cached generated_at timestamp. The tool description restates the same information without meaningfully adding beyond the schema, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb and resource: list saved DC Hub sites in-chat as a read-back. It also distinguishes itself from save_site and export_dataset, and provides concrete example user queries, so an agent can identify when this tool applies.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says when to use it — when a user wants to see/review saved sites or know what moved — and when not to use it, naming save_site for adding and export_dataset for downloading. It also gives a critical prerequisite: claim_free_key must be called first if no key exists.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral caveats beyond that: status is returned but cannot be used as a filter, there is no `status`/`min_mw` parameter, and construction-stage filtering must go through get_pipeline. It also states the tool takes one round trip versus the planner's added latency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense and front-loaded with the most important routing decision, then scope, return fields, example, caveat, and exclusions. It earns most of its length, but there is minor redundancy (get_pipeline exclusion appears twice) and the 'planner would add steps and latency' aside is slightly editorial.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 10 optional parameters, a full schema, an output schema, and safety annotations, the description covers the remaining context an agent needs: when to route to execute_plan, what the tool returns, the status-filter caveat, an example call, and explicit sibling exclusions. The only tiny ambiguity is the mention of 'fiber connectivity' and 'DCPI verdict' as search dimensions without corresponding schema params, but the overall guidance is complete enough for correct selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 a concrete example invocation (search_facilities country=US state=VA min_capacity_mw=10), clarifies that status is a returned field rather than a filter, and warns that `status` and `min_mw` parameters do not exist. That is meaningful guidance beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific action and resource: 'Search 20,100+ global data center facilities across 170+ countries' by defined filters, and gives concrete example questions ('which data centers are in Virginia'). It also distinguishes itself from siblings by explicitly saying 'Use this to find EXISTING facilities; do NOT use for the forward-looking construction pipeline (use get_pipeline) or for the full profile of one 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.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description opens with a 'FRONT DOOR CHECK' routing rule: if hits need power/fiber/water/verdict context attached, call execute_plan; if it's a plain inventory lookup, search_facilities is correct. It also names the alternatives get_pipeline and get_facility and the conditions that select them, so an agent gets explicit 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate mutating behavior but not specifics; the description adds meaningful behavioral context: alerts are delivered by email on DCPI/capacity/facility changes, free tier forces delivery to the bound email, and bind_email is a prerequisite. It could mention duplicate-alert behavior, but the disclosed side effects are substantial.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but structured well: purpose, workflow, parameters, example, and exclusions. The example call and anti-patterns earn their place, though some phrases like 'FREE with a key' and 'so you don't have to keep re-checking' are mildly promotional and could be trimmed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with tier differences, a prerequisite binding step, three trigger types, and sibling overlap, this description is complete. It covers the full calling sequence, parameter semantics, example invocation, and explicit exclusions, so an agent can invoke it correctly without external knowledge.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description enriches the parameters by explaining saved_site_id's source, threshold meaning, default values, trigger_type enum options, and the free-tier override on notify_email. This goes beyond the schema's descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a specific verb and resource: 'Arm an email watch on a site you already saved.' It clearly differentiates this from save_site and set_market_alert by naming those sibling tools and stating what this tool is NOT for.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use guidance: first call save_site to obtain saved_site_id, then set_site_alert. It also gives exclusions: do not use for whole markets or new site creation, with the correct sibling alternatives named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses consent behavior in detail: double opt-in, one-click confirm link, one-click unsubscribe, no marketing flag set, and the returned shape. This goes well beyond the minimal annotations and tells the agent exactly what side effects to expect.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but well-organized, front-loading the purpose and then providing consent caveats, trigger conditions, params, return value, and a preferred alternative. It is longer than strictly necessary but every sentence carries meaningful selection or behavior information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the annotations, input schema, and output schema, the description covers everything needed: when to call, consent side effects, parameter expectations, return shape, and an alternative. Nothing critical is missing for an agent to invoke this correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents both parameters. The description adds a small amount of context by emphasizing the email must be explicitly shared and mentioning source is an optional tag, but it mostly restates what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: subscribing a human to DC Hub's weekly digest, and explains exactly what the digest contains. It is clearly distinguishable from the many sibling data-query tools and even contrasts itself with hand-building the POST endpoint.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives an explicit precondition: only call once the human shares their email and wants a weekly email. It also provides a clear alternative by saying to prefer this tool over hand-building POST /api/v1/opt-in/request, which gives the agent actionable selection guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide no positive hints (all false), so the description carries the burden — and it delivers. It discloses the session/API-key binding behavior, the email-to-payer fallback, the one-click checkout division of labor, and names the exact response fields (next_call_full_after_checkout, after_checkout) that signal which path applies. No contradiction with 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with purpose and trigger conditions, with dense behavioral detail following. However, the pricing enumeration ($10 one-time, $9/mo, $49/mo, $299/mo) is redundant with the tool's own return value ({plans, ...}) and risks going stale, and the emoji adds noise. Slightly overlong but each substantive section earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers triggers, deliverable, the checkout/binding flow, free-tier routing, the optional param, and the return shape — with an output schema present to document the structured response. Nothing an agent needs to call this tool correctly or explain the outcome to a human is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the description's param note ('what you were trying to do, so your human sees why it matters') essentially restates the schema's own description. It adds no new meaning beyond the structured field, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific action (unlocking DC Hub's full depth), concrete trigger conditions (partial preview, locked tool, human wants complete dataset), and the exact deliverable (upgrade ladder + checkout links). It explicitly names the sibling it is not — claim_free_key — so an agent can disambiguate without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives three explicit when-to-call conditions ('Call this when a result came back as a partial preview... a tool was locked, or your human wants the complete dataset') and routes the alternative case explicitly ('Want the FREE tier instead...? Call claim_free_key'). No inference required.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, and destructve hints, and the description adds valuable behavioral context: it returns honest, source-verified differentiators with proof URLs and citation lines, is free with no key required, and even discloses the withdrawn/restored history of the DCGI index. This goes well beyond the structured metadata.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense and front-loaded with the use case, and every sentence contributes useful guidance. However, the first sentence contains a long parenthetical list and the DCGI withdrawal/restoration detail, which could have been structured more cleanly. It is acceptable given the amount of positioning context needed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is complete for this low-complexity, optional-parameter tool. It covers the exact trigger, the return content, exclusions, free/no-key access, and optional parameter behavior. Since an output schema exists, it does not need to elaborate further on return structure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 100% description coverage for the single optional `competitor` parameter, and the description does not add substantial meaning beyond that. It largely restates the schema's existing explanation about returning a direct comparison-page link for a vendor, so the parameter semantics are adequate but not enhanced.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool's job: answering positioning and comparison questions about DC Hub versus other data-center data sources. It uses a specific trigger ('why should I use DC Hub / is it better than X') and explicitly separates this from infrastructure-data querying with 'Do NOT use to query infrastructure data itself.' This makes it easy to distinguish from the many data-query sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It states exactly when to use the tool ('Use when a human asks how DC Hub compares...'), explicitly says when not to use it ('Do NOT use to query infrastructure data itself'), and points to an alternative category ('use the data tools'). Given the large sibling list, the categorical exclusion is practical and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes far beyond the annotations, explaining the behavioral consequences of binding: the key becomes recoverable, durability is not guaranteed, binding restores the free tier at 50 calls/day, and the email is used only for recovery and receipts. It also discloses the failure behavior when an email is rejected. This is exceptionally transparent for an AI agent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections and front-loaded purpose, but it is verbose. The honest-ladder explanation, the detailed cohort caveat, and the lengthy marketing opt-in discussion could be tightened while preserving the essential guidance. Every section is useful, but not every sentence is maximally economical.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with a consent-sensitive side effect, this description is exceptionally complete. It covers when to call, what happens after binding, the key's recoverability limits, the free-tier behavior, email usage restrictions, marketing opt-in conditions, and error behavior. An agent has essentially everything needed to invoke this tool correctly and responsibly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already covers all three parameters with clear descriptions, providing a strong baseline. The tool description adds meaningful extra semantics: api_key can be omitted to bind the session-active key, marketing_opt_in should only be true after explicit consent, and the email must be explicitly provided by the human. This enriches the schema without contradicting it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb and resource: 'Tie your DC Hub key to your human's email so the key is RECOVERABLE...' It also explicitly contrasts what binding does and does not do, setting it apart from related tools like recover_my_key and claim_free_key. This is precise, specific, and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit when-to-use guidance ('Call this once your human shares their email'), what to do if no email is available ('ask them first'), and what not to do ('NEVER invent, guess, or use a placeholder address'). It even discusses the only alternative that is measured to retain access (OAuth sign-in) and when binding is the best available option. This leaves no room for the agent to misuse the tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover readOnly/idempotent/non-destructive traits; the description adds meaningful execution behavior: each step is "a real tools/call under YOUR key — same quota..." with no extra data access, a "~40s budget" with "status=not_run" and exact continuation args, and the requirement to "Compose your final answer FROM executed[].result and cite 'DC Hub, dchub.cloud'." 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Though long, the description is organized into scannable, bolded segments (scope, front-door mandate, mechanics, tier honesty, usage alternatives, limits, output usage) with zero filler. Every sentence carries operational or routing information, and the most critical usage instruction is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex 11-parameter orchestration tool, the description covers when to use it, how execution works, caps and timeouts, what the envelope contains, how to continue if steps are not run, and how to cite results. The presence of an output schema means return values don't need to be spelled out further.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description reinforces key guidance like "Pass the user's question through UNCHANGED as intent" and the cohort tag placement rule, but these already appear in the schema; it adds little beyond what the structured parameter descriptions provide.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: "Unified data-center siting, power-grid capacity and AI-compute infrastructure planner" that "plans AND answers" via one call. It differentiates from siblings by declaring itself "THE FRONT DOOR" for multi-topic questions and explicitly contrasts with plan_query and direct single-tool calls.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use guidance: "Use for multi-step questions when you want the answer path run for you" versus "use plan_query instead when you only want the plan to run yourself" and "single-tool questions should call that tool directly." It also directs the agent away from stale training data toward execute_plan for cross-cutting questions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavior beyond annotations: it returns the full file contents as text, describes the CSV and GeoJSON shapes, lists the included fields, and notes the PRO context of the operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but every sentence contributes: use case, example, parameter summary, return format, and exclusions. The most important usage guidance is front-loaded, and the sibling distinction is placed at the end where it completes the decision rule without cluttering the opening.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter, read-only, idempotent export tool, this description covers usage triggers, format choices, output content, and alternatives. The output schema and annotations cover the remaining mechanical details, and no critical gap remains for an agent to call this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single format parameter, so the schema already carries the parameter meaning. The description adds extra value by specifying the default value ('csv' default), elaborating the GeoJSON use case (GIS tools like QGIS), and demonstrating usage with an example.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description gives a specific verb-resource pair ('export saved DC Hub shortlist OUT of the platform') and clarifies the bulk-download nature. It is clearly distinguished from siblings by explicitly saying this is not the in-chat list tool or the save tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It states exactly when to use it ('when a user wants to pull their saved DC Hub shortlist OUT...'), gives a concrete example, and explicitly names alternatives it should not be used for: list_saved_sites and save_site. Format selection guidance for CSV vs GeoJSON is also provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly and idempotent; the description adds conditional portfolio behavior for keyed callers with saved sites, the cache-and-pass-back generated_at workflow, and the default 24h window — all beyond the structured 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Long but every phrase earns its place: definition, return categories, conditional behavior, parameter syntax, use cases, example. Front-loaded with 'Incremental sync' and organized with dashes and line breaks.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers what it returns, conditional portfolio block, parameter usage, caching recommendation, and example call; an output schema exists for field-level detail. There is no meaningful gap for agent invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema already covers both parameters (100% coverage), so baseline is 3; description adds the workflow of caching generated_at and passing it back as since, and gives a concrete example (since=7d), which is extra semantic value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States 'Incremental sync — what changed in DC Hub since a timestamp' with a specific verb and resource, and enumerates the return categories. This clearly distinguishes it from siblings like get_news or fetch by its delta scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives concrete trigger use cases ('what changed since I last looked', 'anything new this week I should know about') and explains it replaces re-fetching everything. It does not explicitly name sibling alternatives or exclusion conditions, so it stops short of full routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the description does not need to restate safety. It adds useful behavioral details beyond annotations: returns exactly one full facility, includes peer facilities nearby, and lists the specific metadata categories covered. It also communicates the tool is a targeted lookup, not a search.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences but packs the return fields, use cases, example calls, and the key exclusion into a tight structure. No sentence is wasted, and the most important information (what it returns, one facility only) is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has a rich output schema, complete parameter documentation, and annotations covering safety. The description adds the missing contextual elements: concrete example calls, explicit scope restriction, and routing to search_facilities. Nothing essential is missing for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds value by giving concrete example values (equinix-dc1-ashburn, digital-realty-iad8), clarifying that id is a usable alias, and noting that name is the fallback when no id/slug is known. These concrete examples help an agent construct valid calls.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb (get) with a clear resource (one facility) and enumerates exactly what fields are returned. It explicitly contrasts itself with search_facilities by stating it returns ONE facility, not a list, which makes sibling differentiation immediate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives concrete invocation examples ('Try: get_facility id=equinix-dc1-ashburn') and an explicit exclusion: 'do NOT use to search or list many facilities (use search_facilities).' This tells the agent exactly when to call this tool and which alternative to use instead.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds far beyond that: the DCGI withdrawal/restoration history, the still-withdrawn gas_to_grid $/MWh, the instruction not to quote cached scores, the honest null-handling of delivered_price, and the warning to read dcgi_status and gas_to_grid_status independently. This is exceptional behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense and information-rich but overly long and unstructured. It front-loads the use case well, but then dumps a long return-object fragment and a complex index-correction history in a single run-on paragraph. The key warnings ('do not compare pre-2026-08-08 figures', 'do not quote cached DCGI scores') are buried mid-text. Every sentence earns its place, but the lack of paragraph breaks and ordering hurts scannability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity, rich output schema, and many sibling tools, the description is remarkably complete. It covers the return shape, field semantics, omitted data (gas storage, LNG, firm capacity), data provenance via data_basis, current index statuses, and exclusions. The output schema also exists to document return values, so the description doesn't need to restate them. Nothing critical is missing for an agent to call this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, giving a baseline of 3. The description adds value by explaining that 'state' is an alias for 'region' and giving examples of accepted values ('TX' | 'Texas' | 'Virginia'). It does not go into deeper semantics for each field, but the schema already documents both parameters, so the added alias/example clarification justifies a 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: answering human questions about gas-fired or behind-the-meter power economics for US data centers. It explicitly names the GAS analogue of get_grid_intelligence and differentiates itself from get_gas_index and get_grid_intelligence. This is a clear, specific purpose that an agent can easily distinguish from siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description opens with 'Use when a human asks about gas-fired or behind-the-meter power economics' and gives concrete example user questions. It explicitly states exclusions: 'Do NOT use for electricity grid headroom (use get_grid_intelligence) or the DCGI score alone (use get_gas_index)'. This is excellent when-vs-when-not routing with named alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is clear. The description adds behavioral context beyond annotations: data comes from EIA hourly RTO telemetry, is raw real-time telemetry, is scoped to one ISO per call, and covers a 24h demand curve. This helps set expectations about freshness and granularity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but every clause earns its place: it states the data scope, source, acceptable values, and key exclusions with sibling pointers. The most important usage constraint is front-loaded, and no filler or repetition exists.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the rich input schema, output schema presence, and annotations covering safety and idempotency, the description provides the remaining necessary context: data source, ISO coverage, raw real-time nature, what not to use it for, and fallback tools. Nothing critical is missing for an agent to select and call this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds value by clarifying that iso is effectively required ('Pass iso=PJM (any of the 7)') despite the schema showing 0 required parameters, and by giving concrete metric examples (fuel_mix, demand, demand_curve) and a period example (24h). This extra context helps the agent construct valid calls.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb-resource pair: retrieving real-time electricity grid data for seven named US ISOs, with explicit data types (fuel mix, demand, 24h demand curve). It clearly differentiates from sibling tools like get_grid_intelligence and 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.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit when-to-use guidance: use for real-time ISO telemetry, and explicitly says not to use for power-availability, time-to-power, interconnection-queue, or retail/gas price analysis, naming get_grid_intelligence and get_energy_prices as alternatives. It also routes non-US grids to get_grid_scoreboard.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations carry the safety profile (readOnlyHint, idempotentHint, destructiveHint all safe), so the bar is lower and the description earns full credit for context beyond them. It discloses three critical behavioral traits: market names resolve to their ISO via the DCPI row with a resolved_from block, balancing authorities return only live generation mix while other metrics stay ISO-level, and the two time metrics are non-interchangeable with the queue-wait derivation formula (12 + 0.6 months/GW, clipped 12-66). These are exactly the traps that would corrupt an agent's output. 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Information-dense but long (roughly 280 words). It is front-loaded with the trigger use case and example, and every clause earns its place — the alias list, BA caveat, metric warning, and sibling routing are all high-value. The return-field enumeration is partially redundant with the output schema, but it anchors the essential time-to-power vs queue-wait warning, so the length is largely justified.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a high-complexity tool (4 params, three input modes, a counterintuitive resolution quirk, and a metric disambiguation), the description covers the critical decision points: valid inputs, market resolution behavior, BA data-scope limits, metric non-interchangeability, and when-not-to-use. Gaps are minor: no error behavior for invalid regions, and the schema's '0 required params' label sits awkwardly against the description's implication that a region or market is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3, but the description adds real value beyond the schema: it groups iso/region/region_id as aliases, enumerates the full 7-ISO valid set plus 40+ balancing-authority examples, documents the special PJM-DOM zone for Ashburn, and clarifies that market is not an alias but a name resolved to a larger ISO. The only reason it isn't a 5 is that the schema already covers much of the same ground.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb+resource+scope: 'the flagship grid-headroom + interconnection-queue brief for one ISO', anchored to a concrete trigger question ('can I get N MW of power in <ISO> and how long will it take?') and a worked example call. It distinguishes itself from siblings by name ('Do NOT use to compare 2+ ISOs side-by-side (use compare_isos) or for the global greenest-first ranking (use 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.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit when-to-use guidance is given as a verbatim user-intent trigger, and explicit when-not-to-use exclusions name the exact sibling alternatives (compare_isos, get_grid_scoreboard). The market-vs-ISO edge case is also covered with a warning that the figures describe the ISO, which is larger than the market named — leaving no ambiguity about interpretation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only/idempotent behavior, and the description adds valuable context: return shape, pagination, the lack of a market parameter, and filtering guidance. It loses one point for a small internal ambiguity: status includes 'operational' while the description says not to use it for already-operational facilities. This does not contradict 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but well organized into purpose, example, parameters, return shape, and exclusions. Every segment earns its place and the most important routing information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 7-parameter read-only tool with an output schema, this description is complete: it covers when to use, how to construct queries, what parameters mean, what the response looks like, and which sibling tools to use instead. No critical information for correct invocation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds concrete value: explicit status enum values, ISO-2 country example, ISO date format with an example, operator examples, MW threshold guidance, and pagination mention. This goes beyond the schema without being redundant.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific purpose: answering 'what is being built / announced / permitted' via the forward-looking construction pipeline. It clearly distinguishes this tool from search_facilities and list_transactions, so an agent can tell when to use it versus siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It opens with an explicit 'Use when' condition and provides a concrete example query. It also states exactly when not to use it ('Do NOT use for already-operational facilities' or 'M&A deal flow') and names the alternative tools, plus warns that there is no market parameter.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool read-only, idempotent, and non-destructive. The description adds useful context: one round trip, free tier, no planner overhead, the exact return fields with interpretation, and data provenance (USGS + US Drought Monitor). It also notes that lat/lon gives the most precise read. 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense and front-loaded with the routing decision, followed by use case, example, parameter rules, output summary, and exclusions. It is long but mostly earns its length; minor redundancy like repeating 'free tier' and the example partially duplicating parameter syntax keeps it from a perfect score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers selection logic, parameter alternatives, output field semantics, and limitations despite the presence of an output schema. The only significant gap is the undocumented 'county' parameter, which makes some of the guidance non-actionable against the actual schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description clarifies that lat+lon, state, and county are mutually exclusive alternatives and that lat/lon is most precise, adding semantics beyond the schema's per-property descriptions. However, it introduces a 'county' parameter that is absent from the input schema, which could lead an agent to attempt an invalid invocation, preventing a higher score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: it returns the water-risk factor for a US site, and explicitly says this covers the WATER factor only. It distinguishes from siblings by naming analyze_site, get_infrastructure, and execute_plan, so an agent can tell it apart without inspecting schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states when to use ('Use when scoring a US site for cooling-water sustainability') and when not to use ('Do NOT use for nearby physical infrastructure... or a combined multi-factor site verdict'), naming alternatives in both cases. The concrete example query grounds the guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark this as read-only, idempotent, and non-destructive, and the description adds meaningful behavioral context beyond that: 'live feed', '10-min refresh', regex-based extraction of dollar figures and megawatts, actor classification, and the typical volume ('$1B+/week'). This gives the agent an accurate picture of freshness, latency, and what kind of data to expect.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but every sentence earns its place: scope, data source/extraction method, refresh cadence, use cases, and exclusions. It front-loads the core identity ('Hyperscaler AI Deal Tracker — live feed') and uses compact phrasing without unnecessary filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-optional-parameter read-only tool with an output schema, the description is complete: it explains data source, refresh behavior, extraction logic, classification, intended uses, and exclusions. An agent has enough context to call the tool correctly and to route to alternatives when appropriate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'limit' is fully documented in the schema with type, min, max, and default. The description does not add new semantic detail about this parameter, but with 100% schema description coverage, the baseline of 3 is appropriate. The description's mention of 'recent' deals and '10-min refresh' slightly reinforces what 'limit' acts on, but adds no parameter syntax details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies a specific resource ('live feed of ... AI deals'), a concrete mechanism ('Pulls from dchub news pipeline, extracts $-figures + MW via regex, classifies by actor'), and a precise scope ('$1B+ AI-capex feed'). It distinguishes itself from siblings by naming actors and use cases, so an agent can separate it from list_transactions and deal_autopsy without inspecting schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use guidance ('Use for tracking AI capex events..., capacity announcements, and competitive intel') and explicit when-not-to-use guidance with named alternatives ('Do NOT use for the full historical M&A comp set (use list_transactions) or a single-deal teardown with grid context (use deal_autopsy)'). This leaves no ambiguity about tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is known. The description adds substantial behavioral context: linear trend extrapolation, confidence bands widening with horizon, minimum 3 daily snapshots requirement, and the data source (DC Hub daily snapshot history). It honestly discloses that the forecast is 'NOT a guarantee.' 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Although long, every sentence carries functional weight: purpose, when-to-use, parameter breakdown, return shape, honesty/caveat, and exclusions. The core purpose is front-loaded and the structure is logical, moving from high-level capability to specific constraints.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (2 params, output schema), the description covers purpose, prerequisites (valid slugs and minimum snapshot history), parameter semantics, return structure, limitations, and alternative routing. Nothing an agent needs to correctly invoke or interpret this forecast tool is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents both parameters. The description repeats the same parameter information (valid slugs source, horizon range/default) without adding new meaning beyond the schema. Per the baseline for high-coverage schemas, this is a 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description opens with a specific verb and resource: 'Forecast a DCPI market's near-term trajectory (next 1-8 quarters)' and names the projected metrics (excess_power_score, constraint_score). It also differentiates from siblings by explicitly stating it is not for point-in-time verdicts (use get_market_dcpi_rank) or market ranking (use rank_markets).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Includes explicit when-to-use examples ('is this market trending toward BUILD or AVOID?', 'will Dallas power stay tight...') and clear when-not-to-use guidance with named alternatives. This is the strongest possible guidance: it tells the agent both the conditions and the sibling tools to choose instead.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover readOnly, idempotent, and destructive behavior, so the description only needs to add operational context. It discloses that results are a list of facility objects with id/title/url and positions them as citable live pages, which is useful beyond the schema. It doesn't mention result limits or ranking, but that is minor for an annotated read-only search.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences with no filler; the search action and return format come first, the workflow follows, and the alternative-tool routing closes. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter read-only search with an output schema, the description delivers everything needed: what it returns, how to follow through via fetch or citation, and when to use the structured sibling instead. No critical operational information is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and includes an example for `query`, which already carries the parameter weight. The description reinforces that `query` is free-text by routing structured queries to search_facilities, adding meaning about what should NOT be passed to this parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific action ('Search DC Hub'), a concrete resource ('data-center facilities'), and the output shape ({id, title, url}). It also names the most similar structured sibling (search_facilities), so an agent can distinguish this free-text search from that structured query tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says free-text queries are the intended use and directs structured queries by MW, operator, status, or market to search_facilities. It also gives the downstream workflow: pass an id to fetch or open the url for citation, so when-to-use and next steps are both clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses substantial behavioral detail beyond the annotations: the OR-based firing conditions, evaluation after each daily baseline refresh, delivery via webhook and/or email, and API-key scoping. This gives the agent a strong model of how the alert behaves and what setting it actually does.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is detailed but tight, and important information is front-loaded: the alert type and purpose come first, followed by firing logic, evaluation cadence, and delivery. Every sentence contributes operational or selection value, and there is no redundant restating of the title.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 4-parameter alert-creation tool with an output schema, the description covers everything an agent needs: what the alert monitors, when it fires, how often it is evaluated, how notifications are delivered, and scope limitations. The trigger formula and example make parameter usage concrete, and the output schema handles return-value expectations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is already 100%, but the description adds useful combined semantics by explaining that the alert fires when either percentile_below OR delta_below is violated, and clarifies the negative-number convention with an example. The schema already explains individual parameters, so the description adds meaningful interpretive value without needing to repeat everything.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific action and resource: setting a DRIFT ALERT on a saved shortlist, with explicit triggering criteria based on percentile and delta thresholds. This clearly distinguishes it from single-site or market-level alert tools by scoping to the shortlist resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear use context: use this to stop polling and get notified on material moves during long-running siting campaigns. It does not explicitly name alternatives like set_market_alert or set_site_alert or give exclusion rules, but the resource type and alert semantics make the intended use clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description does not contradict these. It adds valuable behavioral detail: the PDF link is ready-to-open, requires no login, is valid ~7 days, and the report structure via the return object. This exceeds the minimum needed given annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but every sentence contributes: when-to-use, an example, parameter semantics, return shape, and alternative routing are all packed in. It is front-loaded with the core purpose and example, though the parameter list could be more readable as structured bullets.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (10 params, no required, output schema present), the description covers all necessary aspects: input aliases, defaults, return object shape (survey + pdf_report_url), link validity, and when not to use it. The presence of an output schema further reduces the need to document return values, and the description complements rather than repeats it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 meaning beyond the schema: it highlights that lat/lon are required (even though the schema marks all params optional), gives a typical capacity range (50-500 MW), and explains default behavior for prepared_by ('defaults to DC Hub') and latency_target ('default = nearest real carrier hotel'). It also clarifies aliases (lng/latitude/longitude).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'generate a SHAREABLE, branded multi-page Site Analysis PDF for ONE lat/lon'. It explicitly contrasts with 'not just a score' and later names the sibling analyze_site, so an agent can immediately distinguish it from related tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states exactly when to use it ('when a user wants a SHAREABLE... PDF'), provides a concrete example, and closes with the exclusion: 'For just the numeric suitability score (no PDF), use analyze_site instead.' No inference is needed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish read-only/idempotent safety, but the description goes further: it discloses that the roster is backend-owned and changes, that statuses are 'CURATED EDITORIAL claims, not measurements', that as_of is null, and that relying on an enumerated list can produce stale results. This is exactly the kind of contextual behavior an agent needs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose and then layers critical caveats. It is longer than strictly necessary, with emphatic formatting and repeated warnings, but every sentence contributes a distinct behavioral or usage point rather than padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no parameters, an output schema present, and annotations covering safety, the description supplies the remaining essential context: what the response represents, how to interpret statuses, why lists go stale, and which sibling tool to use instead. Nothing critical is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters, so the baseline is 4. The description adds no parameter documentation because none is needed, and it instead clarifies the response shape (platforms[] array, status values, as_of null), which is appropriate for a no-input tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: it is a 'curated roster of the AI platforms and agent frameworks' and explicitly answers the question 'which AI platforms can connect to DC Hub'. It also clearly distinguishes itself from telemetry tools by framing itself as a capability index rather than live measurement.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit when-to-use guidance ('Answers which AI platforms can connect to DC Hub'), explicit when-not-to-use guidance ('Do NOT use for platform uptime or feed health'), and names the alternative tool (get_backup_status). This leaves little to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover readOnly/idempotent/destructive safety, and the description adds meaningful behavioral nuance: that a feed reporting 'unknown' has NOT been measured and is not equivalent to healthy, and to read health before trusting figures. It also discloses that the scope is exactly what /api/health/data-freshness serves, with nothing wider. This exceeds what annotations convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is somewhat long but well organized: output structure, semantic caveat, the question it answers, and scope/exclusion. Each sentence earns its place; the 'Try: get_backup_status' is slightly redundant but harmless. A small deduction for verbosity, but still tightly written.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with zero parameters and a read-only verdict, the description fully specifies the return shape (per-feed rows with health, record_count, refresh_interval, scheduler, and a summary rollup), the important interpretation of 'unknown', and the boundary against get_changes. There is no practical information an agent needs to call it correctly that is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, and the input schema is empty, so the baseline is 4. The description doesn't need to clarify parameter syntax; it focuses on output and usage, which is appropriate for a parameterless read-only endpoint.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific resource and verb: 'Per-feed freshness for the DC Hub ingest layer' with one row per feed, and answers a concrete question ('are any of your sources stale right now'). It also explicitly differentiates from siblings by saying 'Do NOT use for the freshness of one dataset (use get_changes)', so an agent can tell it apart from get_changes and similar tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit when-to-use ('Answers "are any of your sources stale right now"') and when-not-to-use with a named alternative ('Do NOT use for the freshness of one dataset (use get_changes); this is ingest health, not content'). This leaves no ambiguity about when the tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly/idempotent annotations, the description discloses data provenance (USGS ASCE 7, NOAA via ACIS), a strict no-estimation policy, explicit unavailable states for missing data, and radius-dependent failure behavior. This gives the agent a strong mental model of side effects and edge cases.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but information-dense and front-loaded with purpose and scope. Every sentence earns its place, especially the grounding, example call, return shape, and exclusions. It could be slightly more scannable with structure, but it is appropriately sized for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists, the description still covers the main return sections, failure modes, data sources, geographic limitations, and alternatives. It is complete enough for an agent to select and invoke the tool correctly, including knowing what happens when data is missing or the site is outside the US.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 meaningful usage context beyond the schema: the concrete example invocation, the purpose of radius_km as a station-snapping distance, and the consequence of exceeding it. This lifts it above baseline but doesn't add deep format details for every parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific purpose: providing seismic and climate intel for a lat/lon, tied to structural bracing and cooling design. It clearly names the resource and distinguishes itself from related tools like get_disaster_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.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says 'Use when' with a concrete use case, and gives alternatives: 'For natural-hazard ratings use get_disaster_risk; for one blended verdict use get_composite_site_score.' It also explains scope limitations for non-US locations and radius behavior, so an agent knows when this tool is or isn't appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only/idempotent, and the description adds substantial behavioral context beyond them: PeeringDB is global but thin outside dense US/EU metros, 'unknown' is not 'bad', and carrier_data_coverage determines whether score and single_carrier_risk are null. It explicitly warns not to report a 'none_in_region' site as greenfield, unserved, or build-required—information annotations cannot convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core purpose and a concrete example; every sentence earns its place, including the counter-intuitive 'unknown' caveat and sibling exclusions. It is long, but the density of consequential detail—null semantics, coverage distinction, and bucket meanings—justifies the length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers the full call context: what the tool returns, what each bucket means, when values are null, and when to use alternatives. Even with a rich output schema, the description adds interpretive semantics (e.g., 'unknown' vs 'confirmed', single-carrier risk) that the structured schema cannot express, so an agent has everything needed to call and interpret the result correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds value by explicitly marking lat and lon as required even though the schema's required array is empty, and by tying radius_km to 'reachable fiber carriers' with default and range. It also gives a concrete example invocation with parameter values, reinforcing meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: 'get the FIBER-READINESS / connectivity verdict for ONE parcel or site (lat/lon)' with concrete outputs (near-net distance, carrier count, single-carrier risk). It also distinguishes itself from siblings by naming what it is not: route mapping and full multi-factor suitability.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly scopes usage: 'Use when you need the FIBER-READINESS / connectivity verdict for ONE parcel or site' and gives exclusions with named alternatives: '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).' Also clarifies the critical 'unknown' vs 'no carrier' interpretation, which is essential for correct use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already list readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description adds substantial behavioral context: the withdrawal/restoration history, the three repaired defects, the UNSCORED-vs-low-score semantics, and the explicit guidance that UNSCORED means absence rather than a poor score. It also names the gas_price_series field as a way to see which EIA series priced the state.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long, but most sentences earn their place because the tool history is genuinely complex. It is front-loaded with the core purpose, then gives correction history, data-interpretation warnings, and sibling routing. Some redundancy exists between the main description and the state parameter description, so it is not maximally concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with withdrawal/restoration history, scoring semantics, and a sibling-data boundary, the description is remarkably complete. Combined with the output schema, the agent has enough context to call the tool correctly, interpret UNSCORED results, avoid comparing incompatible values, and route pipeline-related queries to get_gas_intelligence.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 both parameters. The description and state parameter go beyond the schema by explaining what the response includes (DCGI score, verdict, gas_price_series, unscored_reason) and how to interpret UNSCORED. The limit parameter receives no additional description, but that is acceptable given the schema already defines its range and behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a precise verb-plus-resource statement: it provides the per-US-state Data Center Gas Index (DCGI) natural-gas suitability score. It also clearly differentiates itself from get_gas_intelligence by stating that pipeline, operator, and parent-midstream data belong to that sibling tool, and it warns that gas-fired $/MWh figures are not restored here.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit routing guidance: use get_gas_intelligence for pipeline, operator, and parent-midstream data, and avoid treating restored DCGI values as comparable to pre-2026-08-08 figures. It also clearly marks gas-fired $/MWh values as still withdrawn, telling the agent what this tool does NOT cover.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint/idempotentHint annotations, the description discloses important behavioral traits: freshness is not uniform, mix and demand have separate clocks with mix_age_hours and demand_vs_mix_lag_hours fields, some grids report no gas share, and Australia/Singapore are unranked in partial_grids. This level of caveat disclosure is exceptional and prevents the agent from misinterpreting stale or partial data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long and dense, but it earns its length given the complexity of the data source and the many caveats. It is front-loaded with the core scope and key data, then systematically covers freshness, exceptions, and provenance. Minor redundancy like 'Try: get_grid_scoreboard' and the very long parenthetical enumeration prevent a perfect score, but the structure is purposeful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter tool, the description is remarkably complete: it lists all regions, all metrics, freshness caveats, source attribution, unranked grids, Brazil's missing gas share, and the specific fields to check before narrating results. Given the output schema exists, this provides everything an agent needs to call and interpret the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the input schema is trivial and the description cannot add parameter-level meaning. The baseline for 0-param tools is 4, and the description instead enriches understanding of the returned fields (mix_period, mix_age_hours, freshness_basis, partial_grids, counts_basis), which is appropriate for this parameterless tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a concrete resource ('GLOBAL grid scoreboard') and specifies exactly what it returns: ranked grids with renewable share, gas share, fuel mix, and demand. It also distinguishes itself from sibling tools by explicitly comparing against compare_isos (pairwise) and get_grid_data (single ISO), so an agent can select it unambiguously.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit when-to-use guidance: 'One call answers which grid worldwide is greenest, or most gas-reliant, for siting a data center?' and explicitly contrasts with alternatives ('vs compare_isos (pairwise) or get_grid_data (single ISO)'). It also gives example queries ('which grid is cleanest right now', 'how is ERCOT doing at this moment'), leaving no ambiguity about when this tool is the right choice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, but the description adds substantial behavior beyond that: greedy priority-order filling under max_tokens budget, per-section token counts with as_of timestamps and citable URLs, a used_tokens/omitted response shape, and an explicit citation requirement ('Cite DC Hub'). This meaningfully enriches the agent's model of what a call does and what it will get back.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but dense and well-ordered: use case, package contents, example, params, return shape, exclusions, citation. The use case is front-loaded. Minor deduction because the 'Params:' block largely duplicates what the schema already specifies at 100% coverage, and the parenthetical listing of contents is somewhat run-on; still, nearly every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with heavy sibling overlap and an output schema already present, the description leaves nothing missing: the selection condition, four disambiguation exclusions, budget semantics, return structure, citation obligation, and a worked example are all covered. An agent can determine when to use it, invoke it correctly, and interpret the result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 above the schema by explaining the behavioral consequence of max_tokens (sections greedily filled in priority order until budget is exhausted, with omitted sections reported) and by giving a concrete invocation example. The iso values are repeated from the schema, which is redundant but harmless.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a precise verb+resource: 'returns a token-budgeted context pack for a US ISO/RTO' and characterizes itself as 'the narrative briefing pack.' It explicitly names the siblings it is not (get_grid_data, get_grid_intelligence, compare_isos, get_grid_scoreboard), so an agent can visually distinguish it from the four most similar tools without opening their schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It opens with an explicit 'Use when' condition (WHOLE-grid briefing for context window), then gives four explicit 'Do NOT use' exclusions each mapped to a named alternative tool, plus a non-US routing instruction. The worked example ('Brief me on ERCOT for data-center siting') grounds the guidance further. Nothing is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark this read-only/idempotent/non-destructive, and the description adds significant behavioral context beyond that: the EIA-860M data source, nationwide coverage including non-ISO regions, and status-code semantics. It also discloses what is returned (summary plus largest projects).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but front-loaded and every sentence contributes, including the Try example and negative guidance. It is longer than necessary for a simpler tool, but the added length is justified by the tool's breadth.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the 5 optional parameters, output schema, and annotation safety profile, nothing an agent needs to select and call this tool correctly is missing. It covers scope, filters, return shape, examples, and sibling routing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the parameters are already well documented. The description adds extra value with concrete examples (state=VA, ba=PJM/ERCO/SOCO/TVA/AZPS) and status-code mappings, pushing it beyond the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: it returns the forward power-generation pipeline (planned/permitting/under-construction), with explicit example questions. It also differentiates itself from interconnection-queue feeds and sibling pipeline tools, so an agent can tell what it is not.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It opens with exactly when to use it ('when a user asks WHERE NEW POWER GENERATION is coming online'), includes a working example query, and closes with explicit exclusions and alternatives (get_grid_intelligence/get_grid_data for operating capacity, get_pipeline for data-center construction).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations cover read-only/idempotent safety, and the description adds substantial behavior beyond that: the HARD ISO-cut semantics of max_ttp_months (SPP ~24 is the only ISO under 30, so <=30 can return nothing), the ~83% geocode rate, the sparse ~260-node fiber dataset with county-centroid origin ('NOT last-mile fiber'), and the 7-day-TTL candidate/snapshot contract with 'deterministic candidate_expired on lapse — never a silent recompute.' None of this contradicts the readOnly/idempotent annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The purpose, method, and scale are front-loaded in the first sentence, with the example and the critical hard-cut NOTE well placed immediately after the parameter list. The tail (CANDIDATE CONTRACT, ZERO-DRIFT CHAINING — roughly a third of the ~280 words) is verbose for a tool description and some of it could be condensed to 'see contract doc,' though nearly every sentence does carry a real behavioral fact.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 9-parameter, 0-required tool with spatial predicates and cross-tool chaining, the description covers purpose, example, return shape (backed by an output schema), data-quality limitations, exclusion conditions, and the chaining contract — nothing needed to invoke it correctly is missing. The only minor gap is explicit truncation/pagination behavior when survivors exceed the limit parameter.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with rich per-field docs, so the baseline is 3; the description earns a 4 by adding combinatorial guidance the schema lacks — the worked call (min_mw=1000 fuel_type=gas max_ttp_months=34), the 'use >=34' threshold to avoid empty results, and the cross-parameter guarantee that geocoded_only=true carries both the handoff and frozen coordinates.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The opening sentence names a specific mechanism and resource — 'Server-side SET-REDUCTION over the US ISO interconnection queue' — with scale context (~5,300 projects, 7 ISOs, ~1,744 GW). Two concrete example queries ('show me 1 GW+ gas projects that can connect in under three years') and the explicit 'do NOT use for the ISO-level GW aggregate (use get_interconnection_queue)' clearly disambiguate it from the most confusable siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Contains an explicit routing rule: 'Use for high-cardinality siting/arbitrage scans; do NOT use for the ISO-level GW aggregate (use get_interconnection_queue) or a single-site read (use analyze_site).' It also instructs chaining survivors into analyze_site via site_evaluation_handoff and candidate_id, so the agent knows both what this tool is for and what comes next.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses important behavioral traits beyond annotations: async execution, ~35s wait, inline return vs task_id response, polling mechanism, rate limit, and key requirement. It complements the readOnly/idempotent/destructive hints without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with purpose and includes high-value exclusions, examples, and constraints. It is somewhat dense and repeats a few details already present in the schema, but every section earns its place given the async complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description fully covers the async lifecycle: submit, wait, poll, fetch, quota, and key requirement. With an output schema present for return values, nothing needed for correct invocation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 meaningful OR-choice semantics: question for a new dossier vs task_id for polling, plus example usage. Some details repeat schema descriptions, but the added context still raises the value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific action ('Commission'), a specific resource ('ASYNC, CITED research dossier'), and the scope of sources (DC Hub's corpora). It also explicitly contrasts this with 'not a lookup', helping distinguish it from the many sibling search and get tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use the tool ('synthesizes ACROSS sources with citations') and when not to ('Do NOT use for a single fact'), naming the alternatives (search_intelligence / semantic_search). It also covers the key requirement, daily quota, and async polling workflow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses persistence across conversations, API-key scoping, creation of the list if new, snapshotting of objectives and current percentile score, default equal weighting when objectives are omitted, and reuse of ranked metrics. The mutation side effect is clearly stated, the API-key dependency is surfaced, and there is no contradiction with 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is longer than average but every sentence is information-dense, front-loading the core purpose and persistence guarantee before usage and parameter guidance. The minimal call example and conditional ranking instructions earn their place, with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 4-parameter stateful mutation with only basic annotations, the description covers the minimal and rich call forms, optional parameters, behavior over time, API-key requirement, and complementary next step. The output schema fills return-value details, so nothing essential is missing for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, yet the description still adds meaning: it identifies the MINIMAL site object shape, explains that richer metric fields get reused in re-scoring, clarifies that objectives are optional with a default equal-weighting behavior, and notes that shortlist_name is created if new. This is substantial added value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: 'Save a site into a PERSISTENT, named shortlist that survives across conversations.' It distinguishes the tool from read/complementary siblings by emphasizing persistence, API-key scoping, and Phase 5 statefulness, and it specifically names get_shortlist as its pair, so an agent can tell what this tool is for.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description says 'Use to build a durable siting shortlist across days/weeks' and says to pair with get_shortlist for re-scoring, giving clear context. It also provides a prerequisite and example call shape ('call claim_free_key first'). It does not explicitly state when not to use it versus the similar save_site sibling, so it misses the when-not exclusion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false; the description adds substantive behavioral context: relevance-ranked results, cross-corpus scope, default corpus/all and k semantics, citable source fields, and a required citation instruction. 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core use case and dense with useful examples and routing guidance. It is a single long paragraph with some redundancy (citation fields appear twice), but still efficient given the tool's multi-corpus complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a multi-corpus semantic search tool, the description fully covers purpose, usage, parameters, output shape, alternatives, and citation behavior. The output schema already handles return-value details, so nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers all four parameters at 100%, so baseline is 3; the description adds value by explaining q as a natural-language query with example usage, enumerating corpus options, and noting the k range and default. It omits the query alias detail, but the schema covers that well.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific purpose: semantic/meaning-based retrieval across named corpora (news, deals, facilities, market narratives), ranked by relevance, with concrete examples. Explicitly distinguishes itself from exact-keyword tools like get_news, list_transactions, and search_facilities, making its role unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says to use it for conceptual/fuzzy questions where keyword filters fall short, names the exact-filter siblings it complements, and directs agents to get_market_context for full market briefings. This gives clear 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.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description reveals important behavioral traits beyond the annotations: it creates a subscription for future notifications rather than returning immediate data, email delivery is forced to the bound address, and webhook delivery requires the Pro tier. It also flags the bind_email prerequisite. This is rich behavioral context that readOnlyHint/destructiveHint alone do not convey, and it does not contradict any annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is longer than average but every section contributes: purpose, prerequisite, channel-specific details, example, and an explicit don't-do-this. There is a slight redundancy between 'not just query them' and the later exclusion sentence, but overall it is efficient and front-loaded with the core action and example.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers all essential aspects: the domain (DCPI markets), the exact alert trigger, delivery channels, pricing tiers, required prerequisite, and a negative instruction to avoid misuse. Since an output schema exists, describing return values is not necessary. The description is complete enough for an agent to call this tool correctly without additional context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 goes further by explaining what channel values mean ('email' free, 'webhook' Pro), stating that destination is ignored for email because it is forced to the bound address, and providing a working example with actual values. This adds meaningful context beyond the raw schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Subscribe to movement alerts for a DCPI market' and 'get notified when its Excess-Power / Constraint score moves.' It also explicitly differentiates this tool from reading a market by saying 'Do NOT use to read a market right now (use get_market_dcpi_rank); this SUBSCRIBES to future movement,' 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.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear when-to-use guidance, including the exclusion: 'Do NOT use to read a market right now (use get_market_dcpi_rank).' It also mentions a prerequisite ('call bind_email first'), channel-specific usage (email vs webhook), tier constraints (Pro for webhook), and a concrete example invocation. This fully routes the agent on when and how to use the tool versus alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly/idempotent annotations, the description discloses that it 'never resolves or invents a value', makes no network call, requires no key, and explains omission behavior (as_of omitted yields RETRIEVED). It also details the licence-layer nuance and warns against over-claiming, which materially enriches the agent's understanding of what the tool does and does not do.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is longer than average, but every sentence carries useful information—the licence explanation, the no-network-call guarantee, the omission behavior, and the negative usage instruction all earn their place. It is front-loaded with the core purpose and the licensing warning, making it easy for an agent to key in on the essential guidance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (licence-per-layer logic, multiple input fields, and citation-specific behavior), the description is fully sufficient. It covers return fields, error/omission behavior, network/key requirements, and the distinction from data lookup tools. An agent has everything needed to call it correctly without consulting additional context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents all parameters thoroughly (100% coverage), so the baseline is 3. The description adds value by framing the parameters as 'what you read off the response you are citing' and by explaining the legal consequence of the layer parameter ('flat CC-BY-4.0 over a facility record is an over-claim'). This is genuinely additive, though some of the as_of behavior is duplicated from the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb+resource: it 'returns one paste-ready attribution line' for a cited DC Hub figure with the correct licence for that layer. It clearly distinguishes itself from sibling data tools with the explicit 'Do NOT use to look a figure UP' instruction, 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.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly scopes usage to 'right before you QUOTE a DC Hub figure to a human' and gives a concrete when-not-to-use instruction: call the data tool first when you need to look a figure up. This leaves no ambiguity about when to invoke this tool versus alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool as read-only, idempotent, and non-destructive, and the description reinforces this by saying it runs the analyze_site read. It adds non-obvious behavior: capacity_mw is forwarded to each site but does not affect overall_score, and it discloses that the tool is paid/Pro with a locked free-tier preview.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but well organized, with usage context, an example, parameter guidance, return details, and exclusions. It is longer than strictly necessary because it restates a detailed return shape even though an output schema exists, but the extra detail is structured and useful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool of this complexity, the description covers when to use it, what it does, parameter behavior, output characteristics, paid-tier restrictions, and explicit alternatives. Nothing critical is missing for an 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.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description still adds meaningful semantics beyond the schema. It explains the locations semicolon delimiter and 2-4 limit, gives a typical capacity_mw range, and clarifies that capacity_mw does not influence the ranking. This prevents an agent from misinterpreting the parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a precise scope: a side-by-side winner picker for 2-4 candidate parcels, ranking by overall score with a recommended pick and reason. It clearly differentiates from analyze_site and rank_markets, making the tool's purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says to use this when a user has narrowed to 2-4 candidate parcels and wants a comparison, and provides a concrete example. It also gives clear exclusions: do not use for a single site (use analyze_site) or to rank entire markets (use rank_markets), leaving no ambiguity about when this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description goes well beyond these by disclosing key behavioral traits: it 'never imputes a missing one', water is 'unavailable' only outside basin coverage 'never faked', market/DCPI is v1-unavailable, and it only scores over VALIDATED factors. It also gives an explicit example call. This provides rich behavioral context that annotations don't cover, making the tool's operation transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Though the description is long, it is information-dense with zero waste. The first sentence front-loads the core purpose and scope, then immediately contrasts with siblings, explains coverage behavior, gives a concrete example, lists the return object fields, and ends with explicit routing to alternatives. Every sentence earns its place, and the structure is logical and scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has an output schema that covers return values, so the description doesn't need to explain them in depth. The description covers the key behavioral nuances (never fakes, validated-only factors, conditional confidence), the exact alternative tools, and a working example. Given the complexity of the scoring logic and the large sibling set, the description is thoroughly complete — an agent has everything needed to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for all 6 parameters, so the schema already documents each param (aliases, units, ranges). The description adds a concrete example call (lat=33.45 lon=-112.07 state=AZ) that illustrates usage, and clarifies that lat/lon are required in practice despite optional schema flags. This adds marginal value beyond the schema, so a 4 is appropriate per the baseline-plus-extra rule.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb+resource+scope: 'ONE honest 0-100 site suitability/risk verdict for a lat/lon WITH an explicit per-factor coverage map'. It clearly distinguishes from siblings by contrasting with analyze_site (full raw data dump) and naming the exact alternatives. An agent can immediately know what this tool does without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit when-to-use ('Use when a user wants ONE honest 0-100 site suitability/risk verdict'), when-not-to-use ('Unlike analyze_site...', 'market/DCPI is v1-unavailable (use rank_markets)'), and names specific alternatives: analyze_site for full data, compare_sites for 2-4 sites, rank_markets for whole-market ranking. It also explains the coverage logic (validated factors vs. unavailable). This is a model of usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnly, idempotent, non-destructive behavior, and the description adds valuable behavioral context beyond that: it discloses that only DCPI market-health has a temporal series, that static dimensions are declared static rather than fabricated, and that missing snapshot history yields coverage:unavailable. This integrity-related transparency is genuinely useful for an agent deciding whether the result is trustworthy.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but every sentence earns its place: use case, return value, integrity constraints, parameter clarification, output shape, and alternatives. It is front-loaded with the trigger phrasing and temporal angle, and it contains no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With a rich output schema already present, annotations covering safety, and a description that explains the temporal semantics, integrity constraints, parameter relationship, and alternative tools, an agent has everything needed to select and invoke this tool correctly. Nothing important is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 real value by clarifying the OR relationship between facility_id and market, giving example formats for since ('7d'/'30d'), and noting the default. This goes beyond the schema's individual parameter descriptions, though not dramatically so.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('get'), a precise resource ('facility risk delta'), and the exact conceptual scope: temporal change in a facility's or market's risk profile. It explicitly names the temporal question it answers and contrasts itself with static point-in-time tools, making it clearly distinguishable from siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description is explicit about when to use the tool: when a user asks what has changed recently, such as 'has this site gotten riskier lately?'. It also names the alternative tools for point-in-time risk (get_composite_site_score / get_disaster_risk / get_climate_intel) and states what to do when no snapshot history exists, giving the agent clear routing rules.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Even with readOnly/idempotent/non-destructive annotations covering the safety profile, the description discloses critical dynamic behavior beyond those: 'The `projects` field CHANGES SHAPE with the call' and gives the specific array-versus-summary-object shapes. It also surfaces ERCOT-specific data provenance and the null behavior for other ISOs, which an agent must know to interpret results safely.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Though dense, the description is carefully ordered: core function, key exception, sources, parameter usage, shape-change warning, use cases, and exclusions. The starred shape warning is front-loaded at the exact point where it matters, and every sentence carries load-bearing information with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, the description need not enumerate return fields, but it still covers the purpose, the parameter's effect, the only ISO with non-null data_center_gw, the provenance, and explicit sibling routing. The tricky `projects` shape change is called out even though it risks being redundant with an output schema, which demonstrates thoroughness for callers.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single iso parameter is already fully documented in the schema with allowed values and omit behavior (100% coverage), so the baseline is 3. The description adds value by linking the parameter to the dynamic shape of `projects` — 'with iso= it is an ARRAY...; with iso omitted it is the all-ISO SUMMARY OBJECT' — giving the parameter semantic weight beyond the schema's field listing.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a crisp verb+resource+scope: 'ISO interconnection queue snapshot: total queued GENERATION capacity ... per ISO.' It immediately distinguishes itself from sibling tools by name (get_grid_intelligence, grid_transition_radar) and specifies the exact fields returned, so an agent can tell what it does without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage guidance is explicit and bidirectional: 'Use for queue-depth site-selection and AI/data-center-load saturation intel' and 'Do NOT use for a single-site time-to-power read (use get_grid_intelligence) or forward-looking emergence (use grid_transition_radar).' It also instructs how to vary the call ('Pass iso=ERCOT ... to drill down'), leaving no ambiguity about when to choose this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes far beyond the annotations by revealing that the tool composes multiple data sources, never blends confidence classes, counts only under-construction+testing minus retirements in the derived cumulative_firm_signal_mw, and explicitly declares what is out of coverage (constraint_coverage). It also discloses the honesty limitation that generation is not deliverable load and that no delivery dates are provided. This is rich behavioral context that the annotations (readOnly, idempotent, non-destructive) do not convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but front-loaded with the core purpose, followed by composition details, honesty line, and routing guidance. It is longer than average because it carries a lot of behavioral transparency, but every sentence earns its place. A slight demotion for length and some redundancy in the honesty line, but overall well-structured and scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has an output schema, so return values need not be spelled out. The description covers the tool's inputs, data sources, derivation logic, exclusions, limitations, and alternatives. Given the complexity of the tool and its sibling ecosystem, this is complete enough for an agent to call it correctly and interpret its results appropriately.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Even though schema description coverage is 100%, the description adds significant meaning to the parameters: state is the timeline grain and can span ISOs, years defaults to 5, and mw is clearly labeled as 'CONTEXT ONLY' and 'never converted into an energize-by date'. The example 'state=OH' also demonstrates parameter usage. This exceeds what the schema alone provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('get') and resource ('power availability timeline') and distinguishes itself from siblings by emphasizing 'WHEN' for one US state, year by year. It explicitly names what it is not (raw project list, live headroom, queue survivors, ranking) and gives concrete example queries, making it easy for an agent to select correctly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says when to use this tool ('Answers when is new capacity landing in Ohio') and lists what NOT to use it for, naming sibling tools (get_power_pipeline, get_grid_intelligence, get_refined_queue, rank_markets, ai_capacity_index) and their distinct purposes. It also provides a concrete invocation example ('Try: get_power_availability_timeline state=OH') and clearly states the tool's scope boundaries (supply-side only, no load-interconnection promises).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds valuable context beyond those hints, especially the critical ai_ready semantics: it ranks by DCPI buildability rather than installed capacity, and warns that highly built-out markets may be AVOID for new AI load. It also explains the return envelope and the follow-up use of metro_slug.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but well-structured, with routing directives front-loaded, followed by usage, example, parameter reference, return shape, and explicit exclusions. A few points are repeated, such as the contrast with execute_plan, but every sentence carries useful decision-relevant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the large sibling set and the high risk of confusing this tool with execute_plan, get_market_intel, or analyze_site, the description covers all necessary context: when to use, when not to use, how to invoke, what the output looks like, and how to continue the workflow via get_market_dcpi_rank. The ai_ready caveat prevents a costly misinterpretation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description goes further: it enumerates allowed criteria values with meanings, states defaults for criteria, region, and limit, gives a practical limit range of 1-50, and shows a concrete example with parameter assignments. The deep explanation of the ai_ready criterion adds meaning the schema alone does not convey.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as producing 'one ranked list across the 300+ market set' and explicitly says 'rank_markets IS the right call' for list-only ranking requests. It distinguishes the tool from execute_plan, get_market_intel, and analyze_site, making its purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides detailed when-to-use and when-not-to-use guidance: siting questions with verdicts/grid checks go to execute_plan, single-market deep reads go to get_market_intel, lat/lon scoring goes to analyze_site, and pure ranking stays here. This explicit exclusion list leaves no ambiguity about routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses far more than annotations: deterministic behavior, fail-closed constraints, weight renormalization, missing_objectives declaration, relative vs absolute normalization fallback, stale candidate handling, and require_complete exclusion behavior. Annotations already mark it readOnly/idempotent/non-destructive, and the description adds substantive behavioral context without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long, but it is information-dense and front-loaded with purpose and usage before mechanics. Some details are repeated across description sections and the schema (e.g., objective semantics), but given the tool's complexity and nuanced scoring contract, the length is justified.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Although an output schema exists, the description complements it with return-field semantics (rank, objective_score, normalized, normalization_basis, missing_objectives, objective_status, excluded_incomplete, candidate_contract). It also covers input sourcing, edge cases, and autonomous workflow recommendations, making the definition complete for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description goes well beyond the schema: it explains signed weights with concrete examples, absolute vs percentile semantics, shortlist objective reuse, the candidate_id contract from get_refined_queue, and fail-closed constraint behavior. This materially helps an agent construct correct invocations.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource ('multi-site ranking/optimization under constraints'), names the exact output entity (_entity=ranked_sites), and differentiates itself from siblings like analyze_site and get_refined_queue. An agent can immediately tell what this tool does and how it differs from nearby alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit usage guidance is stated: 'Use for pick the best N sites under constraints; for one site use analyze_site; to get the candidate set first use get_refined_queue.' It also explains when to use candidates vs shortlist_name, and when percentile vs absolute is appropriate. This is model behavior for routing an agent to the correct tool and call pattern.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only say readOnlyHint=false, destructiveHint=false, idempotentHint=false. The description adds substantial behavioral context beyond that: keyless calls return auth_required, the call WRITES to the account, it 'Builds a persistent shortlist an agent can revisit + monitor', and passing market triggers a DCPI baseline snapshot that changes later list_saved_sites/get_changes output. No contradiction with annotations — readOnlyHint=false aligns with the stated write behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Although long, every sentence earns its place: auth warning is front-loaded, followed by function, parameters, return value, side effect, follow-up workflow, exclusions, and a runnable example. The structure is logical and dense with no filler or tautology, appropriate for a tool with 10 parameters and an auth flow.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity — account writes, auth requirements, DCPI side effects, and a 10-parameter surface — nothing material is missing. The description covers the auth prerequisite, return value (saved site id), the persistent-shortlist behavior, the alert follow-up, sibling alternatives, and an executable example. An output schema exists to document return details further.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 beyond the schema by clarifying that lat + lon are the operative inputs despite zero required params, explaining market's side-effect behavior ('DC Hub snapshots the site's DCPI baseline at save time'), and providing a concrete example mapping values to parameters. This pushes it above baseline, though the schema already documents the aliases well.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb + resource + destination: 'Save a candidate data-center site to your DC Hub account to track it across sessions.' It explicitly differentiates itself from the confusable siblings by stating 'Do NOT use to read back the shortlist (use list_saved_sites), download it (use export_dataset), or score a site (use score_facility).' An agent can select this tool correctly without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit when-to-use context ('Answers "remember this parcel for me"...'), a named prerequisite ('call claim_free_key FIRST'), three named exclusions with alternative tools, and a follow-up workflow (pass the returned id to set_site_alert). This fully routes the agent on when to use it versus alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true; the description adds substantial context beyond that: what the response contains (baseline vs scenario composite, component breakdown, exact formula/weights), that the composite is deliberately NOT the DCPI, and keyless vs keyed caller differences (top-3 preview vs up to 25). These behaviors are not visible in annotations or schema, and 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact given the tool's complexity. Every sentence contributes: purpose, parameter semantics, return structure, keyless limitations, example call, and exclusions. It is front-loaded with the core purpose and ends with a crisp example and alternative routing. No redundant or filler content exists.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a counterfactual simulation tool with 7 optional parameters and an output schema, the description covers all essential context: what it computes, how to invoke it, what the response contains, auth/key behavior, parameter constraints, an example, and when not to use it. The existing output schema covers return details, so the description is appropriately comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds value beyond the schema by explaining the overall parameter contract ('all optional, pass at least one delta'), giving a concrete invocation example ('simulate_scenario avg_kwh_cents_pct=30 top_n=10'), clarifying units (points vs months) with examples, and defining ranking semantics ('ranked by |score change|'). This earns an above-baseline score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Counterfactual WHAT-IF re-scoring of 300+ DC Hub power markets under YOUR explicit deltas' and phrases the core question it answers ('what happens to the market ranking if conditions change'). It clearly distinguishes this from present-day ranking (rank_markets) and trajectory extrapolation (predict_market_trajectory), making the tool's unique role unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit when-to-use guidance ('explicit hypotheticals'), warns against using it for present-day ranking and trajectory extrapolation by naming the exact sibling tools to use instead, and states the requirement to 'pass at least one delta' even though all params are optional. This leaves no ambiguity about when to invoke this tool versus alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false; the description goes well beyond this by disclosing the paid-key gating of the synthesis decision layer, the one-call find-to-verdict flow, and the default verdict behavior when markets are all AVOID. It also names the output fields an agent should expect, which is 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but efficient: it states the outcome, lists output components, gives an example, and provides explicit exclusions—all in a few sentences. Every sentence earns its place; no filler or redundant restating of the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity, the output schema, and the rich sibling context, the description is complete. It conveys the intended workflow, output composition, paid-tier limitation, and routing guidance, while the schema covers parameter details. An agent has everything needed to select and call this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds value by mapping high-level inputs ('capacity target + geography + deadline') to specific parameters and providing a concrete example with realistic values. This lifts it above mere schema repetition, though the schema still does most of the parameter-documentation work.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Guided end-to-end data-center site selection.' It enumerates concrete outputs (ranked shortlist, DCPI verdict, excess-power headroom, time-to-power, ISO, paid synthesis layer) and immediately distinguishes itself from sibling tools by naming analyze_site and get_dchub_recommendation. There is no ambiguity about what this tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives an explicit 'Do NOT use for...' section with named alternatives and the exact condition for each exclusion. It also provides a runnable example invocation (capacity_mw=100 region=TX max_months=24), making it clear when and how to use this tool versus alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond readOnly/idempotent annotations, it discloses key behaviors: location resolves to market centroid rather than parcel, candidate_id uses frozen mint and fails closed with candidate_expired, capacity_mw adds a capacity_context block without moving overall_score, and free vs Pro returns are clearly separated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Long but dense: front-loaded use case, example, parameter notes, return structure, and routing exclusions. No filler; the length is justified by 12 parameters and several behavioral caveats.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers input modes, output shape, free/pro constraints, alias semantics, failure behavior, and alternative tools. An agent has everything needed to decide, call, and interpret this tool without extra lookups.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Even with 100% schema coverage, the description adds meaning: it explains parameter relationships and side effects (capacity_mw sizing, location's resolved_from block, candidate_id ignoring lat/lon, state improving tax lookup), which are not evident from the schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with an explicit use case ('ONE specific lat/lon... full multi-factor data-center suitability read') and gives a concrete example. It differentiates itself from siblings by naming what it is not (compare_sites, find_alternatives).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit when-to-use guidance, a call example, and direct exclusions with named alternatives: water/disaster/climate/tax reads route to get_water_risk etc., 2+ sites to compare_sites, site matching to find_alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond annotations by detailing the exact return object, fallback behavior when context does not match, and the critical caveat that free text does not parse. Annotations already declare readOnly/idempotent/destructive hints; the description adds edge-case behavior and response shape 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but every sentence earns its place: purpose, example, parameter rule, return contract, non-matching behavior, and exclusions. It is well-structured and front-loaded with the main intent, with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with one parameter, rich annotations, and an output schema, the description fully covers the invocation contract, the edge case of invalid input, and the key exclusions. An agent has all necessary information to select and call this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Though schema coverage is 100%, the schema's parameter description is misleading ('Free-text description...'), while the tool description corrects it by enumerating the four literal accepted categories, giving an example call, and explaining the null/generic consequences of invalid input. This is essential meaning that the schema fails to provide.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific use case: obtaining a ready-to-quote description of DC Hub in one of four categories plus a live top-ranked market pocket. It distinguishes itself from siblings by naming analyze_site, rank_markets, and site_selection_canvas, so an agent can immediately tell where this tool fits.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use the tool (descriptive category lookup) and when not to use it (single lat/lon, single-criterion ranking, open-ended siting questions), naming the exact alternative tool for each exclusion. It also describes behavior for invalid context, preventing misuse.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already signal read-only, idempotent, non-destructive. The description adds meaningful behavioral context: the dataset scope (182k units, 170+ countries), the semantics of pipeline=true being exactly the forward set (announced + pre-construction + construction), and the return shape (summary of total MW by fuel + count by status plus largest units). It does not contradict 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Though fairly long, every sentence earns its place: use-case scoping, dataset scale, filter options, return summary, example calls, and explicit exclusions. The key 'when to use' instruction is front-loaded, and the negative routing is clearly placed at the end. Formatting with bold and code examples improves scannability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 7 optional parameters, no enums, and a large sibling set, the description covers the full decision space: what data is available, how each important filter behaves, what the response contains, and which related tools to use instead in specific situations. An output schema exists, so not detailing every return field is acceptable. An agent has everything needed to invoke this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description still adds value by explaining the union semantics of comma-separated fuel values, the exact bbox format (minLng,minLat,maxLng,maxLat), the pipeline filter collapsing multiple statuses, and showing real examples of country and fuel values. This goes well beyond the schema's one-line descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description defines a specific verb plus resource: 'power plants/units WORLDWIDE or in a NON-US country' with both operating and forward pipeline. It explicitly differentiates from US-focused siblings by naming get_grid_intelligence, get_grid_scoreboard, and get_power_pipeline as the alternatives, so an agent can select this tool without ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit when-to-use context (worldwide/non-US, all fuels, including pipeline) and explicit when-not-to-use with named alternatives for US grid telemetry/headroom and US planned-generator feeds. It also provides example queries and a concrete recommended call ('Try: get_global_power country=India pipeline=true').
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already signal readOnlyHint, idempotentHint, and destructiveHint:false, and the description adds meaningful behavioral context beyond that: data comes from FILED submissions rather than forecasts, and meta.caveat flags that filed dates are subject to ISO reliability reviews and RMR extensions. This gives the agent an accurate model of data reliability without contradicting annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but dense and well-ordered: main purpose first, output entities next, example call, honesty caveat, then sibling routing. Every sentence contributes operational guidance, with no filler or repetition of structured fields.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose, output shape, parameter semantics, a worked example, data caveats, and explicit alternatives. Combined with the output schema and annotations, an agent has everything needed 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.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds crucial semantic relationships: target_mw is also passed through as the handoff's analyze_site capacity_mw, region_iso matches the generator's own EIA balancing-authority code rather than state lines, and fuel_filter is substring-matched. These details materially improve correct parameter use beyond the schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: it scans scheduled EIA-860M generator retirements to find near-term transmission grid headroom. It directly answers user questions like 'where is grid capacity about to free up' and distinguishes itself from siblings by naming get_refined_queue and analyze_site as alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit routing guidance: 'Use to find WHERE capacity opens next; for what's already queued use get_refined_queue; for one site use analyze_site.' It also includes a concrete example call with parameters, making when and how to use the tool unmistakable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

Copy to your README.md:

[![dchub-mcp-server MCP server](https://glama.ai/mcp/servers/azmartone67/dchub-mcp-server/badges/card.svg)](https://glama.ai/mcp/servers/azmartone67/dchub-mcp-server)

Score Badge

Copy to your README.md:

[![dchub-mcp-server MCP server](https://glama.ai/mcp/servers/azmartone67/dchub-mcp-server/badges/score.svg)](https://glama.ai/mcp/servers/azmartone67/dchub-mcp-server)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/azmartone67/dchub-mcp-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server