DC Hub

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

Annotations only supply safety flags (readOnlyHint=false, idempotentHint=false, destructiveHint=false); the description goes well beyond them by disclosing prerequisites (an identified caller via claim_free_key + bind_email, or an OAuth connection; accept_terms=true), the once-per-terms-version recording behavior, and the side effect of writing to DC Hub's lead register. It even states what unlocks afterward (listing details open), which is exactly the guidance an agent needs before invoking a non-read-only tool.

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

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

Front-loaded with the trigger condition and constraint ('never on your own judgement'), and each clause carries signal (prerequisites, return, exclusions). It is densely packed into few sentences with parenthetical asides, which is efficient but slightly harder to scan than a shorter definition would be.

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

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

For a two-parameter, non-read-only tool with an output schema, the description covers trigger condition, caller identity prerequisites, version semantics, return values, and sibling exclusions. Nothing an agent needs to invoke it correctly is missing, and the output schema handles the return shape.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds provenance the schema does not: terms_version should come from access.unlock.terms.version returned by source_capacity, and omitting it sends the currently published version. These are real usage rules beyond the field documentation.

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

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

Specific verb+resource ('accept_capacity_terms' records acceptance of DC Hub capacity introduction terms) with the exact artifact named and linked. It explicitly distinguishes itself from the two nearest siblings, request_capacity_intro and source_capacity, so an agent can route without opening a schema.

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

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

States the precise triggering condition: call only when source_capacity returns a listing locked with access.reason terms_acceptance_required, 'never on your own judgement.' It also names the two prohibited uses and the correct alternative for each (request_capacity_intro, source_capacity), which is explicit when/when-not guidance.

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

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

Annotations already cover the safety profile (read-only, idempotent, not open-world, non-destructive), so the description's real contribution is freshness ('Refreshed Fridays 14:00 UTC') and the composite score's composition (depth + diversity + power), which the agent cannot get from annotations. The field enumeration partly duplicates the existing output schema, keeping it short of a 5.

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

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

Front-loaded with trigger and scope, and the use-case and do-not-use sentences each carry routing value. The one dense sentence enumerating return fields is somewhat long and partly redundant with the output schema, but no sentence is pure filler.

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

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

Given only two optional params, an output schema, and full annotation coverage, the description supplies everything else an agent needs: freshness cadence, what the score means, primary use cases, and explicit sibling alternatives. No gaps remain for correct invocation.

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

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

Schema description coverage is 100%, so both params (limit, horizon) are already documented, and the description only echoes the 30/60/90 horizon values in prose without adding format or edge-case guidance. Per the high-coverage baseline this is a 3.

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

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

States a specific verb and resource ('ranks data center markets') plus a precise scope ('where 100MW of AI training capacity can land in the next 30/60/90 days'). It explicitly distinguishes itself from three siblings (rank_markets, grid_transition_radar, and DCPI/rank_markets ai_ready), so an agent can route correctly 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.

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

Opens with an explicit trigger ('Use this when the user asks where AI compute capacity could land'), names concrete use cases (AI capex planning, GPU cluster siting, hyperscaler deal forecasting), and gives two explicit 'Do NOT use for' exclusions with the correct alternative for each. 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.

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds substantial behavior beyond that: out-of-coverage points return parcel_not_covered with an analyze_site preview plus coverage list and "never a guess," and representative_point is deliberately the largest member's centroid rather than the geometric center to avoid poisoning point-keyed reads. It also states hosted layer scope (VA, IL, TX, OH, UT, OR, IA, WY counties) and the downstream handoff.

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

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

Front-loaded with "Use this when..." and organized logically (inputs, return shape, handoff, alternatives). Dense with parentheticals and slightly long, but nearly every clause carries actionable information.

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

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

For a read-only analysis tool with an output schema present, everything an agent needs is there: both input modes, coverage scope, failure behavior, return shape, and the handoff to analyze_site and get_water_risk. Nothing essential is missing.

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

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

Schema coverage is 100%, so the schema already documents all parameters including aliases and geometry format. The description restates the geometry-vs-lat/lon alternative and the capacity_mw pass-through, adding modest clarity on the OR relationship but mostly reflecting what the schema already says.

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

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

Specific verb+resource: "structured read of its boundary" for a land parcel, with both input modes (own GeoJSON vs. lat/lon hosted-layer lookup) and outputs named. It is clearly distinguishable from analyze_site and get_refined_queue, which are both explicitly named.

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

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

Explicit when-to-use ("when you HAVE a boundary or a point on a specific parcel and want it anchored + sized") and names alternatives with their selection conditions: analyze_site for general lat/lon site scores, get_refined_queue for the queue survivor set. Even notes that queue rows carry no parcel identity, so they never auto-join.

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

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

With annotations already covering read-only/idempotent/non-destructive, the description still adds substantial behavioral context: tiering behavior (keyless returns verdict and power bands, free key adds a few reports/month, other scores need a paid plan), partial-result handling (surface human_message and its link), the missing_coordinates failure, and that mpp_pay returns a payment challenge with no money moving. It also discloses that capacity_mw adds a capacity_context block but does not affect overall_score.

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

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

Front-loaded with purpose and return shape, then progressively narrower detail (tiering, partial results, coordinate sourcing). Dense but nearly every clause carries decision-relevant information for a 14-parameter tool with payment tiers; only the repeated lat/lon requirement is redundant with the schema.

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

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

Despite an output schema existing, the description still covers what an agent needs to call correctly: required coordinate pairing, preferred candidate_id path, tier-dependent response completeness, error identifiers, and payment-approval gating. Nothing material for correct invocation is left unstated.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantics beyond the schema: capacity_mw is a context-only input that does not move the composite, candidate_id freezes coordinates and ignores lat/lon, and mpp_pay/mpp_credential require explicit human approval before charging. It restates the lat/lon co-requirement, which the schema already covers.

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

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

States a specific verb and resource — evaluating a site/coordinate for data-center suitability — and enumerates the concrete output (0-100 composite, verdict, power/gas/fiber/market/risk sub-scores, infrastructure and power cost). It also distinguishes the coordinate path from the market-name path, so an agent can tell it apart from siblings like compare_sites or get_composite_site_score.

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

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

Gives an explicit trigger ("Use this when the user asks whether a specific site or coordinate works for a data center") plus concrete input sourcing (take lat/lon from get_facility or search_facilities; candidate_id from get_refined_queue). It stops short of naming when a different sibling should be used instead (e.g., multi-site comparison or ranking), so it is strong context without full alternative routing.

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

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

Annotations declare this is a non-readonly, non-idempotent, non-destructive mutation; the description goes well beyond that by spelling out what binding does (makes the key recoverable via recover_my_key) and what it does not do (does not make identity durable), plus the consent rule for marketing. It does not state what happens on a repeat bind of an already-bound key despite idempotentHint=false, which is the one meaningful behavioral gap.

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

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

The usage trigger is correctly front-loaded, but the middle passage carries a lot of weight that does not help select or invoke the tool — the cohort statistics ('0 of 3 mature identities, 2026-08-12') and the OAuth aside read as internal justification rather than invocation guidance.

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

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

With an output schema present, return values need not be described; the description covers the mutation's benefit, its limits, and consent prerequisites well. What is missing is failure behavior (already-bound key, rejected placeholder address) which matters for a non-idempotent write.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters; the description only reinforces the email constraint ('pass only an address they typed'). It adds nothing beyond the schema on api_key or marketing_opt_in, so the baseline 3 applies.

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

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

The first sentence names the specific action (tie a DC Hub key to an email) and its trigger, and later sentences explicitly separate binding from recover_my_key and from OAuth sign-in. An agent can distinguish this from unlock_more_data or claim_free_key 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.

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

It states exactly when to call it ('user wants their key tied to their email, or a result said an email unlocks more'), gives the prerequisite (ask the human for their email first, pass only an address they typed), and names the competing alternative (OAuth sign-in, only offered after a 401 WWW-Authenticate challenge).

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

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

The description adds substantial behavior beyond the annotations: no key is needed to start, the key is returned with an embedded connect_url, free vs email-key limits are specified, and email-based recovery is explained. It also clarifies the 401/OAuth branch and that keys should be saved rather than re-minted.

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

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

The description is front-loaded with the triggering condition and core action, and most sentences carry operational guidance. It is dense and somewhat long, but the length is mostly justified by the branching rules around email, key recovery, and 401 challenges.

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

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

Despite having an output schema, the description still explains the important return values (key and connect_url) and their significance. It covers limits, email consequences, recovery, re-minting, downstream execution, and the sign-in challenge case, leaving little an agent needs to infer.

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

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

Schema coverage is 100%, so both parameters are already documented in the schema. The description reinforces that the email must come explicitly from the user and is used for recovery, but it adds little about client_name beyond what the schema already says.

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

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

The description states a specific action and resource: it mints a free DC Hub key and returns it with connect_url. It also distinguishes this from keyless access, recover_my_key, and execute_plan, so an agent can identify the tool 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.

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

It gives explicit when-to-use conditions: when the user wants more data than keyless allows or asks for a key. It also names alternatives and exclusions: recover_my_key for lost keys, don't re-mint, prefer sign-in when a 401 challenge appears, and use execute_plan for multi-step questions.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description layers on substantial extra context: the physics model (km x 4.9 µs/km x 2), route_factor 1.4 stamped as inference, confidence_v provenance tiers, dark-fiber screening, and a fail-closed candidate_contract for expired/unknown ids. This is genuinely value-adding behavior disclosure.

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

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

Front-loads the trigger and outcome before diving into the per-pair metrics, and uses a labeled 'CANDIDATE CONTRACT' block for the contract rules. It is dense and slightly repetitive in restating the candidate_id provenance, but nearly every clause carries operational information.

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

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

For a 4-param, read-only analytical tool with an output schema and full annotation coverage, the description supplies everything an agent needs: trigger, sequencing, the physics/confidence semantics, and the candidate-id contract. Nothing material is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: candidate_ids resolve to FROZEN mint coordinates (zero transposition), cand_ tokens may be mixed into the sites string, and expired/unknown ids are dropped and declared. It also frames max_latency_us against a realistic use case (sync replication 1000-2000 µs).

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

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

States a specific verb+resource ('cluster sites by latency') plus the scope (2-8 sites) and the output ('viable low-latency clusters and pairwise RTT floors'). It distinguishes itself from routing work ('deterministic pruning BEFORE detailed routing') and cross-references compare_sites and get_refined_queue, so an agent can place it relative to siblings.

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

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

Gives an explicit trigger ('when the user asks which data center sites can form a low-latency cluster') and a clear ordering rule ('BEFORE any routing work'). It stops short of naming the specific alternative tool to use for the downstream routing step, so it's clear context rather than full when/when-not routing.

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

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

Annotations already declare read-only, idempotent, non-destructive, open-world behavior, so the safety profile is covered. The description adds important behavior beyond that: non-US and non-ISO rows have null DCPI/queue fields because they are not tracked rather than zero, and it distinguishes avg_time_to_power_months from avg_queue_wait_months as different measurements.

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

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

The use case is front-loaded, followed by examples, parameter constraints, return shape, and a crucial measurement caveat. Despite its density, every sentence contributes operational detail needed to select and invoke the tool correctly.

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

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

Given the tool's complexity, the description is complete enough for correct selection and invocation. It explains when to use it, the accepted input domain, the comparison output fields, null-field semantics, and the key measurement distinction, while the output schema covers the return structure.

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

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

Schema coverage is 100%, so the parameter is already documented. The description still adds meaningful constraints and enumerations: comma-separated list, two-to-four maximum, accepted US ISOs, TVA, BPA, utility BAs, and non-US grid identifiers. It does not add much syntax nuance beyond that, so it is strong but not exceptional.

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

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

States a specific verb and resource: compare two to four power grids side by side, including fuel mix, demand, renewable/gas share, and queue metrics. It explicitly distinguishes itself from making N sequential get_grid_intelligence calls, so an agent can route between this and the single-grid path.

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

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

Gives a clear trigger: when the user asks to compare two to four grids side by side. It names the alternative it replaces, get_grid_intelligence for sequential single-grid calls, and supplies concrete examples including mixed US/non-US comparisons.

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

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

Annotations only cover safety (readOnly/idempotent/non-destructive), yet the description discloses the entire tiered output contract — keyless returns only verdict and power bands, a free key adds names/counts without figures, and scores plus the winner require a paid plan. It also frames the payment path (mpp_pay returning a signed challenge rather than moving money), which is far beyond what structured fields convey.

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

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

Four dense sentences that lead with the trigger and the input format, then the return contract, then the example. Every sentence carries information, though the tier explanation is compressed enough to need a careful read.

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

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

Covers trigger, input format, capacity hint, tier-gated return content and payment behavior; with an output schema present it need not enumerate return fields. An agent has everything needed to select and invoke this correctly.

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

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

Schema description coverage is 100%, so locations format, {lat,lon} alternatives, capacity_mw range and the MPP payment parameters are already fully documented. The description restates the locations string format and 'optional capacity_mw' but adds no syntax or semantics the schema lacks, so it sits at the baseline.

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

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

States a specific verb and resource ('compare' 2-4 candidate sites, returns side-by-side analyze_site scores plus a winner) and gives the exact user situation that triggers it. An agent can distinguish this from analyze_site (single site) and rank_sites (ranking) 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.

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

Explicit trigger condition: the user has 2-4 candidates and asks which is best, plus a concrete example ('Phoenix vs Ashburn for 50 MW?'). It implies but never names the alternative single-site tool or when to use rank_sites instead, so routing is clear but not fully exclusive.

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

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

Annotations already declare read-only, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds genuinely non-obvious behavior: the per-deal autopsy read is gated behind a paid key, and the default response is deliberately trimmed (comparables count only) to keep it cheap. No rate limits or failure modes, but the paywall and progressive-disclosure cost model are real added context.

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

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

Front-loaded with the trigger condition, which is good. But it is dense and repetitive: the 'what is the real play' framing appears twice, and there are many embedded quoted phrases and dashes that add length without adding information.

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

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

An output schema exists, so return values need not be spelled out, and the description nonetheless sketches the shape (deal fields + DCPI verdict + time-to-power). Trigger conditions, the paid-key caveat, and the disclosure levels are all present, leaving only minor gaps such as ranking/ordering of the returned deals.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes beyond the schema by giving escalation guidance for comparables ('escalate only for deals you're drilling into') and by confirming the verdict text is always included regardless of the comparables setting, which resolves a plausible ambiguity.

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

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

States a concrete verb and resource: returns recent data-center deals (buyer, seller, value, market) joined to each market's DCPI verdict and time-to-power. An agent can distinguish it from the broader deal listers. It never names a sibling it is not (e.g. hyperscaler_deals, list_transactions), so the differentiation is inferred rather than stated.

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

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

Explicit when-to-use: 'Use this when the user asks what a data-center deal means for power' plus two representative user questions and a worked call example (deal_autopsy limit=15). Clear context, but no when-not-to-use and no named alternative for plain deal listing.

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

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

Annotations already flag destructiveHint=true and idempotentHint=false, but the description adds what the annotations cannot: deliveries stop, the watch is unrecoverable, cap_ ids instead retire a Capacity Source requirement and stop its alert emails, and a key/OAuth credential is required. This is exactly the extra operational context the annotation layer lacks.

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

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

Front-loads the trigger condition, then consequences, then the cap_ edge case, then the credential requirement, then the anti-pattern. Every sentence carries distinct, decision-relevant information with no filler.

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

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

With an output schema present, return values need no explanation. The description covers auth, destructiveness, irreversibility, the cap_ variant, and id sourcing, leaving nothing an agent needs before calling it.

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

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

Schema coverage is 100%, so the baseline is 3; the description goes further by explaining the cap_ prefix semantics that branch behavior and by reinforcing the id provenance. It does not add format/syntax detail beyond that, so not a 5.

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

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

States a specific verb (retire/delete) and resource (standing intent / webhook watch), and immediately distinguishes it from list_standing_intents and register_standing_intent by naming them. The 'Answers "stop watching this"' phrasing pins the user intent without ambiguity.

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

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

Explicit when (user wants to retire a watch), explicit when-not ('Do NOT use to pause temporarily; there is no pause'), and names the source of the id (list_standing_intents or the register response). Alternatives and the absence of a pause path are spelled out.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds genuine beyond-annotation context: the returned _entity shape, a front_door block containing execute_plan and get_changes, and the caveat that this is a curated navigation layer rather than the canonical catalog. Return-value detail is partly redundant with the existing output schema, keeping this at 4 rather than 5.

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

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

Front-loaded with the when-to-use trigger and then the return shape, which is the right order. It runs long and restates the tools/list-is-canonical point twice (once as 'navigation layer, not the exhaustive catalog' and again as 'bind it from tools/list, not from here'), a minor redundancy that a single mention would cover.

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

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

For a discovery/routing tool with an output schema present, the description supplies everything an agent needs: when to invoke it, what it returns at a structural level, how to proceed afterward (call the chosen tool; its full schema is in tools/list), and the caveat about binding capability maps. Nothing material is missing.

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

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

Schema description coverage is 100% for the single optional query parameter, so the schema already carries the semantics. The description's example keywords ('site selection', 'grid queue', 'fiber', 'deals', 'market') largely mirror the schema's own examples, adding little new meaning; baseline 3 is appropriate.

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

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

States a specific verb and resource ('lists tools by family') and frames the tool's role as a 'navigation layer' rather than a data tool. It explicitly distinguishes itself from the canonical catalog (tools/list) and from execution tools (execute_plan), so an agent can place it without opening a schema.

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

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

Opens with the triggering condition ('Use this when you are unsure which ... tool fits') and closes with an explicit when-not and alternative: it is not the exhaustive catalog, tools/list stays canonical, and capability maps should be bound from tools/list rather than here. Both routing and exclusion are spelled out.

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

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

Beyond the readOnly/idempotent/openWorld annotations, the description discloses the execution model in real detail: deterministic no-LLM routing, wave-by-wave sequencing with parallelism where the graph allows, capped per-finalist fan-out, hand-off resolution for metro_slug/candidate_id/ISO, and the exact `_entity=plan_execution` envelope shape including totals, minted, and replay. This tells an agent precisely what side effects to expect (none destructive) and what the response will contain, which is substantial value on top of annotations.

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

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

It is front-loaded with the 'Use this when...' trigger and the critical 'One call plans AND answers' claim, so structure is sound. However, the opening topic enumeration runs to fifteen comma-separated domains and much of the envelope detail duplicates the output schema, making the description longer than the decision-relevant content requires.

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

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

For an 11-parameter orchestrator with an output schema already present, this description covers every dimension an agent needs: when to pick it, what it does internally, how parameters merge, and what the envelope contains. Even the normally implicit concern of fan-out and step capping is addressed via max_steps/max_fanout defaults.

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

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

Schema description coverage is 100%, so all 11 parameters are already documented in structured form, giving a baseline of 3. The description adds only 'Pass the user's question as `intent`' and reinforces that user-supplied values beat minted ones, both of which are already stated in the schema. The interesting dynamics it does explain (angle-bracket hand-off resolution and minting between steps) concern internal step wiring rather than the caller-facing parameters.

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

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

The first sentence names a specific verb+resource ('one-call planner over megawatts and power density, grid headroom...') and explicitly frames the tool as multi-topic orchestration that 'plans AND answers'. It differentiates itself from the single-purpose siblings by enumerating the topic domains it chains together, and it names plan_query as the underlying planner. It stops short of a crisp one-line 'this executes a multi-tool plan' statement, burying the identity inside a 15-item topic list.

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

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

'Use this when a data center question spans several topics' and 'Recommended entry for a question that spans more than one of those' gives a clear selection rule that distinguishes it from the dozen granular get_* tools. The relationship to plan_query is hinted at ('the same planner plan_query exposes'), implying plan_query plans while this executes. It lacks an explicit exclusion clause such as 'for a single-metric lookup use get_grid_data instead'.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds context annotations cannot: the paid-plan gating and the fact that the whole file body is returned as text, which matters for how the agent should relay results.

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

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

Front-loaded with the trigger and alternatives, and every sentence serves routing or behavior. The 'Returns:' clause is mild redundancy given an output schema exists, but it is short and harmless.

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

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

For a single-parameter, non-destructive export tool with an output schema already defined, the description supplies trigger, alternatives, plan gating, and format guidance. Nothing needed 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.

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 slightly beyond by restating the default ('csv' default) and showing a format-specific invocation example ('export_dataset format=geojson'), which clarifies intent rather than duplicating fields.

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

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

States a specific verb+resource ('export their saved data center sites') plus the purpose (offline analysis, spreadsheet, ingestion) and output forms. It explicitly names the sibling tools it is not (list_saved_sites, save_site), so an agent can route 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.

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

Gives a concrete trigger ('when the user wants to export'), a worked example with the exact call, and explicit exclusions with named alternatives ('Do NOT use to list sites in-chat (use list_saved_sites) or to save a new one (use save_site)'). This is the full when/when-not/alternative pattern.

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

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

Annotations already declare the safety profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint=false), so the burden is lighter. The description contributes domain context beyond that — the record is a citable public summary covering name/operator/location/status/market — which helps the agent understand the nature of the data returned.

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

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

Front-loaded with the triggering condition and then the guarantee/alternative, which is the right ordering. Slightly redundant to enumerate the return shape when an output schema exists, but overall tight and purposeful.

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

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

For a single-parameter read tool with full schema coverage, an output schema, and safety annotations, this covers the one open question — why choose `fetch` over `get_facility` — and answers it. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100% and the single `id` param already carries an example (equinix-dc1-ashburn), so the schema does the heavy lifting. The description only reinforces the provenance of the id ("from `search`"), adding no format or syntax detail beyond the schema — baseline 3 is appropriate.

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

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

States a specific action (fetch a data-center facility record by id) and explicitly frames it as the companion to `search`. It names the sibling it is not (get_facility) and what that sibling returns, so an agent can distinguish the two 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.

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

Gives an explicit precondition ("when you have an id from `search`") plus a clear alternative for the adjacent need ("For full structured specs... use get_facility or open the url"). When-to-use and when-to-use-something-else are both stated.

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

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

Annotations already declare it as read-only, idempotent, and non-destructive. The description adds useful behavior beyond that: it discovers candidates from one seed and returns ranked alternatives with similarity_score, match_reasons, and key_differences.

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

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

The description is front-loaded with the use case and example, and the final sentence efficiently routes to alternatives. It is slightly weakened by a parameter sentence containing inaccurate extras and by return details that partly duplicate the output schema.

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

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

Purpose and sibling routing are complete, and annotations plus the output schema cover safety and return shape. However, the description's incorrect parameter guidance means it is not fully reliable as a standalone invocation guide.

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

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

The schema has 100% description coverage and explicitly says there is no `name` param, but the description incorrectly says 'facility_id or name' and mentions an optional `capacity_mw` that is not in the schema. It also omits the actual `match_on` and `exclude_operator` parameters, creating active confusion despite the schema being correct.

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

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

States a specific verb and resource: finding data center facilities similar to a seed facility. The example and sibling exclusions make it clearly distinct from score_facility, analyze_site, and compare_sites.

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

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

Explicitly says when to use it, gives a concrete example, and names when not to use it with alternative tools. It also clarifies that this discovers candidates from a single seed rather than comparing a known short-list.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description goes well beyond them: it discloses spatial de-duplication by cluster_km (why a metro yields distinct areas instead of 40 near-identical rows), that gas/fiber filters apply ONLY when the layer answers, state-grain (not jurisdiction-grain) moratorium context, and a next_calls handoff.

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

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

Purpose is front-loaded in the first clause and the content is dense with distinct facts, but the "THE INVERSE QUERY" paragraph is rhetorically padded ("where should I even be looking?") and the closing examples partly duplicate the schema's own examples.

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

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

For a 13-param open-world search tool with an output schema present, the description covers everything an agent needs: trigger condition, alternative routing, output shape (search areas with distances and coverage caveats), and example invocations. Return-value detail is appropriately left to the output schema.

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

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

Schema coverage is 100% and the per-parameter docs are already detailed, so the baseline is 3. The description adds value by showing worked parameter combinations ("state=OH min_voltage_kv=230 max_gas_km=8" and "lat/lon radius_km=60 min_voltage_kv=500"), illustrating how the filters compose rather than restating definitions.

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

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

States a specific verb+resource (find candidate data-center search areas) and pins down the mechanism (HIFLD substation anchors at/above min_voltage_kv, gas/fiber distances, cluster de-duplication). It explicitly contrasts itself with analyze_site, get_composite_site_score, rank_sites, find_alternatives and execute_plan, so an agent can disambiguate 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.

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

"Use this when the user has no data center site yet and wants candidate search areas" gives a clear entry condition, and it names the routing rule for multi-part siting questions (execute_plan). It frames the tool as the inverse of every coordinate-based sibling, effectively stating when NOT to use it.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds real operational context: a branded 5-page PDF, a link that needs no login, and a ~7-day validity window that the agent must relay to its human. It stops short of describing error behavior or what happens when a coordinate falls outside coverage.

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

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

Front-loaded with the trigger and the sibling exclusion, then the example, then the param recap — a sensible order with no wasted preamble. The trailing 'Params:' block largely duplicates a fully-covered schema and could be trimmed.

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

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

Output schema exists, yet the description still usefully sketches the return shape and calls out pdf_report_url as the actionable artifact, which is what the agent must hand back. Gaps: use_case is never mentioned, and the description insists lat/lon are 'required' while the schema declares zero required parameters — a mismatch that could cause the agent to demand a coordinate the schema treats as optional.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns one more by pairing each core parameter with a realistic value in the worked example (lat=37.694 lon=-88.65 capacity_mw=150) and reinforcing defaults for prepared_by and latency_target. It omits use_case entirely and repeats range/default facts the schema already states, so it stays below a 5.

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

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

States a specific verb+resource (generate a shareable Site Analysis PDF) scoped to exactly one lat/lon parcel, and explicitly frames it as 'the polished client deliverable, not just a score.' It names the sibling it is not (analyze_site) so the 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.

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

Gives an explicit trigger ('use this when the user wants a shareable ... PDF for ONE lat/lon'), a concrete worked example with realistic argument values, and a stated when-not ('For just the numeric suitability score (no PDF), use analyze_site instead'). Nothing about selection 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.

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

Annotations only declare readOnly/idempotent/openWorld=false; the description goes well beyond them by disclosing that the roster is backend-owned and mutable, that clients must read platforms[] and per-row status rather than any enumerated list, and that mcp_active/mcp_ready are curated editorial claims with as_of null rather than live connection counts. That is exactly the kind of caveat an agent needs to avoid misreporting results.

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

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

The usage condition and the when-not are front-loaded, which is good, but the passage is long for a zero-argument read tool. The 'an enumeration here goes stale ... exactly how a client named here stopped appearing in the roster' anecdote and the 'Try: get_agent_registry' filler consume space without adding decision-relevant information.

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

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

With an output schema present, the description need not explain return values, and annotations already carry the safety profile; the description nonetheless supplies the interpretive context (editorial statuses, as_of null, backend-owned roster) that keeps a caller from over-claiming. Nothing needed to call it correctly is missing.

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

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

The tool takes zero parameters, so the baseline is 4; there is no parameter surface for the description to illuminate. It does describe the shape of the relevant response fields (platforms[], status), but that belongs to the output schema rather than to parameter semantics.

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

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

The description names a specific resource (the DC Hub AI platform/agent-framework registry) and states what it returns: platforms with recommended tools and an authentication tier. It also explicitly disclaims what it is ('a curated ecosystem/capability index, NOT live per-caller call/citation telemetry'), which distinguishes it from telemetry-adjacent siblings.

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

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

It gives an explicit triggering condition ('Use this when the user asks which AI platforms and agent frameworks integrate DC Hub'), an explicit exclusion ('Do NOT use for platform uptime or feed health'), and names the alternative tool to use instead (get_backup_status). 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.

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds genuinely useful behavioral context beyond them: the semantic warning that 'unknown' means NOT measured, and that scope is exactly /api/health/data-freshness and nothing wider. It stops short of the full 5 only because there is no note on refresh cadence of the health check itself.

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

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

The use case and row/rollup structure are front-loaded, which is good, but the text is bloated: the stray 'Try: get_backup_status' fragment is wasted, and the freshness question is effectively restated by both the 'are any of your sources stale' example and the '/api/health/data-freshness... nothing wider' scope sentence. Several sentences could be merged without loss.

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

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

An output schema exists, so return-value explanation is not strictly required, yet the description still previews row fields and the rollup. For a zero-parameter read tool with full annotation coverage, an agent has everything needed to call it and interpret the result.

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

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

The tool takes zero parameters, so the schema has nothing to document and the baseline is 4. There is no parameter syntax the description could meaningfully add, and it correctly avoids inventing any.

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

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

States a specific verb and resource ('how current DC Hub's data center and power data feeds are'), enumerates the exact feeds returned, and describes both the per-row fields (health, record_count, refresh_interval, scheduler) and the summary rollup shape. It is unmistakably distinct from sibling data tools like get_changes.

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

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

Gives an explicit trigger ('Use this when the user asks how current... feeds are'), a sample user question ('are any of your sources stale right now'), and a named exclusion with the alternative ('Do NOT use for the freshness of one dataset (use get_changes)'). Nothing about when/when-not 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.

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

Annotations already cover the read-only, idempotent, non-destructive, closed-world profile. The description adds meaningful context beyond that: the portfolio block only appears for 'keyed callers with saved sites', and the generated_at caching pattern for successive calls. Auth-conditional and caching behavior are disclosed.

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

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

Front-loaded with 'Use this when...' and information-dense throughout, with a concrete example call. Slightly long, and the trailing 'Answers ...' sentence partially restates the opening, but no sentence is pure filler.

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

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

Output schema exists, so return values need not be explained, yet the description still characterizes the response blocks richly. Between the triggering contexts, parameter shorthand, caching pattern, and keyed-caller behavior, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by restating the since shorthand/default and, notably, introducing the cache-and-replay pattern for generated_at, which is not obvious from the schema alone and clarifies how 'since' should be chained across calls.

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

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

States a specific verb+resource and enumerates exactly what it returns (DCPI 7-day market movers, newly discovered facilities, new M&A deals + news, plus a per-saved-site portfolio block). The 'changes since' framing is distinctive, but no sibling tool is named to explicitly contrast against the many adjacent tools (get_news, list_transactions, get_market_context).

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

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

Gives clear triggering contexts: 'when the user asks what changed... since a date', 'what changed since I last looked', 'anything new this week'. This tells the agent when to reach for it, but it offers no explicit alternatives or when-not guidance against the numerous sibling intelligence tools.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered; the description adds real behavioral context beyond that: radius_km snapping to the nearest NOAA station with unavailable_exceeds_radius beyond it, US-only seismic coverage, and a strict no-estimation policy with missing data declared unavailable. It stops short of noting rate limits or latency.

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

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

Front-loaded with the use case and alternatives, and most sentences carry weight. The full return-shape enumeration is largely redundant given a dedicated output schema exists, adding length without adding routing value.

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

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

Complete for a six-parameter lookup with annotations and an output schema: it covers source grounding (USGS ASCE 7, NOAA/ACIS), scope limits (US seismic, station radius), failure modes, and sibling routing. An agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so the schema already documents all parameters (baseline 3). The description adds meaning beyond the schema by explaining the operational consequence of radius_km (default 25, station snapping, failure when exceeded) and confirming the lat/lon pair drives the whole lookup, which goes past the flat field definitions.

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

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

States a specific verb+resource (retrieve seismic/climate design inputs for a lat/lon site) and names the exact dimensions it feeds (structural bracing cost, cooling design). It explicitly distinguishes itself from get_disaster_risk and get_composite_site_score, so an agent can route 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.

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

Opens with an explicit trigger condition ('when the user asks about seismic or climate design inputs') and names both alternatives with the condition that selects them (natural-hazard ratings → get_disaster_risk; one blended verdict → get_composite_site_score). 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.

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

Annotations only declare the safe-read profile (readOnly/idempotent/non-destructive/openWorld=false); the description adds genuinely unavailable context: no imputation of missing factors, live provenance per factor (FEMA NRI, WRI Aqueduct 4.0), the rule that water is 'unavailable' rather than faked outside basin coverage, and that market/DCPI is v1-unavailable. This is exactly the operational nuance annotations cannot express.

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

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

The purpose and coverage-map distinction are front-loaded, and the alternatives are consolidated at the end. It is dense but long — the explicit return-shape enumeration duplicates an output schema that already exists, which is the one stretch that doesn't earn its place.

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

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

For a scoring tool with an output schema present, the description still covers everything an agent needs: verdict scale (0-100, BUILD/CAUTION/AVOID), confidence semantics, coverage values (validated|unavailable), and the no-imputation contract that determines how results should be interpreted.

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

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

Schema description coverage is 100%, so the lat/lon/state/alias semantics are already documented, making 3 the baseline. The description adds a concrete example call (lat=33.45 lon=-112.07 state=AZ) but never mentions the lng/latitude/longitude aliases or that state is optional-but-helpful, so it adds little beyond the schema.

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

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

The opening sentence states a specific verb (score) and resource (composite site suitability for a lat/lon) plus the distinguishing artifact: an explicit per-factor coverage map. It explicitly contrasts itself with analyze_site ('full raw data dump') and with the scoring scope ('scores ONLY over VALIDATED factors'), so an agent can separate it from siblings 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.

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

It states the triggering condition ('when the user wants one 0-100 verdict WITH a coverage map') and then routes three alternatives by scenario: analyze_site for full data, compare_sites for 2-4 sites, rank_markets for whole-market ranking. Exclusions and substitutes are both explicit.

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

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

Annotations only declare readOnly/idempotent/openWorld=false; the description adds substantial behavior beyond that: the exact fallback when free text does not match (generic blurb with matched_category=null and context_understood=false), the is_generic_answer/answer_note/next_tools fields on non-matching input, and the fact that it never computes a siting answer. This is rich disclosure the annotations cannot carry.

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

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

The trigger and the exclusions are front-loaded, which is good, but the four categories are listed twice and the return-shape enumeration duplicates the output schema, adding bulk without new information. Information-dense but not tightly edited.

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

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

For a single-optional-param tool with an output schema, the description covers everything needed: trigger, valid inputs, fallback semantics, and routing to the correct alternative tools. The repetition of return fields is redundant with the output schema but does not leave a gap.

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

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

Schema coverage is 100%, but the schema's own description is misleading — it advertises free text like "100MW AI training campus in Texas" while the tool actually requires one of four literal categories. The description corrects this and enumerates the four valid values (the schema declares no enum), which is essential meaning added beyond the schema. It falls short of 5 only because the underlying schema remains contradictory and could still mislead.

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

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

The description states a specific verb+resource: it returns a DC Hub blurb in one of four named categories plus the live top-ranked market pocket. It explicitly distinguishes itself from analyze_site, rank_markets, and site_selection_canvas, so an agent can tell exactly what this tool is not.

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

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

It gives an explicit trigger ("Use this when the user asks what DC Hub is") and an explicit do-not-use list, each paired with the correct alternative (single lat/lon -> analyze_site, one-criterion ranking -> rank_markets, computed shortlist -> site_selection_canvas). 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.

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so the bar is lower, and the description still adds real behavior: live query rather than estimate, explicit out-of-coverage fallback (coverage=unavailable), county-level rather than parcel resolution, and a caveats field. It does not mention auth/API-key requirements or rate limits, which is the only gap.

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

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

Roughly 100 words, front-loaded with the trigger and source, then example, then return shape, then sibling routing. Every clause carries information; nothing is restated from the title or padded.

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

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

For a lookup tool with an output schema and full annotation coverage, the description supplies everything needed to call it correctly: source, resolution, coverage semantics, fallback behavior, and the alternatives. Return-field enumeration is redundant against the output schema but harmless and aids scanning.

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

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

Schema description coverage is 100% and the schema already documents ranges and the alias names (latitude/longitude/lng), so the baseline is 3. The description adds value by pinning the constraint to US coordinates and supplying a concrete invocation example (lat=33.45 lon=-112.07), but it does not explain how the aliases interact if multiple are passed.

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

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

Specific verb+resource with explicit scope: natural-hazard risk for a US data-center site, grounded in the FEMA National Risk Index. It enumerates the hazard classes covered (flood, wildfire, hurricane, earthquake, heat, drought, tornado) and is trivially distinguishable from get_water_risk and get_composite_site_score.

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

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

Opens with an explicit trigger ('Use this when the user asks about natural-hazard risk for a data center site'), then routes away to two named alternatives with their own conditions (chronic water stress -> get_water_risk; blended site verdict -> get_composite_site_score). No inference required.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description usefully adds provenance and freshness (EIA retail, monthly, ~3 months lag, latest_period field names the month), the national-benchmark nature of Henry Hub gas, and auth behavior (anonymous/free-key seats return null with gated: true; email-bound key unlocks). These are real additions beyond the annotations. However, it omits the payment flow entirely (mpp_pay/mpp_credential appear only in the schema), so the description does not fully disclose the per-call charge behavior a caller must understand.

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

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

Content is front-loaded with the when-to-use trigger, which is the right priority, and most sentences carry information. But it is a single dense paragraph of roughly 250 words, and a large block enumerates return fields (retail_rates, avg_rate_kwh, industrial_rate_kwh, natural_gas_usd_mmbtu) that the existing output schema already documents — that portion does not fully earn its place.

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

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

For a multi-source, gated, stale-by-design data tool, the description covers what is returned, units (cents vs dollars per kWh), freshness, the national-vs-regional distinction for gas, failure mode at unauthenticated seats, and explicit scope limits (no wholesale/LMP, no grid status). With an output schema present, return-value shape needn't be explained further; nothing an agent needs in order to call this correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds genuine meaning: it enumerates the ISO values, gives a state example, and establishes that iso/state select exactly one scope (one ISO footprint as the average of its states, one state, or the US). It also clarifies that data_type 'is accepted but does not change the response', which resolves ambiguity in the schema's 'Optional price type focus' wording — though that is arguably a schema/description mismatch rather than pure enrichment.

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

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

States a specific verb+resource (retrieves electricity/natural gas prices) with explicit scope (US ISO footprint, single state, or US), and actively distinguishes itself from siblings by naming execute_plan and by disclaiming wholesale/LMP and grid-status data. An agent can identify it 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.

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

Gives concrete trigger phrasings ('what does power cost in ERCOT?', 'retail rate in Virginia?') plus an explicit exclusion ('price alone does not rank sites ... execute_plan weighs both'), and states the alternative's selection condition. It also flags the gated-seat case so the agent knows when results will be null.

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

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

Annotations already cover the read-only/idempotent/non-destructive profile, and the description adds traits beyond them: single-record scope ("Returns ONE facility in full"), a 404 not-found recovery loop, and the gating behavior ("Gated: give human_url to your human") which the agent could not learn from the schema. This is exactly the kind of operational context annotations cannot express.

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

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

The routing constraint and single-vs-many distinction are front-loaded in useful order, and every sentence carries operational content. The long field enumeration is dense but justified by the 'tell me everything about this facility' use case, though it makes the opener heavier than strictly needed.

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

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

For a single-entity lookup with six optional/aliased params, full schema coverage, and a declared output schema, the description covers scope, prerequisites, failure handling, and gating. There is no material gap an agent would hit on invocation.

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

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

Schema coverage is 100% and the schema already explains facility_id/slug/name aliases, so the baseline is 3. The description earns a point above baseline by supplying concrete call syntax examples (equinix-dc1-ashburn, the long digital-realty slug) and reinforcing that identifiers must come from search_facilities. The two include_* toggles are left entirely to the schema.

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

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

The description opens with a specific verb+resource (fetch one data center facility) and enumerates exactly which fields come back, so an agent knows the payload shape before calling. It explicitly contrasts with the sibling search_facilities for multi-result queries, making it unambiguous.

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

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

It states when to use it ("when the user asks about one data center facility"), when not to ("do NOT use to search or list many facilities (use search_facilities)"), plus the prerequisite ("Needs a slug or id from search_facilities") and the recovery path for a 404. 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.

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds substantive behavioral context beyond them: only DCPI market-health has a temporal series, the hazard dimensions are declared static and never fabricated into week-over-week deltas, and missing snapshot history returns coverage:unavailable. This is exactly the integrity/edge-case disclosure annotations cannot carry.

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

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

Front-loaded with the usage trigger and return shape, and the integrity caveat earns its length. It is dense and somewhat long, with the parameter list and return signature partly redundant against the schema, but no sentence is pure filler.

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

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

For a tool with 3 optional params, an output schema, and subtle coverage semantics, the description covers trigger, scope, integrity behavior, return shape, and sibling alternatives. 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.

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 the OR/mutual-exclusion relationship between facility_id and market and restates the default window (7d). It largely mirrors the schema descriptions, so it is a modest rather than substantial gain.

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

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

States a specific verb+resource+scope: how a facility's (or market's) power risk changed recently, framed by the user question it answers. It explicitly distinguishes itself from point-in-time siblings (get_composite_site_score / get_disaster_risk / get_climate_intel), so an agent can route correctly without opening a schema.

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

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

Gives an explicit trigger ("has this site gotten riskier lately?") and names the alternative tools plus the exact condition (current point-in-time risk vs change) that selects them. When-to-use and when-not-to-use are both covered.

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

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

Annotations already declare read/idempotent/non-destructive/closed-world, but the description adds substantial behavior annotations don't carry: free callers receive only a sample, the full set requires a paid key, the call is gated, and the agent must pass human_url to its human. That paywall and human-approval context is exactly the extra disclosure this dimension rewards.

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

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

Front-loads the when-to-use trigger and the return shape, with a concrete example query. Slight redundancy: filtering by carrier/market/route_type is stated twice ('Filter by carrier, route_type, market' early, then 'Filter by market ... or carrier' at the end).

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

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

Output schema exists so return fields needn't be spelled out, yet the description still summarizes GeoJSON contents; gating, filters, and human-payment flow are all covered. The only gap is not situating this tool against the adjacent get_metro_fiber sibling, which the sibling list suggests could be confused with it.

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

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

Schema description coverage is 100%, so the schema already documents all six params including the MPP payment fields; baseline is therefore 3. The description adds only marginal value, though it does usefully cross-reference that 'market' is a slug from rank_markets and notes route_type=longhaul pairing.

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

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

States a specific verb+resource (fiber routes/carriers/connectivity) and explicitly enumerates the route classes (long-haul, metro, dark, IX) it returns. It distinguishes itself from the nearest sibling by routing single-building queries to get_facility, so an agent can tell it apart 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.

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

Gives a clear when-to-use trigger ('when the user asks about fiber routes, carriers or connectivity for a market'), an example query, and one explicit alternative (get_facility for a single building). It does not, however, differentiate from plausibly overlapping siblings such as get_metro_fiber or get_fiber_readiness, leaving some ambiguity.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds substantial context beyond them: the data provenance (PeeringDB), null-scoring semantics tied to carrier_data_coverage, and the critical 'unknown is NOT bad' distinction between 'no carrier serves this point' and 'PeeringDB does not describe this region'.

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

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

Front-loads the purpose well and the example is helpful, but the full enumeration of return fields duplicates the output schema and adds length. Mostly efficient, with one redundant block.

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

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

For a tool with a full output schema, the description is more than complete; the return-value listing is redundant but not harmful, and the coverage/unknown nuance is exactly the kind of context an agent needs. Slightly over-complete rather than under.

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

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

Schema description coverage is 100%, so the schema already documents every parameter including the aliases (lng/latitude/longitude) and radius ranges. The description restates the same ranges and defaults without adding new meaning, so the baseline 3 applies.

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

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

States a precise verb+resource+scope: 'whether one data center site (lat/lon) is fiber-ready' with the specific sub-signals (near-net distance, carrier count, single-carrier risk). This scoping to a single site distinguishes it from sibling tools like get_metro_fiber and get_fiber_intel without the agent needing to open schemas.

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

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

'Use this when the user asks whether one data center site is fiber-ready' gives clear triggering context and a concrete example query. It implicitly distinguishes the single-site scope from metro/sibling tools but never explicitly names an alternative or states when NOT to use it, so it falls 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.

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

Annotations already declare readOnly/idempotent/non-destructive/open-world, so safety is covered. The description goes further with behavioral caveats: each layer carries its own source label, gas_to_grid_status carries the reason if the backend switch is off, and — most valuably — the warning that $/MWh values published before 2026-09-27 were computed differently and can differ up to 5.5x. That is real disclosure beyond the structured fields, despite awkward wording.

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

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

The description is front-loaded with the core purpose, which is good, but it contains an obviously truncated fragment ('AZ, GA, FL), never a substitute price; if the backend switch is ever turned off again') and interleaves caps-lock warnings with unrelated notes. Multiple sentences do not parse cleanly, which harms an agent's ability to extract rules reliably.

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

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

An output schema exists, so return-value explanation is not required. The description supplies the trigger, the scope of returned layers, the exclusion and alternative, and the critical cross-date comparability caveat. Given the tool's complexity and the presence of an output schema, this is largely complete — the damaged fragments are the main residual gap.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema (market slug with examples, optional heat_rate_btu_per_kwh with an example). The description repeats the market slug guidance without adding format or constraint detail, and never mentions the heat-rate parameter. Baseline 3 is appropriate when the schema carries the load.

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

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

The first sentence names a specific resource (behind-the-meter gas power economics) and enumerates the three layers returned — Henry Hub spot, regional basis differential, and the delivered industrial + electric gas tariff in $/MMBtu. It also distinguishes itself from the electricity-mix sibling by routing that case to get_grid_data. The purpose is clear, though a garbled mid-sentence fragment ('AZ, GA, FL), never a substitute price') muddies the edges.

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

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

It states an explicit trigger ('Use this when the user asks what behind-the-meter gas power costs in a US data-center market') and an explicit exclusion ('Do NOT use for the electricity grid fuel mix (use get_grid_data)'), naming the alternative. The temporal-comparison warning and the 'do not derive a $/MWh yourself' instruction add further usage constraints. Only the corrupted fragment keeps this from being fully clean guidance.

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

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

Annotations already declare a safe, idempotent read, so the bar is low, yet the description adds substantial behavioral context: the index-versioning hazard (differing DCGI figures before/after 2026-08-08), where the full methodology record lives, and the UNSCORED-not-low-score semantics. It also explains that gas_price_series identifies which EIA series priced each state.

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

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

Front-loads the core purpose before the caveats, and most sentences (UNSCORED semantics, version warning, sibling routing) earn their place. It is somewhat packed with dated incident detail (same-day withdrawal, 2026-09-27 republish) that could be tightened, but it remains readable.

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

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

With an output schema present, return values need not be re-explained, and the description still covers the two things an agent must not get wrong: cross-version comparability and treating UNSCORED as absence. Alternatives and the methodology endpoint are also supplied.

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

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

Schema description coverage is 100%, so both parameters (limit, state) are already fully documented, which sets the baseline at 3. The description adds semantics around state output (verdict, gas_price_series) but nothing new about parameter syntax or constraints beyond the schema.

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

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

States a specific verb+resource+scope: 'which US states suit gas-fired data center power' scored per-state by the Data Center Gas Index (DCGI). It is clearly distinguishable from sibling gas tools, naming get_gas_intelligence (pipeline/operator/midstream) and get_gas_economics as the alternatives.

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

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

Gives an explicit trigger ('Use this when the user asks which US states suit gas-fired data center power') and explicit routing away from siblings ('Use get_gas_intelligence for pipeline, operator and parent-midstream data'), plus a reference to get_gas_economics. When-to-use and when-to-use-something-else are both covered.

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

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

Annotations cover the safety profile (readOnly, idempotent, non-destructive), and the description layers on substantial behavioral context beyond them: freshness cutoffs for DCGI and $/MWh, synthetic-labeled basis, nulls surfaced honestly rather than fabricated, and the caveat that gas_access is presence not firm capacity. This is exactly the extra detail annotations cannot carry.

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

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

Front-loads the use case and keeps sentences information-dense, but enumerates the full return object even though an output schema exists, which is partly redundant. Still well-ordered and free of filler.

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

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

For a high-complexity intelligence-fusion tool, it covers triggering, provenance/confidence, staleness rules, and honest-null behavior. With an output schema present it needn't explain returns, yet its extra caveats add rather than pad.

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

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

Schema coverage is 100%, so both region/state params are already documented, and the description largely repeats the state-code-or-name format. It does not add new syntax or constraints beyond the schema, so baseline 3 applies.

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

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

States a specific verb+resource (fuse gas economics into a per-state brief) and explicitly frames itself as 'the GAS analogue of get_grid_intelligence', letting an agent distinguish it from grid/energy siblings. The example user questions make the scope concrete.

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

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

Gives explicit trigger conditions and sample utterances ('is gas power cheaper than the grid in Texas?'), names the sibling it mirrors, and adds hard exclusions ('DO NOT quote a DCGI score cached before 2026-08-30'). When-to-use and when-not-to-use are both present.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds substantive context beyond that: dataset provenance (Global Integrated Power Tracker, 182,000+ geolocated units, 170+ countries), the exact definition of the pipeline set, and the return shape (summary of total MW by fuel plus largest units). It does not mention pagination or rate limits, keeping it short of a 5.

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

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

It is a long, dense paragraph, but it is front-loaded with the use case, then filters, then returns, then exclusions, then a try-example — every sentence contributes. Slightly overpacked, which keeps it from a 5.

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

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

With an output schema already present, the description need not detail return values, yet it still sketches them. Combined with scope, filter semantics, dataset coverage, and explicit sibling routing, an agent has everything needed 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.

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 meaningfully enriches it: fuel is 'comma-union', pipeline=true means ONLY the forward set (announced + pre-construction + construction), bbox is minLng,minLat,maxLng,maxLat, and country/status examples are given. This is more semantic detail than the schema fields carry.

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

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

The description names a specific verb+resource (retrieve global power plant asset inventory) and precisely scopes it: operating AND forward pipeline across ALL fuels, worldwide. It explicitly distinguishes itself from the US-focused siblings get_grid_intelligence, get_grid_scoreboard, and get_power_pipeline, so an agent can route 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.

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

It states when to use it ('user asks about power plants worldwide or in a non-US country'), when NOT to use it (US grid telemetry/headroom, US planned-generator feed), and names the specific alternative tool for each exclusion. Concrete example queries ('what power is being built in India') and a 'Try:' invocation remove ambiguity.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds real behavioral context beyond them: US ISOs/EIA regions return hourly fuel mix plus a 24h curve, other grids return each feed's newest reading per metric with its own timestamp, and the PJM capacity caveat (installed_capacity_mw_period is report-month net summer MW, not committed capacity). It stays silent on rate limits and on the payment flow for mpp_pay/mpp_credential, which is the only notable behavioral gap.

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

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

Front-loaded with the trigger sentence, then coverage, then return-shape, then exclusions — a sensible information order with no filler. It is long and partly run-on, and the exhaustive grid-code enumeration overlaps heavily with the iso parameter description, which costs it a point.

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

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

An output schema exists, yet the description still front-loads the one thing an agent must know before calling: which grid families return which kind of payload. Combined with the sibling routing and the capacity caveat, nothing needed to call this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns extra credit by tying the metric/period params to actual outputs ('fuel_mix, demand and the 24h curve' vs 'newest reading per metric') and by explaining what installed_capacity_mw_period means. It does not add anything about mpp_pay/mpp_credential, leaving that entirely to the schema.

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

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

States a specific verb and resource ('live electricity grid data (power demand, fuel mix) for one grid') and immediately bounds scope with an enumerated coverage list. It is clearly distinguishable from siblings like get_grid_intelligence and get_energy_prices without inspecting any schema.

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

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

Opens with an explicit trigger ('Use this when the user asks for live electricity grid data ... for one grid') and then names three concrete alternatives with the conditions that select them: get_grid_intelligence for power-availability/queue analysis, get_energy_prices for retail/gas pricing, get_grid_scoreboard for ranking many grids. That is the full when/when-not/alternative triad.

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

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

Annotations cover only the safety profile (read-only, idempotent), and the description adds what they cannot: response throttling by key tier, that keyless calls return a preview rather than the full brief, that non-US-ISO codes yield region_not_covered, and that avg_time_to_power_months and avg_queue_wait_months are distinct measurements that must not be conflated. That output-field disambiguation is unusually valuable and prevents a real reporting error.

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

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

Front-loaded correctly: trigger condition first, payload list second, caveats and example last. However, it is denser than needed — the seven-ISO enumeration appears twice and the free-preview behavior is stated three times ("keyless gets a trimmed preview", "With a free key...", "Free = preview"), which crowds a description that could be a third shorter.

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

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

With an output schema present, the description need not explain return values, and it correctly spends its budget on auth tiers, error behavior, and field-meaning traps instead. It is essentially complete for invocation. The missing piece is how the four alternative identifying parameters in the anyOf are resolved if more than one is supplied.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns an extra point by adding value constraints the schema does not enforce — iso must be one of the seven US ISOs, and other codes return region_not_covered rather than an error or a guess. It also restates the region/iso aliasing, which is redundant with the schema. It does not clarify precedence among the anyOf alternatives (region_id vs iso vs market), which is the one remaining semantic gap.

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

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

Names a specific domain (grid capacity, power availability, headroom, time-to-power) and enumerates the return payload — live demand, fuel mix, queue depth, DCPI scores, reserve margin. An agent knows exactly what class of question this answers. It stops short of naming a sibling, which matters here given near-neighbors like get_iso_context, get_grid_data, get_grid_scoreboard, and get_power_availability_timeline.

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

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

"Use this when the user asks about grid capacity, power availability, headroom or time-to-power..." is an explicit trigger condition, and the worked example ("PJM headroom for 200 MW?") anchors it. Auth-tier guidance (free key = a few briefs/day, keyless = trimmed preview, unlimited = paid) tells the agent whether it can call at all. No explicit when-not or named alternative is given, so it is 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.

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds the crucial non-obvious trait: freshness is not uniform, US mix data can be 18-24h stale while demand is 1-2h old, with per-row mix_period, mix_age_hours and freshness_basis. That staleness warning materially changes how an agent should interpret and present results, which is exactly the value structured fields cannot carry.

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

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

The trigger sentence is well front-loaded, but the middle is bloated: a long parenthetical on ENTSO-E zone counting that defensively explains its own measurement methodology ("measured per call rather than asserted here"). The "Try: get_grid_scoreboard" filler and the resource pointer add length without adding selection value.

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

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

With an output schema present, the description needn't explain return values, and it already covers coverage scope, ranking basis, and the freshness caveat critical to interpreting results. What's missing is minor: how many rows are returned, ordering guarantees, and whether rows with stale mixes are flagged versus filtered.

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

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

There are zero input parameters, so there is nothing to disambiguate and the baseline is a 4. The description's mention of counts_basis.eu_zones_live / eu_zones_configured refers to output fields rather than inputs, which is fine since an output schema exists.

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

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

States a precise verb and resource — a global scoreboard ranking grid operators side-by-side on latest published demand, fuel mix, and renewable share — and enumerates the covered regions in detail. The purpose is unmistakable, but it never names siblings such as compare_isos or get_global_power, so the agent must infer the boundary from scope alone.

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

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

"Use this when the user asks how power grids compare: demand, fuel mix or renewable share" plus the example questions gives a clear activation trigger tied to user intent. However, it gives no explicit when-not-to-use guidance and no named alternatives for narrower comparisons.

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

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

Annotations already declare this a read-only, idempotent, non-destructive, closed-world call, so the safety profile is covered. The description adds genuinely new behavioral context: the data provenance (utility's own GIS, 'filed distribution-level truth'), the coverage breadth with named utilities, the no-args coverage behavior, default radius 25 / max 150, and that utility mode spans the full published extent.

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

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

Front-loaded with the use case before the detail, and the closing example invocation is efficient. The parenthetical enumeration of a dozen-plus utilities is useful evidence of coverage but is the one stretch that verges on bloat.

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

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

An output schema exists, so return formatting need not be described. For an 11-parameter, all-optional tool the description supplies the mode semantics, defaults, coverage, and provenance an agent needs to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3 and the schema already documents aliases, bounds, and capacity_type values. The description goes beyond that by explaining how parameters compose into call modes (point vs. utility vs. no-args) and supplies a concrete example invocation, which the schema alone does not convey.

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

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

States a specific verb and resource — 'utility-published hosting capacity', the MW a named distribution feeder can take — and explicitly distinguishes itself from siblings that give proxies ('not a proximity proxy'), which matters in a family dense with get_grid_data, get_power_availability_timeline, and get_interconnection_queue. An agent can tell exactly what this returns 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.

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

Opens with an explicit trigger ('Use this when the user asks how many MW a distribution feeder can take') and enumerates the three calling modes (lat/lon point, utility/market territory, no-args coverage list) plus example questions it answers. It also rules out the proxy-style tools, so the agent knows when to route elsewhere.

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

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

Annotations already establish readOnly/idempotent/non-destructive, so the bar is low. The description adds real behavioral context beyond them: provenance (EIA public domain, five ISO project lists), a critical grain caveat that a row count is a count of upgrades rather than whole projects, and the delisting/source-release behavior implied by include_delisted.

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

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

Long but deliberately structured: trigger statement first, then COVERS, then NOT, then a worked example, so the load-bearing guidance is front-loaded. The coverage block is dense but each clause (sources, fields, grain) carries information an agent needs to interpret results correctly.

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

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

With an output schema present, return values need not be explained, and the description covers everything else: what is included and excluded, source provenance, per-source grain, status vocabularies, and units. Nothing an agent needs to invoke or interpret this 10-parameter, zero-required tool is missing.

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

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

Schema description coverage is 100%, so the schema already carries parameter documentation and the baseline is 3. The description still adds value by enumerating status vocabularies, giving unit meaning (MMcf/d, $M, kV), explaining the per-ISO grain of transmission rows, and showing a concrete invocation pattern (type=gas_pipeline state=LA status=Construction).

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

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

States a specific verb+resource (retrieving planned/proposed/approved/under-construction infrastructure projects) and immediately scopes it against the existing network, so it is distinguishable from sibling tools like get_pipeline or get_infrastructure. The two coverage categories (EIA gas pipelines, five ISO transmission lists) are named explicitly with their source lists.

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

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

Gives explicit when-to-use triggers ('what ... are planned, proposed, approved or under construction — the forward build-out, not the existing network') and sample queries, plus negative scope (NOT CAISO or NYISO, not utilities outside those ISOs). It stops short of naming the alternative sibling tool an agent should pick for the existing network, leaving that routing to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the safety profile is covered structurally. The description adds meaningful context beyond that: the upstream data sources (HIFLD/EIA), that results are 'raw nearby assets' rather than scored output, and that each asset carries distance and capacity. It does not discuss pagination or rate limits, but with strong annotation coverage that gap is minor.

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

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

The description is dense and front-loads the core purpose before enumerating layers and the exclusion. Every sentence carries information, though the listing of layers plus data sources plus sample query makes it slightly long; nothing is wasted but it is near the upper practical length.

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

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

An output schema exists, so return-value documentation is not required, yet the description still summarizes the shape (distance + capacity per asset). With 9 params fully covered by the schema, annotations handling safety, and an explicit sibling exclusion, nothing an agent needs to invoke this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds semantics the schema alone doesn't convey: layer values map to distinct asset types (substations/transmission/pipelines/power_plants), transmission is filtered at >69 kV, and power plants are split into operating + planned by fuel. The worked example (lat/lon/radius_km) also demonstrates intended usage beyond the field docs.

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

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

The description gives a specific verb and resource ('what power infrastructure is near a site') and enumerates exactly what is returned: substations with count and max voltage, transmission lines over 69 kV, pipelines, and power plants by fuel. It explicitly distinguishes itself from the sibling analyze_site, so an agent can route correctly 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.

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

It states when to use it ('when the user asks what power infrastructure is near a site'), supplies sample utterances that trigger it, and names the exclusion: 'do NOT use for a single scored site-suitability verdict (use analyze_site).' Both the trigger and the anti-trigger are present with the alternative named.

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

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint=false, so safety is covered. The description adds genuine context beyond that: the score's composition, its 0-100 range, the 300+ market comparison set, and the 7d/30d trend output. It does not cover rate limits or data freshness/latency, which keeps it from a 5.

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

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

Front-loaded with the trigger and the return summary, then the routing exclusions. Dense and mostly waste-free, though the long component enumeration and the duplicated 'one composite health number' phrasing cost a little.

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

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

An output schema exists, so return-shape explanation is a bonus rather than a requirement, and the description still sketches the key returns. For a zero-parameter read tool, an agent has everything needed to select and call it correctly.

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

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

Zero declared parameters, so the baseline is 4. The description supplies a concrete call example ('get_intelligence_index market=northern-virginia'), though this implies a 'market' argument the empty schema does not define, which is a minor inconsistency rather than added semantic depth.

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

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

States a specific verb+resource ('composite score (0-100) aggregating supply/demand balance, vacancy, absorption velocity, fiber depth, power availability, and pricing trend') and explicitly names the siblings it is not (get_market_intel, rank_markets). An agent can distinguish this from the 90+ other 'get_*_intel' tools without opening a schema.

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

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

Gives an explicit trigger ('when the user asks how healthy a data center market is'), sample utterances it answers, and two named exclusions with the correct alternatives for each (full metric set → get_market_intel; multi-market ranking → rank_markets). 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.

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

Annotations only cover the safety profile (readOnly, idempotent, non-destructive, open-world), but the description discloses non-obvious behavior: the 'projects' field is polymorphic (array of rows when iso is given, summary object when omitted), ERCOT uniquely exposes a large-load queue, and the keyless call returns a trimmed preview vs a keyed/free full response. These are exactly the traits an agent cannot infer from 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.

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

Front-loaded with the trigger and return value, then layers in shape variance, ERCOT special case, and access tiers. Slight redundancy: 'Keyless: a trimmed preview; free with an email-bound key' is partly restated by 'free = preview' and by the payment param descriptions.

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

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

Despite an output schema existing, the description supplies the polymorphic response shape, the ERCOT-only queue nuance, and the free-vs-paid access path — the information an agent needs to call and interpret the tool correctly. Nothing material is missing for a zero-required-parameter read tool.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema does not: iso's presence changes the response shape, and omitting it yields an all-ISO snapshot. Payment params are also framed as requiring explicit human approval. It restates 'iso optional' rather than adding new syntax.

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

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

States a specific verb+resource (grid interconnection queues) and names the exact payload ('queued generation GW per ISO'), which separates it from adjacent data tools like get_grid_intelligence, get_refined_queue and get_power_pipeline. It also names the user question it answers (queue congestion, data-center load waiting).

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

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

Gives a concrete triggering condition ('when the user asks about... how congested an ISO's queue is or how much data-center load is waiting') and routes to a complementary sibling ('for demand and headroom on the same ISO also call get_grid_intelligence'). It does not state when NOT to use it or when to prefer get_refined_queue/get_power_pipeline instead.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), and the description still adds real behavior: greedy priority-order fill under a budget, per-section token accounting, and the tier gate ('locked_sections need a higher tier') which is a paywall constraint no annotation discloses. It also imposes a citation attribution requirement.

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

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

Front-loaded with the use-case and the section inventory before the exclusion list, and the example call is compact and high-signal. The section enumeration is a long clause but every item is a distinct capability rather than filler; slightly denser than ideal, though nothing is padding.

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

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

For a two-parameter read with an output schema and full annotation coverage, this is more than sufficient: content list, budget behavior, sibling exclusions, tier limits, and citation duty are all present. The output schema carries the return shape, so the description is not obligated to explain it and yet still summarizes it.

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

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

Schema coverage is 100%, so baseline is 3; the description goes further by restating the enum set, the 200-8000 range with default 4000, and the fill-order semantics of max_tokens, plus a worked example call. It stops short of saying what happens when the budget is too small to fit even one section, which the schema's 'omitted' field hints at but the prose never explains.

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

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

States a specific verb and resource ('returns a token-budgeted context pack for a US ISO/RTO') and enumerates exactly what the pack contains, down to per-section token counts and citable URLs. It also self-labels as 'the narrative briefing pack', which separates it cleanly from get_grid_data, get_grid_intelligence, and compare_isos in a crowded sibling namespace.

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

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

Opens with an explicit 'Use this when' trigger and then names four alternatives with the exact condition that selects each ('Do NOT use for raw single-ISO telemetry (use get_grid_data)', etc.). An agent can route correctly without opening any sibling schema.

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

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

Beyond the readOnly/idempotent annotations, it discloses the greedy priority-fill algorithm, that each section carries its own token count, as_of timestamp and citable URL, that anything exceeding the budget is marked omitted, and a citation obligation. These are non-obvious operational behaviors an agent must know to interpret output correctly.

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

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

Front-loaded with the use case and output shape, then a worked example, then routing exclusions — good ordering with no filler sentences. It is dense and slightly repetitive, re-specifying param ranges and default that the schema already documents.

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

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

Covers trigger, parameters, return shape, budget/truncation behavior, sibling exclusions, and attribution requirements for a single-call briefing tool. Although an output schema exists, the prose return summary is a helpful cross-check rather than a gap-filler, and nothing an agent needs is missing.

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

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

Schema coverage is already 100%, so the baseline is 3; the description adds real semantics — that market slugs must be sourced from rank_markets, that max_tokens drives a priority-ordered fill, and range/default. It largely restates the schema's param text, which keeps it out of the top band.

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

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

States a specific verb and resource (returns a token-budgeted whole-market briefing pack) and enumerates the exact sections included. It explicitly distinguishes itself from get_market_dcpi_rank, get_market_intel, and rank_markets, so an agent can route 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.

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

Explicit when-to-use trigger ("when you need a whole data center market briefing for your context window") plus a concrete example query. It also names three alternatives and the exact condition that selects each, which is the strongest form of routing guidance.

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

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

Annotations already cover the safety profile (readOnly, idempotent, not open-world), and the description adds non-obvious behavior on top: daily refresh cadence, CC BY 4.0 licensing after 30 days with an attribution requirement, tier gating (verdict and composite free; sub-scores and narrative paywalled), and 404 semantics for unknown slugs.

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

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

The trigger question and the core payload list are front-loaded, and most sentences carry routing, licensing, or gating information. Some promotional framing ("300+ markets worldwide", "structured reasoning + ready-to-cite prose") slightly dilutes density.

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

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

For a single-lookup tool with an output schema, the description covers everything an agent needs: how to obtain the slug, error behavior, what is free vs gated, and a plain-language summary of the returned verdict fields.

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

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

Schema coverage is 100% and the single param is fully described in the schema, so baseline is 3. The description adds operational meaning the schema lacks: where the slug comes from (rank_markets) and what a 404 means. It stops short of format/syntax guidance, so not a 5.

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

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

States a concrete verb+resource (returns DCPI rank verdict for ONE market) and enumerates the returned fields. It explicitly distinguishes itself from rank_markets and compare_isos, so an agent can route 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.

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

Names the triggering user questions, gives an explicit exclusion ("Do NOT use to rank many markets at once (use rank_markets) or to compare ISO grids (use compare_isos)"), and states the selection condition (one market in depth). This is the when/when-not/alternatives pattern at full strength.

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