DC Hub — Data Center Site Selection & Colocation: Electricity, Power Grid, Gas, Fiber

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

Annotations already cover readOnlyHint, idempotentHint, and destructiveHint, and the description adds useful behavioral context beyond those: the refresh cadence ('Refreshed Fridays 14:00 UTC'), the ranking logic ('composite score (depth + diversity + power)'), and the caveat that cooling-type signals appear only 'where facility data carries them.' This meaningfully supplements the annotation metadata.

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 three sentences with no wasted words. It front-loads the core ranking behavior, then lists what is returned, then covers usage boundaries. Every sentence contributes either to selection, invocation, or differentiation.

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

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

Given the tool has an output schema, the description does not need to enumerate return types exhaustively, but it still summarizes the key output fields and scoring rationale. It also provides refresh timing, use cases, and explicit sibling exclusions, making it fully self-sufficient for correct tool selection and 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% for both parameters, so the baseline is 3. The description reinforces the horizon concept ('next 30/60/90 days') and adds business context for why the parameter matters, but it does not provide additional parameter-level syntax or format details beyond what the schema already documents.

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 and resource: 'ranks data center markets by where 100MW of AI training capacity can land in the next 30/60/90 days.' It clearly separates this from sibling tools by naming rank_markets and grid_transition_radar as alternatives, so an agent can identify the correct tool without inspecting its 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?

The description explicitly states recommended use cases ('AI capex planning, GPU cluster siting, hyperscaler deal forecasting') and gives direct exclusion guidance: 'Do NOT use for a general best-markets ranking (use rank_markets) or forward grid-emergence (use grid_transition_radar).' This gives the agent both positive and negative selection criteria.

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

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

Annotations already mark readOnly/idempotent/non-destructive, lowering the burden; the description adds meaningful behavior beyond that: a point outside hosted coverage returns an honest 404 with the coverage list rather than a guess, and representative_point is chosen from the largest-area member to avoid off-pacel geometric centers. These details materially affect how the agent interprets results and failure modes.

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

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

Extremely dense and front-loaded, with no fluff sentences; the core action and scoping come first. However, it is one long paragraph with heavy parentheticals, and a short bulleted structure would improve scanability for an agent.

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-value format doesn't need to be restated; the description adds coverage rollout, 404 error behavior, anchor semantics, handoff integration, and sibling routing. For a 7-param, 0-required tool with two invocation modes, nothing critical 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?

Input schema covers all 7 parameters at 100%, so baseline is 3; the description still adds useful nuance by clarifying that a MultiPolygon 'carries discontinuous pacels as one envelope', that lat/lon is the hosted-lookup path when geometry is omitted, and that capacity_mw passes into the site_evaluation_handoff. It doesn't add substantial syntax detail beyond the schema, but the mode-level semantics are helpful.

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?

Opens with 'Structured read of a parcel BOUNDARY', naming a specific verb (read), resource (parcel boundary), and outcome (anchor + size). It explicitly contrasts with analyze_site and get_refined_queue, so an agent can tell it apart from the closest siblings without digging into 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?

Provides explicit routing rules: 'Use when you HAVE a boundary or a point on a specific parcel' and directs to analyze_site for general lat/lon site scores and get_refined_queue for queue survivors. It also distinguishes the two input modes — own GeoJSON boundary vs lat/lon hosted-pacel lookup — so usage is unambiguous.

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

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

Beyond annotations, the description discloses major behavioral nuances: location resolves to a market's PUBLISHED CENTROID and is 'a MARKET-level read, NOT the parcel you named'; 'Ashburn, VA' will not resolve because trailing state is not stripped; capacity_mw deliberately does NOT move overall_score; candidate_id uses the frozen mint and ignores lat/lon; free vs Pro tier output differences are explicit. These are exactly the non-obvious traits an agent needs, and none contradict the annotations.

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

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

The description is long but every sentence earns its place—usage, example, parameter semantics, return breakdown, free/Pro division, and sibling alternatives are all packed in. It is front-loaded with the primary use case and example, and the dense structure mirrors the tool's complexity. No filler or tautology.

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 (14 params, optionality logic, tiered output, resolution edge cases), the description is remarkably complete. It covers invocation, parameter behavior, return structure, free/paid differences, and exclusions, so an agent can call it correctly without external lookup. The output schema exists, and the description still explains the headline output and what the full paid result includes.

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

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

Schema coverage is 100%, but the description adds meaning beyond the schema: it explains the optionality condition among lat/lon, location, and candidate_id; clarifies that location is a market-level lookup with centroid resolution; notes capacity_mw returns a capacity_context and intentionally leaves overall_score unchanged; and states the defaults for include_* booleans. This goes well beyond the schema's basic type/description.

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 and resource: a full multi-factor data-center suitability read for ONE specific lat/lon parcel or candidate site. It distinguishes itself from siblings by explicitly naming compare_sites, find_alternatives, get_water_risk, get_disaster_risk, get_climate_intel, get_tax_incentives, and get_composite_site_score as alternatives for other intents. This gives an agent a clear, non-confusable purpose.

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

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

The description opens with 'Use when a user has ONE specific lat/lon...' and provides a concrete example invocation. It explicitly states when NOT to use the tool ('Do NOT use to compare 2+ sites' / 'to find sites that match a target') with named alternatives. It also routes dedicated water/disaster/climate/tax reads to their specialized tools, leaving no ambiguity about selection.

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

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

Annotations carry only readOnlyHint=false and destructiveHint=false, leaving the disclosure burden on the description — which it fully bears. It discloses the free-tier gate mechanics (10 free calls → previews → 50/day after binding), the failure mode ('If the email can't be accepted, the key keeps working'), consent defaults (marketing OFF, transactional only), and even an honest caveat that the retention benefit is UNPROVEN with a small cohort. Nothing contradicts the annotations; readOnlyHint=false aligns with binding being a state-changing but non-destructive operation.

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

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

The '★ WHAT THIS DOES AND DOES NOT DO' opening is a strong front-load that prioritizes the core distinction. However, the description is a dense wall of text covering the cohort-size statistical caveat, verbatim scripts, and consent boilerplate — some of which repeats the schema descriptions (email guidance appears twice). It could be tightened by roughly a third without losing invocation-critical information, so it is helpful but not concise.

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

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

For a high-stakes consent/mutation tool, nothing needed to invoke it correctly is missing: the trigger condition, the exact question to ask the human, the consent purpose line to surface, the failure behavior, and the return statement ('Returns the unlocked benefits + confirmation') backed by an output schema. This is a complete operational brief for an agent.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds consequence-level meaning beyond the schema: fake/placeholder addresses are rejected server-side and make the key unrecoverable, api_key omission binds the already-active session key, and marketing_opt_in must follow explicit human agreement with an unsubscribe guarantee. This elevates the semantics from mechanical 'what' to practical 'what happens if wrong'.

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+outcome: 'Tie your DC Hub key to your human's email so the key is RECOVERABLE and upgrade receipts land in the right inbox.' It also explicitly states what it does NOT do ('does NOT make your identity durable'), which distinguishes it from sibling recovery/durability concepts like recover_my_key and claim_free_key. An agent can tell exactly what state change this performs.

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

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

Provides explicit when-to-call ('Call this once your human shares their email') and when-not-to-call ('If your human hasn't shared an email, ask them first — don't call this tool with a made-up value'). It names the alternative path (OAuth sign-in) with the exact condition that selects it (401 WWW-Authenticate challenge), and references the follow-up tool recover_my_key, giving clear routing among siblings.

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

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

Although annotations only state readOnly=false and destructiveHint=false, the description carries the full burden and does so richly: re-minting restarts the daily allowance and orphans history, hosted gateway clients cannot persist the key, OAuth requires a human at a browser, and the return payload includes connect_url for paste-a-URL clients. It even discloses measured failure rates and side effects, going well beyond the minimal annotation information.

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 content is extremely long, with repeated motivational warnings, multiple dated measurement stats, and several asides that are not needed for selecting or invoking the tool correctly. The core mint instruction appears only after several advisory blocks, so it is not well front-loaded. While the ★ structure helps, the description is not 'appropriately sized' and many sentences do not earn their place.

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

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

For a tool with this complexity, the description is remarkably complete: it covers when to use, when not to use, per-client behavior, side effects, recoverability, return fields, rate limits, and the upgrade path via unlock_more_data. There is a full output schema noted, and the description even enumerates the returned fields, leaving little ambiguity for an agent.

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

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

The schema already covers both parameters 100%, so the baseline is 3. The description adds meaningful context: email is optional but makes the key recoverable across sessions and is the durable anchor for hosted web clients, while client_name is for attribution. This exceeds mere schema repetition.

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: mint a free DC Hub dev key in one call, returning an api_key to set on X-API-Key. It also clearly distinguishes itself from siblings by naming alternatives such as recover_my_key, unlock_more_data, and bind_email, so an agent can pick this tool correctly.

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

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

Provides explicit when-to-use ('the moment you hit a paywall or a partial preview'), explicit when-not-to-use ('Do NOT call this again if you already hold a key'), and names alternative tools. It even explains client-type exceptions where the key is useless and directs to recover_my_key instead. This is exemplary usage guidance.

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

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

Annotations already mark the tool as read-only, idempotent, non-destructive; the description substantially adds behavioral context: physics floors vs inferred estimates, route_factor 1.4, provenance tiers, deterministic pruning, fail-closed candidate handling, and a strong caveat that results are not engineered latency quotes. No contradiction with annotations.

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

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

The description is long but every sentence carries functional weight: purpose, usage, candidate contract, example, return structure, and limitations. It is front-loaded with the core value proposition and organized logically, though it could benefit from tighter formatting given its 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?

For a complex tool with 4 parameters, candidate-contract edge cases, and nuanced output semantics, the description covers everything needed: input modes, output shape, assumptions, provenance, typical use cases, and clear warnings about interpretation. The presence of an output schema reduces the need to explain return values, and the description still sketches the result 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% and the input schema already documents sites, candidate_ids, max_latency_us, and min_confidence in detail. The description re-emphasizes some points (frozen coordinates, fail-closed candidate declaration, typical sync replication latencies) and gives a concrete example, but adds little genuinely new meaning beyond the schema.

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

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

Description states a specific verb and resource ('returns viable low-latency clusters and pairwise RTT floors') with an explicit scope (2-8 sites) and position ('before any routing work'). It also distinguishes itself from siblings by naming plan_fiber_leadin and get_fiber_readiness as 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?

Provides explicit when-to-use context ('Use when your human wants to know which N candidate sites can form a synchronous / low-latency cluster') and names the excluded alternatives ('For actual route corridors use plan_fiber_leadin; for a single-site connectivity score use get_fiber_readiness'). Also documents the candidate contract with get_refined_queue.

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. The description adds valuable non-obvious behavioral context: avg_time_to_power_months and avg_queue_wait_months are DIFFERENT measurements with different derivation methods, and the description warns the agent to quote whichever it means by name.

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

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

The description is dense but every sentence earns its place: use case, example, parameter constraints, return shape, semantic caveat, and alternatives. The critical usage guidance is front-loaded, and the caveat about the two time metrics is explicitly highlighted with stars.

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 comparison tool with one parameter and a rich output shape, the description covers everything needed to call it correctly: valid inputs, count constraints, example, return fields, and exclusions. The output schema exists, but the description still usefully enumerates the included metrics and clarifies the meaning of the proxy measures.

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 for the only parameter is 100%, so the baseline is 3. The description adds extra value by reinforcing the 2-4 count constraint, providing the full list of valid values, giving a concrete example, and explaining that the parameter is comma-separated.

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 and resource: 'side-by-side of 2-4 ISO grids' and enumerates the exact metrics compared. It also clearly differentiates itself from get_grid_intelligence and get_grid_scoreboard, which removes ambiguity about what this tool uniquely does.

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

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

The description explicitly says when to use the tool ('when a user wants a side-by-side of 2-4 ISO grids') and when not to: 'Do NOT use to rank ALL grids globally (use get_grid_scoreboard) or for the single-ISO deep brief (use get_grid_intelligence).' It even provides a concrete example query and parameter invocation.

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

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

Annotations already cover readOnly, idempotent, non-destructive, so the description carries less burden here. It adds real behavioral context: it runs analyze_site internally on each parcel, states the free tier returns a locked preview while paid returns full results, and clarifies that capacity_mw is forwarded but does not move overall_score, so the winner is picked on location suitability. Strong added transparency beyond annotations.

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

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

The description is long and dense, including a full return shape that overlaps with the output schema. It front-loads the core purpose and usage, but the return-shape enumeration is redundant given the output schema exists, and the MPP payment details are already in the schema. Every sentence doesn't earn its place; some could be trimmed 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?

Given the tool complexity (5 params, paid/free gating, internal delegation to analyze_site, output shape) the description is nearly complete. The output schema exists, so the detailed return-shape enumeration is unnecessary but not harmful. Covers constraints, exclusions, pricing, and behavior. Only minor gap: no explicit statement about error cases/edge conditions, but acceptable for a read-only comparison tool.

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

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

Schema coverage is 100%, so baseline is 3, and the description adds useful semantics: locations format and 2-4 max, capacity_mw forwarded but not affecting overall_score, and the meanings of mpp_pay/mpp_credential are already explained in the schema. It doesn't add meaning beyond the schema for the MPP params, but the forwarding nuance is a plus; still, the schema already carries the heavy lifting. A 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 ('compare'), resource ('candidate parcels'), and outcome ('side-by-side winner picker... ranked by overall score'). Explicitly differentiates from analyze_site and rank_markets by saying what it is not for. An agent can tell exactly what this tool does and when to pick it over 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 explicit when-to-use ('narrowed to 2-4 candidate parcels... winner picker'), when-not-to-use ('Do NOT use for a single site (use analyze_site) or to rank entire markets (use rank_markets)'), plus a concrete example query. This is the gold standard for usage guidance.

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

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

Annotations already declare readOnlyHint, iempotentHint, and destructiveHInt false, so the safety profile is covered. The description adds meaningful behavioral context beyond annotations: paid-key gating for full autopsy reads, default cheap progressive disclosure, and the comparables escalation path from count to summary to full. No contradiction with annotations.

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

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

The description is information-dense and front-loaded with the core purpose, then moves to return contents, paid-key behavior, and comparables escalation. It earns its space, though the 'real play' phrasing appears twice and could be tightened slightly.

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

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

For a tool with two optional params and an output schema, the description covers purpose, output shape, auth-dependent behavior, default vs escalated parameter choices, and an example. Nothing essential for correct invocation 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?

Input schema coverage is 100%, so the baseline is 3. The description adds value by framing comparables as an escalation for drilling into a deal, explaining the default 'count only' behavior, and giving a direct example invocation with limit=15. This goes slightly beyond the schema descriptions.

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

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

States specifically that the tool returns data-center M&A/capex deal flow with DCPI verdicts overlaid on each market, and positions it around the question 'what is the real play?'. This is a clear verb+resource description that distinguishes it from siblings like list_transactions or get_market_dcpi_rank.

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 selection context: it answers 'who is actually buying data centers right now' and 'what is the real play behind this deal', plus a 'Try: limit=15' example. It does not explicitly name alternatives or when-not-to-use conditions, but the use cases are clear enough.

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

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

The description goes well beyond the annotations by explaining the return shape (_entity=tool_families), the front_door block with execute_plan and get_changes, and the family structure with when-to-use notes. It also discloses that this is a navigation layer and not exhaustive, which is critical behavioral context.

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

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

The description is dense and front-loaded with the core meta-tool purpose, followed by return details and usage routing. The sentence about binding a capability map is slightly niche but earns its place by preventing a specific misuse. Minor verbosity in listing families is offset by useful when-to-use context.

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

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

For a meta-tool of this complexity, the description covers what it returns, how it relates to the canonical tools/list, when to call it, and what to do after. The output schema and annotations fill remaining structured details, so nothing needed for correct invocation is missing.

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

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

The single optional query parameter is already fully documented in the input schema with examples. The description adds only a brief mention that results are 'optionally filtered by a query,' which is consistent but not substantially beyond the schema. Baseline 3 is appropriate given 100% schema description coverage.

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

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

The description clearly identifies this as a meta-tool for navigating DC Hub's tool catalog by family rather than scanning the full list. It distinguishes itself from the canonical tools/list and gives a concrete resource and behavior, making its role unambiguous even among many 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?

The description explicitly tells the agent to call this tool FIRST when unsure which tool fits a task, then call the chosen tool. It also gives a clear when-not-to-use rule: bind capability maps from tools/list, not from here. This is excellent 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?

Beyond the read-only/idempotent annotations, the description discloses deterministic no-LLM routing, execution under the caller's key with the same quotas, caps (max 6, cap 8, fan-out 3, ~40s budget), and status=not_run for unfinished tails. It also describes the single result envelope and states that execute_plan adds no data access beyond existing tools, with no contradiction of the annotations.

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

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

The description is long but dense and front-loaded with the 'THE FRONT DOOR' call-to-action, followed by explicit caps, examples, and the output envelope. Every sentence contributes routing guidance, behavioral disclosure, or alternatives, though some of the domain enumeration could be trimmed without losing clarity.

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

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

For an 11-parameter orchestrator, the description covers invocation contract, multi-vs-single routing, execution limits, failure behavior, output format, and citation requirements. Combined with the output schema and full parameter coverage, an agent has everything needed to call and use the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful semantics by mandating `intent` pass through UNCHANGED, telling agents to put cohort tags outside the intent string, and explaining that `context` supplies structured hints and step-arg overrides. These nuances go beyond the schema's field descriptions.

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

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

The description states a clear role: a unified planner that runs multi-step tool sequences and returns results, explicitly naming itself 'THE FRONT DOOR'. It identifies the action (plans and answers) and distinguishes itself from sibling plan_query and single-tool calls, so an agent can select it correctly.

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 ('call this FIRST whenever a question spans more than one', 'Use for multi-step questions') and when-not-to ('use plan_query instead when you only want the plan'; 'single-tool questions should call that tool directly'). It names the alternative and the exact routing condition, leaving nothing 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 destructiveHint, so the description is not required to restate safety. It adds value by disclosing the exact return behavior: full file contents as text, with CSV rows or a GeoJSON FeatureCollection including specific fields. This goes beyond the annotations without contradicting them.

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

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

The description is dense but well-organized: usage trigger, example, parameters, return format, and exclusions. Every sentence carries useful information and is front-loaded with the most important routing signal.

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 export tool with rich annotations and an output schema, this description covers purpose, usage, format semantics, return contents, and exclusions. Nothing critical is missing for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100% and already documents format with csv default and geojson for GIS tools. The description reinforces this with an example and clarifies what each format returns in practice, providing context beyond parameter names and types.

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

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

The description uses a specific verb ('export') with a clear resource ('saved DC Hub shortlist') and explicitly contrasts itself with list_saved_sites and save_site. The example invocation makes the tool's role unmistakable.

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

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

It explicitly states when to use the tool (offline analysis, spreadsheet, ingestion into another tool) and when not to use it (listing in-chat or saving a new site), naming the alternatives list_saved_sites and save_site. This gives an agent unambiguous 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=true, idempotent=true, destructive=false), so the description adds the valuable behavioral context: the result is a summary, not the full record; it names the included fields (name, operator, location, status, market) and the excluded ones (capacity MW, coordinates). The return-shape detail partially duplicates what the output schema provides, so not a full 5, but the limitation disclosure is genuinely useful.

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

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

Three sentences, each earning its place: purpose, return shape and content, then explicit alternative routing. Front-loaded with the primary action. No fluff; the OpenAI-format parenthetical adds useful compatibility context rather than noise.

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, schema-covered, output-schema-rich read tool, the description is complete: it states what the input must be, what the output contains, what it does not contain, and where to go for the missing detail. Nothing an agent needs to call it correctly is 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 description coverage is 100% — the id parameter already says it is 'A facility id/slug from a prior search result, e.g. equinix-dc1-ashburg'. The description only reinforces the same provenance ('an id returned by the search tool') without adding new meaning beyond the schema. Baseline 3 is 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 ('Fetch a DC Hub record') with explicit provenance ('for an id returned by the search tool'), and clarifies exactly what kind of record it returns (a citable public summary). It differentiates itself from get_facility by describing the record's scope (summary vs full structured specs), so an agent can tell siblings apart.

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 wires the tool into a workflow ('for an id returned by the search tool') and names the alternative ('For full structured specs... use get_facility or open the url') with the condition that selects it. An agent knows when to call fetch and when to route elsewhere without 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 establish the operation as read-only, idempotent, and non-destructive. The description adds useful behavioral context by describing the return shape (ranked alternatives with similarity_score, match_reasons, and key_differences) and clarifying that this tool discovers candidates from a single seed. It does not contradict the annotations, though it does introduce some confusion about accepted parameters.

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

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

The description is well-structured and front-loaded with the purpose and a concrete example, followed by returns and exclusions. However, the parameter enumeration duplicates schema content and is partly inaccurate, so not every sentence earns its place.

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

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

Given a 100%-covered input schema, an output schema, and safety annotations, the description provides strong contextual guidance: when to use, when not to use, a realistic example, and the key output differences. The main completeness gap is the stale/incorrect parameter summary, but the schema covers the authoritative parameter details.

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

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

Schema coverage is 100%, so the baseline is 3, but the description's parameter summary is actively misleading: it advertises 'facility_id or name' and 'capacity_mw', while the schema explicitly says there is no `name` param and does not include `capacity_mw`. It also omits `match_on` and `exclude_operator`. This adds misinformation rather than useful meaning beyond the schema.

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

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

The description states a precise use case: when a user likes one specific facility and wants similar nearby alternatives. It gives a concrete example and explicitly distinguishes itself from scoring and comparison siblings, 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?

It says exactly when to use the tool ('Use when a user likes ONE specific facility') and when not to use it, naming the alternatives: score_facility/analyze_site for scoring one site and compare_sites for head-to-head comparison. The 'Do NOT use' guidance is explicit and actionable.

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 genuinely useful behavior beyond that: output is a ready-to-open PDF link valid ~7 days with no login, prepared_by defaults to DC Hub, latency_target defaults to nearest carrier hotel, and the survey fields are enumerated. No contradiction with annotations.

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

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

Approximately 200 words for a 10-parameter PDF-generation tool, and every segment earns its keep: trigger, example, param summary, return shape, link behavior, sibling routing. Slightly long, but the density is high and the structure is logical, front-loading the purpose before the details.

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

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

Given the complexity (10 params, PDF artifact, output schema), the description covers everything an agent needs to invoke correctly: correct trigger, worked example, defaults, required parameters, output structure, and operational caveats (7-day validity, no auth, hand to human). The only gap is the schema-vs-description required-params mismatch, which is a schema flaw rather than a description omission.

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 all 10 parameters are documented there; the description adds meaning on top: requiredness of lat/lon, range hints, the 50-500 MW typical window, and role semantics ('client name on the cover', 'brands the report', defaults for both prepared_by and latency_target). Minor caveat: description marks lat/lon as required while the schema list 0 required params.

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

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

The description names a specific verb-resource pair: generating a SHAREABLE, branded multi-page Site Analysis PDF for a single lat/lon. It explicitly distinguishes the deliverable from a bare score ('not just a score') and provides a concrete worked example invocation, so purpose can't be conflated with any sibling.

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 'Use when a user wants...' and closes with an explicit exclusion: 'For just the numeric suitability score (no PDF), use analyze_site instead.' This names the exact selection condition and the alternative tool, leaving nothing 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 establish readOnly, idempotent, and non-destructive behavior. The description goes further by disclosing that the roster is backend-owned and changes, statuses are curated editorial claims rather than live measurements, the response may carry as_of null, and stale enumerations should not be trusted. This is valuable behavioral context beyond the annotations.

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

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

The description is front-loaded with its purpose and includes genuinely important warnings, but it is verbose and somewhat repetitive. Phrases like 'Try: get_agent_registry' and the extended stale-encyclopedia metaphor could be condensed without losing meaning.

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

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

The description fully covers what the tool returns, how to interpret the statuses, the important editorial caveat, and what not to use it for. With no required parameters and an output schema available, 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?

The input schema has zero properties and schema description coverage is 100%, so there are no parameters for the description to clarify. With zero params, the baseline of 4 applies; no additional parameter documentation is needed.

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

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

The description clearly identifies the tool as a curated roster of AI platforms and agent frameworks in the DC Hub ecosystem, including recommended tools and authentication tiers. It also states the exact question it answers ('which AI platforms can connect to DC Hub') and explicitly disambiguates it from telemetry or uptime tools.

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

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

The description specifies when to use the tool and when not to: it is for capability discovery, not for live uptime or feed health, and it explicitly names get_backup_status as the alternative for those cases. This gives an agent actionable 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 declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds meaningful behavioral nuance: a feed reporting 'unknown' has NOT been measured, which is not the same as healthy, and stale/error feeds should not be trusted blindly. It also clarifies the exact scope boundary to /api/health/data-freshness, which is valuable context beyond the annotations.

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

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

The description is detailed and front-loaded with the core value proposition, but slightly redundant in the closing section: 'nothing wider' and 'this is ingest health, not content' convey similar scope exclusions. Minor over-explanation, but every sentence contributes meaningful operational context otherwise.

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

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

For a zero-parameter read-only tool with an output schema, the description covers all necessary context: what fields are returned, what health values mean, how to interpret 'unknown', and the precise scope. There is no missing information an agent would need to decide whether to call 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?

The tool has zero parameters, so baseline is 4. There is no parameter semantics to add, and the description appropriately focuses on the output and interpretation rather than inventing parameter guidance.

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 and resource: per-feed freshness for the DC Hub ingest layer, with exact feeds and a summary rollup. It also explicitly distinguishes itself from get_changes by saying this is ingest health, not content freshness. This makes the tool's purpose unambiguous and differentiates it from 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?

The description explicitly states when to use this tool ('are any of your sources stale right now') and when not to use it ('Do NOT use for the freshness of one dataset (use get_changes)'). It also gives operational guidance, such as reading each row's health before trusting figures drawn from it. This is model-example-level usage guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds substantial behavioral context: the exact categories returned, the conditional portfolio block for 'keyed callers with saved sites,' the since parameter semantics, and the caching instruction to pass back generated_at. It also hints at authentication requirements without overpromising. No contradiction with annotations.

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

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

The description is dense but well organized: it front-loads the core sync purpose, then enumerates return categories, then conditional behavior, then parameter usage, then example invocations. Every sentence adds operational value, including the cache guidance and the 'Try: get_changes since=7d' example. Length is justified by the richness of the tool's behavior.

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 two optional parameters, rich annotations, and an output schema, the description covers everything needed to invoke it correctly: when to use it, what to expect back, parameter formats and defaults, auth-dependent behavior, and pagination/caching hints. The presence of an output schema removes the need to enumerate return fields exhaustively. Nothing important is missing for an agent to select and call this tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value beyond the schema by explaining the intended use of since as a delta cursor, including shorthand forms, default behavior, and the critical guidance to cache and reuse generated_at on the next call. It also gives a concrete example invocation. The limit parameter is not discussed, but the schema fully documents it, so no meaningful gap 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?

The description identifies a specific purpose: incremental synchronization since a timestamp, framed as 'what changed in DC Hub since a timestamp' rather than a full re-fetch. It distinguishes itself from sibling get_* tools by emphasizing the delta-sync behavior and lists concrete returned content. The opening phrase 'Incremental sync' plus the explicit use-case answers make the tool's role unmistakable.

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

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

The description clearly states when to use the tool: when an agent wants only changes since a timestamp, 'so an agent pulls only the delta instead of re-fetching everything.' It provides concrete example invocations like 'get_changes since=7d' and the exact question forms it answers. It does not explicitly name alternatives or state when not to use this tool, so it misses the top bar, but the guidance is strong.

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

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

Annotations already mark it read-only and idempotent, and the description adds valuable behavioral context: strict provenance (USGS ASCE 7 / NOAA ACIS), never estimating missing data, null-when-unavailable behavior, and geographic limitations. This goes beyond the structured annotations without contradricting them.

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

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

The description is front-loaded with purpose and use context, and the remaining sentences are information-dense. The returned-object block is somewhat long and partially redundant with the existing output schema, but it is structured and serves as a usable contract reference rather than rambling.

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 two data domains, an output schema, and a non-trivial radius/geographic limitation, the description covers when to use it, what it returns, how parameters behave, what cannot be returned, and which siblings to prefer. No important selection or invocation information 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; the description adds meaning by explaining the purpose of the lat/lon pair, the example invocation, and the radius_km threshold behavior ('beyond it climate returns unavailable_exceeds_radius'). This is more than the schema alone provides, though most parameter detail remains in the schema.

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

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

The description opens with a specific verb-and-resource statement: it provides seismic + climate intel for a lat/lon, tied to bracing cost and cooling design. It distinguishes itself from siblings by explicitly routing to get_disaster_risk and get_composite_site_score, and it includes a concrete invocation example.

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 says 'Use when a user wants seismic + climate intel for a lat/lon' and also states exclusions: non-US locations get seismic unavailable, and radius_km beyond the threshold returns unavailable_exceeds_radius. It names two sibling tools for different intents, so the agent can choose correctly.

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

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

Beyond the read-only and idempotent annotations, the description discloses crucial behavior: it never imputes missing factors, water is 'unavailable' only outside basin coverage and never faked, market/DCPI is v1-unavailable, and the confidence field reflects complete vs. conditional scoring. This gives the agent honest expectations about data gaps.

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

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

The description is dense but every clause carries information: use case, distinction from analyze_site, validated factors, data-unavailability rules, example, return shape, and sibling routing. It is front-loaded with the most important purpose, though the long parenthetical lists make it slightly harder to parse than an ideal definition.

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 remarkably complete: it explains when to use it, which factors are live, how missing data is handled, what the response contains, and how it compares to analyze_site, compare_sites, and rank_markets. The presence of an output schema means return values do not need further elaboration here.

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

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

The input schema already provides 100% description coverage for all six parameters, so the baseline is 3. The description adds a concrete example call, but it does not introduce new parameter-level semantics beyond what the schema states.

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

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

The description uses a specific verb and resource: it 'scores' to produce a '0-100 site suitability/risk verdict' with an explicit per-factor coverage map. It immediately distinguishes itself from analyze_site by stating the key difference: this tool scores ONLY over validated factors and never imputes a missing one.

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

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

The description opens with a clear 'Use when...' condition and closes with explicit routing: 'Use analyze_site for full data, compare_sites for 2-4 sites, rank_markets for whole-market ranking.' It also names rank_markets as the alternative for market/DCPI, which is currently unavailable here.

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

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

Beyond the readOnlyHint=true and idempotentHint=true annotations, the description discloses crucial behavioral traits: literal category matching only, free text not parsing, the generic fallback response with matched_category=null and context_understood=false, and the additional fields returned on non-matching context (is_generic_answer, answer_note, next_tools). It also fully enumerates the response fields, telling the agent exactly what to expect without needing to infer from the output schema.

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

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

The description is dense but every sentence carries meaningful guidance. It front-loads the core purpose and best usage, then provides exclusions. The main paragraph is long, but the density is justified given the tool's behavioral quirks and the need to prevent misuse. A slight structural improvement would be bullet formatting for the response fields, but the inline enumeration is acceptable for an AI-facing tool definition.

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 tool with a live output schema, the description is exceptionally complete. It covers the exact accepted values, error/fallback behavior, full return shape, and routes to correct sibling alternatives. The output schema already exists, so the description needn't redundantly document return types. The only niche gap might be explaining when top_pocket is stale, but recommendation_live field partially covers that. Nothing essential is missing 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?

The input schema already provides 100% coverage with a rich parameter description and example. The tool description adds critical semantic detail beyond the schema: it explicitly warns that context must match one of four literal categories, that free text does not parse, and it enumerates the exact allowed values. This prevents the agent from passing free text despite the schema's example looking like free text. Slight redundancy with the schema example, hence 4 rather than 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?

The description begins with a specific verb ('Use for') and identifies the exact resource: a ready-to-quote DESCRIPTION of DC Hub in one of four named categories, plus the live top-ranked market pocket. It explicitly states what it does NOT do ('It does NOT compute a siting answer from free text'), which sharply distinguishes it from analysis tools. The clear contrast with sibling tools like site_selection_canvas and rank_markets leaves no ambiguity about the tool's scope.

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

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

The description provides explicit when-to-use and when-not-to-use guidance. It names concrete alternatives (analyze_site for a specific lat/lon, rank_markets for ranking by one criterion, site_selection_canvas for an open-ended siting question expecting a shortlist) and states exactly what this tool returns instead of a ranked analysis. It also explains the behavior when the context parameter is non-matching, including the next_tools field that routes the agent to the right tool.

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

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

Anotations already mark read-only/idempotent; description adds that it is a live query, never estimated, returns coverage=unavailable outside US NRI, and is county-level. This significantly extends behavioral understanding without contradicting annotations.

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

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

The description is longer than average but every sentence contributes: trigger, data source, example, return contract, resolution, and alternatives. The most important usage info is front-loaded.

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

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

For a read-only lookup with 5 alias parameters and an existing output schema, the description covers data provenance, coverage edge case, example call, return shape, resolution, and routing to related tools. No critical operational detail is missing.

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

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

Input schema covers all 5 parameters with descriptions and aliases; description provides a concrete example (lat=33.45 lon=-112.07) but does not add substantial semantics beyond the schema. With 100% schema coverage, baseline of 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?

The description opens with a specific trigger ('Use when a user wants the natural-hazard / disaster risk for a lat/lon') and enumerates hazard types. It also contrasts with sibling tools by naming get_water_risk and get_composite_site_score, so it is unambiguous.

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

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

Explicitly states when to use and gives two alternatives with conditions ('For chronic water stress use...; for one blended site verdict use...'). Also delimits application to US NRI coverage, telling the agent what to expect outside that area.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and the description adds meaningfully beyond them: the CC-BY-4.0 atribution requirement, the 'one round trip, no planner overhead' performance characteristic, and the domain caveat that the cheapest ISO is frequently the one with no headroom. Nothing contradicts the annotations.

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

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

Dense and front-loaded — the FRONT DOOR CHECK routing decision comes first, followed by use case, return contents, example, and exclusions, and every sentence carries routing or licensing value. However, it is one long unparagraphed wall of text that would benefit from line breaks or tighter punctuation.

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 low-complexity read tool: selection criteria, alternative routing, exclusions, return contents, licensing, and an example are all covered in the description, while the output schema and annotations handle return-value structure and safety profile. An agent can select and invoke this tool correctly without opening any 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 description coverage is 100%, so the baseline is 3. The description adds a concrete invocation example ('get_energy_prices iso=ERCOT'), links data_type focus to the retail/wholesale/gas return fields, and clarifies that iso is effectively required for ISO pricing even though the structured schema lists zero required 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?

States a specific verb and resource — 'live energy PRICING for the 7 US ISOs' — and enumerates the returned fields (retail electricity rate, wholesale/LMP context, Henry Hub-referenced gas price, real-time grid-status flag). A worked ERCOT example anchors the meaning, and the exclusions for get_grid_data / get_grid_intelligence / get_gas_economics help separate it from closely related 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 when-to-use rule ('when a user asks what does power/gas COST in <ISO> right now', or just wants today's price for one ISO) and explicit when-not-to-use routing: siting/market-comparison goes to execute_plan, fuel mix/demand to get_grid_data, headroom to get_grid_intelligence, behind-the-meter gas economics to get_gas_economics. This is the gold standard for alternative 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 declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds context by specifying that it returns exactly one facility in full and enumerates the data categories included, plus the boundary that it should not be used as a search/list tool. No contradiction with annotations.

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

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

The description is front-loaded with core scope and data list, followed by examples and an explicit exclusion. It is detailed but efficient; minor redundancy exists between 'Full metadata for one facility' and 'Returns ONE facility in full'.

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 100% schema coverage, annotations, an output schema, and example invocations provided, the agent has sufficient information to invoke the tool correctly. Domain specifics like DCPI verdict are not required for invocation and are adequately mentioned as part of the return data.

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%, with all six parameters documented in the input schema. The description's example id/slug values add concrete usage hints but do not materially extend the schema-provided semantics. Baseline 3 is appropriate since the schema carries the parameter documentation burden.

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

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

Description begins with 'Full metadata for one facility' and enumerates specific fields (name, operator, address, lat/lon, power capacity, cooling type, fiber providers, commissioning year, status, DCPI verdict, peer facilities), giving a clear verb+resource. It also distinguishes itself from search_facilities by explicitly saying 'Returns ONE facility in full; do NOT use to search or list many facilities'.

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

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

Explicitly states the single-facility lookup use case and provides concrete examples: 'Try: get_facility id=equinix-dc1-ashburn — or get_facility slug=digital-realty-iad8'. It also names the alternative tool for list/search operations: 'use search_facilities'.

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

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

The annotations already mark the tool as read-only and idempotent, but the description adds substantial behavioral detail: only DCPI market-health has a temporal series, site-hazard dimensions are declared static, and missing snapshot history yields coverage:unavailable. This prevents the agent from inventing week-over-week changes and clearly communicates the tool's limitations.

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

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

The description is longer than average but earns its length: it front-loads the use case, then covers return shape, integrity constraints, and alternatives. It is dense but organized, though the capitalization and slightly wordy 'REAL DCPI' phrasing could be tightened.

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

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

For a tool with an output schema, 3 optional params, and extensive sibling context, the description is complete. It explains the temporal vs. static distinction, when results may be unavailable, what the response contains, and which sibling tools to use instead. Nothing essential is missing for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful semantics beyond the schema by clarifying that facility_id and market are alternatives ('OR') and by giving the since window format and default. This helps the agent choose the right parameter combination even though each param is already documented.

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 and resource: returns the DCPI market-health delta (change over a window) for a facility or market. It clearly distinguishes this from point-in-time risk tools by emphasizing temporal change, and gives concrete example queries ('has this site gotten riskier lately?').

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 explicitly says when to use the tool: when the user asks what has changed in a facility's or market's risk profile recently. It also names the alternatives for point-in-time risk (get_composite_site_score, get_disaster_risk, get_climate_intel), and warns against fabricating deltas for static dimensions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds genuine behavioral context beyond that: it specifies the '~1.2°' proximity rule for market filtering, explains the GeoJSON return structure, and clarifies that the tool returns ONLY routes touching the named metro. The mpp_pay/mpp_credential parameters are also transparently explained in the schema. No contradiction with annotations.

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

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

The description is dense but well-organized: usage context first, then a concrete example, then the market-scoping behavior, then the return shape, then exclusions. Every sentence earns its place and the structure front-loads the most decision-relevant information. The return schema and param enums are not needlessly duplicated, though the description is fairly long and could be trimmed slightly.

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

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

For a read-only geodata query with six parameters, zero required fields, an output schema, and 100% schema coverage, the description is complete. It states the geographic scoping rule, names the sibling alternatives for the two most likely misconceptions, documents the payment flow, and describes the GeoJSON shape. An agent can select this tool, set parameters, and interpret the result without any additional tool discovery.

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. The description nevertheless adds value by explaining the market filter's ~1.2° proximity behavior, giving concrete enum examples for carrier and route_type, and showing how route_type=longhaul pairs with market. It also covers the free-vs-paid semantics of mpp_pay. This exceeds the baseline-3 for fully covered schemas.

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 pairing ('scoring a candidate site for fiber depth, mapping long-haul routes between metros, or assessing dark-fiber availability') and immediately distinguishes the tool from siblings by name ('Do NOT use ... use get_acility' and 'use analyze_site'). The worked example with carrier=Zayo route_type=longhaul further anchors what the tool returns and how it is invoked.

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

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

The description provides explicit when-to-use guidance ('Use when scoring a candidate site for fiber depth, mapping long-haul routes...') and also explicit when-not-to-use guidance with named alternatives ('Do NOT use to count fiber providers at a single facility (use get_acility) or for IX interconnection-density scores (use analyze_site)'). It even includes a concrete example query and parameter mapping, leaving little 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?

Despite annotations already carrying readOnlyHint and idempotentHint, the description adds critical behavioral context: the PeeringDB data source, the semantic distinction between 'unknown' and 'build-required', null behavior for score/single_carrier_risk, and a warning not to treat 'none_in_region' as unserved. This goes well beyond the annotations and prevents a likely misinterpretation.

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 definition is long but every sentence earns its place: use-case, example, parameter summary, return shape, and a critical caveat on interpreting 'unknown'. The warning is front-loaded toward the end after the necessary context, and the structure separates the core purpose from the interpretive nuance.

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 complex null semantics and a coverage distinction, the description covers input usage, output fields, enums, null rules, and alternatives. The existing output schema handles raw return shapes, and the description supplies the missing interpretation layer—especially the 'unknown is not bad' rule—making it effectively complete for agent 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 documents each parameter, so the baseline is 3. The description adds value by explicitly declaring lat/lon as required (the schema has no required list), giving a full example invocation, and restating radius default/range in human terms, which reinforces but does not radically extend 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 pair: get the FIBER-READINESS / connectivity verdict for ONE parcel or site, and enumerates the core outputs (near-net distance, carrier count, single-carrier risk). It explicitly distinguishes itself from get_fiber_intel (routes between metros) and analyze_site (multi-factor suitability), so an agent can select it correctly without opening the 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 provides a clear 'Use when' trigger—needing the parcel connectivity verdict for a single lat/lon site—and an explicit 'Do NOT use' clause naming get_fiber_intel for metro route mapping and analyze_site for full suitability scoring. Example usage and parameter guidance reinforce the selection criteria.

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

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

The description discloses a significant behavioral trait: the gas-to-grid $/MWh output was withdrawn after serving inconsistent and physically impossible values. It explains the withdrawal date, the reason, and the current behavior without contradicting the read-only/idempotent annotations.

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

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

The description is longer than average, but the extra length is mostly operational warning content that prevents misuse. The resource definition is front-loaded, and the withdrawal guidance is clearly delimited, though it could be tightened.

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

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

The annotations and output schema already cover read-only behavior and return structure. The description supplies critical withdrawn-field context and an explicit exclusion to get_grid_data. The main gap is the unresolved role of heat_rate_btu_per_kwh in the schema relative to the withdrawn $/MWh output.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds market slug examples and clarifies which data layers still exist, but it does not explicitly explain how the optional heat_rate_btu_per_kwh parameter should be treated now that the gas-to-grid $/MWh scenario is no longer returned.

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: behind-the-meter gas-fired power inputs for US data-center markets, and enumerates the returned $/MMBtu components (Henry Hub spot, regional basis differential, delivered industrial + electric gas tariff). It also differentiates itself from get_grid_data, so an agent can select it confidently.

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

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

The description explicitly says not to use this tool for the electricity grid fuel mix and points to get_grid_data as the alternative. It also gives clear operational constraints: do not quote cached $/MWh figures, do not derive them without attribution, and rely on gas_to_grid_status for the reason.

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 the bar is lower, yet the description adds substantial context: the withdrawal/restoration history, the three repaired defects (case-blind EIA TYPEPIPE term, non-deterministic price tie-break, hardcoded cost constant), the UNSCORED-as-absence semantics, and the still-withdrawn $/Wh figures. It discloses a known landmine (serial incomparability) that annotations cannot express. No contradiction with annotations; readOnlyHint aligns with a read 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?

Cearly front-loaded with the purpose sentence, but the description is ~200 words with repeated warnings: the UNSCORED message and the withdrawal warning appear nearly verbatim in both the tool description and the state param schema description, wasting tokens. The three-asterisk correction narrative on the repair defects is dense and could be compressed to the operational implication. It reads as a patch list rather than a tool contract.

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 this much hidden complexity — temporal incomparability, null-as-absence semantics, a separate still-withdrawn artifact — the description is highly complete. The output schema exists, so return values don't need spelling out. Minor deduction for the repetitive structure, but nothing an agent needs 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% for both params, so baseline is 3. The description adds meaning beyond the schema by explaining why `gas_price_series` matters (which EIA series answered, PIN vs PEU carrying different margins) and why a state may come back UNSCORED with null dcgi. It deepens the agent's understanding of the state parameter's output behavior rather than merely restating 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+resource+scope: 'Data Center Gas Index (DCGI) — the per-US-state natural-gas suitability score.' It clearly distinguishes what this tool returns (a per-state score with verdict and series attribution) from the sibling get_gas_intelligence by naming that alternative for pipeline/operator data. The purpose is unambiguous and not obscured by the correction history.

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

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

Explicitly says 'Use get_gas_intelligence for pipeline, operator and parent-midstream data,' routing the agent away from this tool for those data. Also gives a strong when-not-to-use constraint: 'DO NOT COMPARE a DCGI figure published before 2026-08-08 with one published now.' This is exactly the level of directive an agent needs to avoid a subtle misuse.

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

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

Annotations already mark this as read-only and idempotent, and the description adds substantial behavioral context beyond that: withdrawn and restored index terms, the warning not to compare pre-2026-08-08 figures with current ones, the deliberate omission of gas storage/LNG/firm pipeline capacity, and the instruction to read dcgi_status and gas_to_grid_status instead of assuming both moved together. It also discloses that gas_to_grid $/MWh remains unfixed due to a 5.5x disagreement across five surfaces.

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

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

The description is long, but the length is largely justified by the tool's many caveats, withdrawn fields, and need to distinguish sibling tools. It is front-loaded with the use case and core return object before diving into warnings, and most sentences carry operational value. A small amount of redundancy and all-caps emphasis prevents a perfect score.

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 the output schema existing, the description goes beyond it to explain important runtime context: null delivered price where tariff data is sparse, per-field data_basis provenance, withdrawn vs restored fields, omitted categories, and how to route different user questions to different sibling tools. For a complex data-fusion tool, this is thoroughly complete and should leave an agent well-equipped 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 description coverage is 100%, so the schema already explains both state and region parameters. The description reinforces that region accepts a US state code or name with examples like 'TX', 'Texas', and 'Virginia', which is helpful but not materially beyond the schema. This is the appropriate baseline score given the high schema coverage.

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

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

The description opens with a specific trigger condition ('Use when a human asks about gas-fired or behind-the-meter power economics for a data center in a US state') and names the exact resource it returns: a per-state brief fusing multiple gas-related data sources. It also explicitly distinguishes itself as the 'GAS analogue of get_grid_intelligence', making its purpose unmistakable against sibling tools.

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

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

The description gives strong when-to-use guidance with concrete example questions, and explicitly states when NOT to use it: for electricity grid headroom use get_grid_intelligence, and for the DCGI score alone use get_gas_index. It also clarifies what is currently returned and what remains withdrawn, so an agent can avoid misuse.

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, and non-destructive; the description adds valuable behavioral context: data source (GEM Global Integrated Power Tracker), scope (182k units, 170+ countries), and the response shape (summary plus largest units rather than a full dump). No contradiction with annotations.

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

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

Long but front-loaded: trigger, scope, data source, filters, output shape, examples, and exclusions all serve a purpose. Minor filler like 'Examples help' and a couple of typos keep it just shy of a perfect score.

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

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

Given 7 optional params, an output schema, and rich annotations, the description covers everything needed for selection and invocation: when to use, what it returns, how filtering works, and which siblings to use instead. 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?

Input schema has 100% description coverage, so the baseline is already adequate. The description adds semantics: comma-union fuel filtering, bbox coordinate order, pipeline=true meaning announced+pre-construction+construction, and worked country examples. It doesn't add much about limit, but the schema covers that.

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 concrete trigger: power plants/units worldwide or in a NON-US country, covering operating and pipeline across all fuels. It explicitly distinguishes itself from US-specific, pipeline-specific, and project-level sibling tools, so an agent can select it correctly without opening other schemas.

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

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

Provides explicit when-to-use guidance ('Use when...'), explicit when-not-to-use ('Do NOT use for US-specific grid questions...'), named alternatives (get_grid_data/get_grid_intelligence, get_power_pipeline), and a boundary between high-level comparisons and project-level detail (get_facility/search). This is model 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds meaningful behavioral context: data is raw real-time telemetry for exactly one ISO, sourced from EIA hourly RTO, and limited to the 7 US ISOs. This gives the agent a clearer sense of the data's nature and limitations without contradicting annotations.

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

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

The description is three sentences with no filler. It front-loads the core purpose, then compactly provides scope limitations, alternatives, and geographic boundaries. Every sentence carries 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?

Given the annotations, output schema, and a relatively simple 3-parameter interface, the description covers all key aspects needed for selection and invocation: what data is returned, for which regions, how to specify the ISO, and which sibling tools to use instead. Nothing critical appears 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 schema already provides 100% description coverage for all three parameters. The description adds concrete usage hints such as 'Pass iso=PJM (any of the 7)' and enumerates example values for metric (fuel_mix, demand, demand_curve), which helps correct invocation beyond the schema alone.

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

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

The description clearly states a specific verb ('get real-time electricity grid data'), a specific resource (7 US ISOs via EIA hourly RTO), and the key data dimensions (fuel mix, demand, 24h demand curve). It also explicitly distinguishes itself from sibling tools such as get_grid_intelligence, get_energy_prices, and get_grid_scoreboard by delineating what it is not for, so an agent can reliably identify this tool from its 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?

The description provides explicit when-to-use and when-not-to-use guidance with named alternatives: do not use for power-availability/time-to-power/interconnection-queue analysis (use get_grid_intelligence), do not use for retail/gas pricing (use get_energy_prices), and for non-US grids use get_grid_scoreboard. This is model guidance for tool selection.

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

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

Annotations already signal readOnly and idempotent behavior, and the description adds significant context: market names resolve to their ISO via the DCPI row, balancing authorities return only live generation mix while other figures stay ISO-level, and the reply carries a resolved_from block. The explicit warning that avg_time_to_power_months and avg_queue_wait_months are different measurements with different derivations is particularly valuable and does not contradict any annotation.

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

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

The description is front-loaded with the trigger question and example, and every block serves a purpose. However, it is very long and repeats some parameter details that already exist in the schema, such as the ISO list and PJM-DOM note; it is thorough but not concise.

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

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

Given the tool's complexity, the description is complete: it covers input modes, resolution behavior, return-field semantics, measurement pitfalls, and exclusions. The output schema exists, so the lengthy field list in the description is a bonus rather than a necessity, and nothing an agent needs to invoke 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 schema descriptions are already good, but the tool description adds meaning beyond them: accepted aliases (iso/region), live EIA balancing-authority examples, market slug examples, the PJM-DOM special zone, and the explicit note that 'market' is not an alias for a grid code. This materially improves correct parameter selection.

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 deliverable — a grid-headroom and interconnection-queue brief for one ISO — and pairs it with a natural-language trigger question and a concrete example. It explicitly differentiates this tool from compare_isos and get_grid_scoreboard, which is exactly the kind of sibling discrimination an agent needs.

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

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

The description tells the agent when to use it (capacity and time-to-power for one ISO) and when not to (comparing 2+ ISOs, global ranking), naming the alternatives. It also explains edge cases like market-name resolution and balancing-authority behavior, leaving little 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?

The description discloses critical behavioral traits beyond the readOnlyHInt: non-uniform freshness, mix_age_hours routinely 18-24h old, separate demand/mix clocks, Brazil's missing gas share, and partial_grids for AUS/SG. It tells the agent to read mix_age_hours before narrating a row as current, adding substantial safety value.

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

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

The description is long and dense, but every sentence carries needed caveat or context. It front-loads the core purpose and the 'freshness is not uniform' warning early. It is not concise in word count, but it earns its length given the complexity.

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

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

For a zero-parameter, read-only tool with a rich output, the description covers scope, data sources, ranking method, exclusions, geothermal nuance, freshness semantics, licensing, and example questions. An agent has everything needed to call it and interpret results 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?

There are zero parameters, so the schema has nothing to document. The description compensates by explaining what the output contains (renewable share %, fuel mix, gas share, mix_age, demand_vs_mix_lag), which sets correct expectations despite no output schema properties.

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 clear verb+resource: it fetches a global ranked grid scoreboard. It names all covered regions/operators and explicitly contrasts with siblings ('vs compare_isos (pairwise) or get_grid_data (single ISO)'), so an agent can distinguish it from the many grid-related tools.

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

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

It states specific use cases ('which grid worldwide is greenest, or most gas-reliant, for siting a data center?') and names alternatives: compare_isos for pairwise, get_grid_data for single ISO. It also warns about freshness caveats so an agent knows when to rely on the ranking vs. drill into details.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and idempotentHint=true, so the safety profile is covered. The description adds substantial beyond-annotation context: capacity_type semantics ('load' vs 'gen' vs 'bus_headroom'), the critical warning that 'gen' is NOT available load, the honest-by-construction behavior (distinct_feeders vs geometry_rows_scanned reported separately, sample_complete=false with capacity_floor_mw), and the explicit not-published vs silent-zero behavior. It doesn't detail rate limits or auth, but the annotations plus this behavioral disclosure are strong.

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 information-rich rather than concise, but every sentence earns its place: scope, data provenance, calling modes, critical capacity_type semantics, coverage caveat, example call, and exclusions. It is front-loaded with the core purpose and the most critical warning (check capacity_type before quoting any number). It could be trimmed by removing the enumerated utility list, but that list serves a credibility and coverage-clarification function. Slightly long, but structured for scanning.

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

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

Given the tool's complexity (three calling modes, capacity_type distinctions, geographic carve-outs, output-schema semantics), the description covers everything an agent needs to invoke it correctly and interpret results: how to call each mode, what capacity_type means, what the output splits include, how completeness flags work, what geographic gaps exist, what not-published looks like, and what sibling tools to use instead. The output schema exists, so not restating return fields is appropriate.

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 11 parameters well, including aliases (lng/lon, latitude/longitude, market/utility), radius_km bounds, and capacity_type restrictions. The description adds value beyond the schema by explaining the meaning of the three capacity_type values in the context of siting ('gen' is export capacity, NOT available load), clarifying that NO ARGS returns the coverage list, and giving a concrete example parameter combination. It doesn't restate param mechanics but adds the interpretive layer that matters for correct invocation.

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

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

The description clearly identifies the tool as retrieving utility-published feeder hosting capacity in MW for a named distribution feeder, with specific data sources and geographic scope. It distinguishes this from proximity proxies and names the exact three calling modes (lat+lon with radius, utility/market, no args). This differentiates it from sibling tools like get_grid_intelligence, get_interconnection_queue, and get_retirement_headroom.

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

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

The description provides explicit when-to-use guidance with example calls ('Try: get_hosting_capacity utility="Ameren Illinois" capacity_type=load min_mw=5') and explicit when-not-to-use guidance naming exact alternatives: 'Do NOT use for transmission-substation proximity or time-to-power (use get_grid_intelligence), the ISO interconnection queue (use get_interconnection_queue / get_refined_queue), or retiring-plant headroom (use get_retirement_headroom).' This is optimal usage differentiation.

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, the description discloses that results are raw assets joined to HIFLD/EIA, that substations include count and max voltage_kv, that transmission is a >69 kV path overlay, and that power plants include operating and planned status. This gives an agent an accurate behavioral model without contradicting the annotations.

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

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

The description is front-loaded with the resource and layer list, then gives return details, an example, and an explicit exclusion. Each sentence earns its place; the only minor redundancy is 'nearby infrastructure' vs 'raw nearby assets', which does not hurt clarity.

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

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

For a read-only lookup tool with an output schema and fully documented parameters, the description is complete: it covers what is returned, the data source, the supported questions, an example call, and when not to use the tool. Nothing an agent needs to select and 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 description coverage is 100%, so the schema already documents all nine parameters. The description adds a usage example and notes radius_km is configurable, but it does not add significant meaning beyond the schema's own per-parameter descriptions.

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

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

The description identifies a specific resource — nearby infrastructure around a lat/lon point — and enumerates the exact layers returned: substations, transmission lines, pipelines, and power plants. It also distinguishes itself from analyze_site by explicitly saying it returns raw assets rather than a scored verdict.

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

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

It states the intended use cases with example questions ('what is near this parcel', 'how far is the nearest substation and what voltage') and gives a concrete invocation example. It explicitly warns against using it for a single scored site-suitability verdict and names analyze_site as the correct alternative.

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 readOnly, idempotent, and non-destructive behavior. The description adds genuinely useful behavioral context: the tool aggregates multiple market metrics, returns a single composite score plus components and trend, and is scoped to one market rather than the full metric set. It does not discuss latency or data freshness, but for a read-only index tool this is sufficient.

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

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

The description is front-loaded with the definition and return value, then gives use cases, an example, and exclusions. It is somewhat dense but efficient. A small amount of redundancy exists ('Returns ONE composite health number' repeats the earlier 'Returns...'), and the example call is questionable, but the overall structure is strong.

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

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

The description is largely complete for selection and alternative routing, and the presence of an output schema covers return-shape details. However, the invocation guidance is contradictory: the schema accepts no parameters while the description implies a market parameter, leaving an agent without a reliable way to target a specific market. That gap prevents the description from being fully complete.

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

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

The input schema defines zero properties, yet the description tells the agent to try 'get_intelligence_index market=northern-virginia', introducing a market argument that is not represented in the schema. This is misleading and could cause an agent to make an invalid invocation. It conveys that a market name is conceptually relevant, but the added semantics are not backed by 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?

Clearly defines a specific verb and resource: a real-time composite market health score (0-100). It distinguishes itself from siblings by explicitly saying it returns ONE composite health number and naming get_market_intel and rank_markets as alternatives, so an agent can disambiguate it from the large sibling set.

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

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

Provides explicit use cases ('is this market healthy', 'how does Northern Virginia look overall right now') and explicit when-not-to-use guidance with named alternatives ('use get_market_intel', 'use rank_markets'). It even includes an example call. The main flaw is that the example references a parameter not present in the schema, but the when-to-use guidance itself is exemplary.

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

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

Annotations already mark the call read-only and idempotent, and the description adds valuable behavioral details beyond them: the 'projects' field changes shape ('ARRAY per-project rows' vs 'SUMMARY OBJECT'), and ERCOT's data_center_gw is non-null only for ERCOT. This gives the agent important runtime expectations without contradiction.

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

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

The description is long but every sentence carries operational information: purpose, sources, shape-shifting warning, use cases, and exclusions. It is front-loaded with the core purpose and uses a highlighted note for the critical shape change. Some promotional language ('headline large-load figure') adds slight noise but does not undermine clarity.

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

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

For an ISO-queue snapshot tool with one optional parameter and an output schema available, the description covers all necessary context: data sources, regional coverage, return-shape caveat, and when to avoid. Nothing essential for correct selection and invocation 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 parameter description already explains omission behavior. The tool description adds value by clarifying the shape-changing impact of including or omitting iso ('with iso= it is an ARRAY... with iso omitted it is the SUMMARY OBJECT'), which is not in the schema itself. This is a meaningful param-related behavioral detail.

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 and resource: 'ISO interconnection queue snapshot' with clear scope ('total queued GENERATION capacity per ISO'). It also differentiates from siblings by explicitly naming alternatives like get_grid_intelligence and grid_transition_radar, so an agent can select this tool confidently.

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 use cases: 'Use for queue-depth site-selection and AI/data-center-load saturation intel' and explicit exclusions: 'Do NOT use for a single-site time-to-power read (use get_grid_intelligence) or forward-looking emergence (use grid_transition_radar).' This is exemplary when-to-use vs alternatives guidance.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description discloses the token-budgeted greedy-fill behavior, per-section token counts, as_of timestamps, citation URLs, and omission behavior. It gives the agent a clear mental model of how results are produced and limited.

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

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

The description is long but densely structured and front-loaded with the core trigger. Each section — contents, example, params, return shape, exclusions, citation — serves a distinct purpose, though it does repeat some schema details that 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?

Given the tool's complexity and the large sibling set, the description is exceptionally complete: it covers content, budget semantics, output shape via the output schema, exclusion paths, and even citation expectations. No material decision-relevant gap remains.

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

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

The input schema already documents both parameters fully, including the ISO list, the 200-8000 range, and the default of 4000. The description adds a useful example but mostly restates the schema, so the 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?

The description opens with a clear trigger — 'Use when an agent needs a WHOLE-grid briefing' — and specifies the full contents of the returned context pack. It also distinguishes the tool from siblings like get_grid_data, get_grid_intelligence, and compare_isos by naming what this tool is not for.

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

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

The description explicitly states when to use the tool, when NOT to use it, and names the exact alternative tools for each excluded case. It also provides a concrete example invocation, making the routing decision unambiguous.

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

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

The description goes well beyond the readOnly/idempotent/destructive annotations by explaining the greedy priority-order filling under a max_tokens budget, per-section token counts and as_of timestamps, citable URLs, and the omitted field in the return object. It even discloses that the outlook is Claude-written, which is useful context an agent could not infer from annotations.

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

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

The description is long but information-dense, with purpose front-loaded, then an example, parameter semantics, return shape, and explicit exclusions. Every sentence adds value, though the density could be slightly streamlined for faster scanning.

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

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

The description covers what the tool returns, how the budget works, where valid slugs come from, which sibling tools to use instead, and the required citation string. Given the tool's complexity and the rich output schema information embedded in the description, nothing critical is missing for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds real meaning beyond the schema: it explains that market is a slug sourced from rank_markets, that max_tokens controls greedy section filling in priority order, and provides a concrete invocation example. This is meaningful enrichment rather than mere duplication.

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 and resource: returns a whole-market briefing pack for a data-center market, enumerating the exact sections included and the token-budgeting behavior. It actively distinguishes itself from siblings by naming get_market_dcpi_rank, get_market_intel, and rank_markets as alternatives for narrower or different needs.

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 opens with 'Use when an agent needs a WHOLE-market briefing' and then gives explicit negative guidance: do not use for a single metric, raw structured metrics, or cross-market ranking, with specific sibling tools named for each case. This gives an agent unambiguous routing criteria.

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