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?

Beyond the annotations (which only mark it as a non-read-only, non-destructive, non-idempotent mutation), the description discloses the required identity chain (claim_free_key then bind_email or OAuth), the once-per-terms-version semantics, the 'nothing opens/sent' gating on accept_terms, and the side effect of recording in DC Hub's lead register.

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

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

Front-loaded with the gating condition and always-true trigger, and most sentences carry load. The parenthetical identity chain and repeated warnings make it slightly longer than needed, but there is little pure waste.

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

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

An output schema exists, yet the description still briefly notes the return (accepted plus terms version). Combined with prerequisites, alternatives, and trigger conditions, an agent has everything needed to call this correctly without further lookup.

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

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

Schema description coverage is 100%, so both parameters are already fully documented in the schema, including the exactly-true requirement and the omit-to-use-published-version default. The description restates these rather than adding new meaning, so the baseline 3 applies.

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

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

States a specific verb (accept) and resource (capacity terms) and immediately delineates scope: it records acceptance so Capacity Source listing details open. It explicitly differentiates from siblings by naming request_capacity_intro and source_capacity as different operations.

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

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

Gives an explicit precondition trigger (call when source_capacity returns a listing locked with access.reason terms_acceptance_required), an explicit prohibition ('never on your own judgement'), and two named alternatives for adjacent needs. Nothing about when/when-not is left to inference.

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

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

Annotations already cover 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?

Annotations already mark readOnly/idempotent/non-destructive, and the description adds substantial context: free vs paid tier behavior, location resolving to a market centroid rather than the named parcel, candidate_id overriding lat/lon, capacity_mw deliberately not affecting overall_score, and the MPP payment-challenge flow. There is 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 the usage condition and example, but it is very long and repeats parameter ranges and return-structure details that the input/output schemas already provide. Most sentences add useful caveats, but it could be tightened by relying more on the schema and presenting the extra guidance as compact bullets.

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 14-parameter tool with multiple mutually-exclusive location modes, free/paid tiers, and a payment flow, the description covers everything an agent needs: how to specify the site, what the score means, what the free tier returns, how payment works, and which sibling tools handle related but different tasks. 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?

Even with 100% schema coverage, the description adds conditional requiredness (lat/lon unless candidate_id or location), explains that location is a market-level read and not an alias for coordinates, clarifies candidate_id precedence over lat/lon, and describes the capacity_mw side-effect block. This is substantial meaning beyond the raw schema.

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

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

The description clearly states a specific verb+resource ('full multi-factor data-center suitability read') for a single site, and explicitly positions it as the single-site step of site selection. It names what it is not (compare_sites, find_alternatives) and distinguishes it from specialized risk/tax tools, so an agent can tell it apart 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?

It opens with an explicit 'Use when' condition and provides a concrete example call. It also gives clear exclusions ('Do NOT use to compare 2+ sites' with named alternatives) and routes dedicated water/disaster/climate/tax needs to specific sibling tools, leaving no ambiguity about when to invoke it.

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

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?

Annotations only show destructiveHint=false and no readOnly, so the description carries a heavy burden for behavior. It discloses critical behaviors: re-minting resets daily allowance and orphans history, keys don't persist on hosted clients, OAuth is the only durable path, no agent-only path to OAuth, 401 challenge behavior varies by client. These are real behavioral traits beyond annotations. Deducting one point because the massive length and dense metrics may obscure the core behavior for a hurried agent, but the disclosure itself is thorough.

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?

This is a very long wall of text (approx. 800+ words) for a simple 2-param tool. The key actionable information (mint key, save it, use X-API-Key) is buried under extensive caveats about OAuth durability, cohort statistics, measurements, and client-specific behaviors. While the content is genuinely useful, it is not scan-friendly for an agent; front-loading the core 'do this' would make it stronger. Every section is informative but could be trimmed by 50% without losing safety value.

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

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

Given the tool's role as a funnel entry point with many edge cases (hosted vs header-capable clients, OAuth availability, key persistence, daily limits), the description covers all decision paths an agent needs: when to mint, when to use alternatives, what to do with the output, and what to avoid. The output schema is provided, so return values are covered. The only gap is that some metrics may be dated, but the description explicitly timestamps them, which is honest.

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 both params have schema descriptions. The tool description adds semantic context: email makes key recoverable across sessions (durable anchor for hosted clients), client_name is for attribution. This goes beyond the schema's minimal descriptions (e.g., email schema only says 'optional owner email'). The description also clarifies email is only to use if human explicitly gave it, which is a practical safety note. Worth a 4 because it enriches both params meaningfully.

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

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

The description clearly states the tool mints a free DC Hub dev key, and distinguishes it from alternatives like recover_my_key and unlock_more_data. It specifies the exact trigger condition (hitting a paywall or partial preview) and the API usage pattern (set as X-API-Key header), making the purpose unambiguous.

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

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

The description provides extensive when-to-use and when-not-to-use guidance: mint only when higher free-tier allowance is needed, not for keyless answers, not if OAuth durable identity is available, not if already holding a key. It explicitly names alternatives (recover_my_key, unlock_more_data, durable identity via OAuth) and covers client-specific routing (paste-a-URL connectors should use connect_url). No gaps.

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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds meaningful context beyond that: it runs analyze_site on each parcel, ranks by overall_score, and explicitly states capacity_mw does NOT move overall_score—so the winner is based on location suitability, not requested load. It also discloses the paid/Pro tier behavior. While it doesn't mention rate limits or further confidentiality, with annotations in place this is strong added 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 dense but front-loaded with the primary use case, includes a concrete example, and then systematically explains parameters and output shape. Every sentence serves a purpose—usage, exclusions, example, param semantics, output, and payment tier. Nothing is fluff, and the structure flows logically.

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 (5 params, nested output schema, paid tier, sibling alternatives), the description is thorough. It covers when to use it, how parameters behave, what the output looks like (including pointing to analyze_site's shape), and the free vs. paid distinction. With an output schema present, it need not repeat return values, but it provides enough context for correct invocation without requiring external knowledge.

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

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

Schema description coverage is 100%, so all five parameters are already documented. The description goes further: it explains the locations format as semicolon-separated lat,lon pairs, clarifies capacity_mw semantics (forwarded but not score-influencing), and notes the nested capacity_context behavior. It also mentions the output schema structure for sites and winner, though the schema itself already covers that. This exceeds the baseline 3 for full coverage by adding loaning nuance.

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 use case (comparing 2-4 candidate parcels), a clear action (side-by-side winner picker), and an example. It explicitly distinguishes itself from analyze_site (single site) and rank_markets (market ranking), giving an agent immediate differentiation.

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

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

The description opens with 'Use when a user has narrowed data center site selection to 2-4 candidate parcels' and closes with explicit exclusion: 'Do NOT use for a single site (use analyze_site) or to rank entire markets (use rank_markets).' This is textbook usage guidance with both when and when-not plus named alternatives.

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

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

Annotations already declare readOnlyHint, 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?

Annotations already mark this as destructive, so the description adds useful context beyond that: the watch cannot be recovered, deliveries stop, and a key is required. This gives the agent a clear picture of the irreversible side effects 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 compact and well-structured: core action first, then source of the ID, then applicable user intent, then a clear prohibition. Every sentence carries useful information and there is no clutter.

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 one-parameter destructive tool with a fully documented schema and annotations, the description is complete: it covers the effect, irreversibility, authorization requirement, ID provenance, and the main misuse case. Nothing critical is missing for an agent to invoke it correctly.

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

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

The input schema already fully documents the single intent_id parameter, including noting that it comes from list_standing_intents or register. The description reinforces this but does not meaningfully add new parameter semantics beyond what the schema already provides.

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

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

The description clearly states a specific verb and resource: 'Permanently retire a registered standing intent (webhook watch) by intent_id' and explicitly says it removes the watch. It also anchors the tool's purpose with 'Answers "stop watching this"', making the intent unmistakable and easy to distinguish from listing or registering intents.

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 when to use this tool (when the user wants to stop watching something), how to obtain the required intent_id (from list_standing_intents or the register response), and when not to use it ('Do NOT use to pause temporarily; there is no pause, this removes the watch'). This provides clear decision rules.

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 mark readOnlyHint=true and idempotentHint=true, so the description correctly reflects a non-destructive search. It adds substantial behavioral context: candidates are search areas, not parcels or listings (and why), constraint_coverage semantics (unfiltered with applied:false on layer errors), fiber_distance as chord not polyline, state-grain hazard/moratorium, geography requirement yielding a 400 error, and free-tier coordinate coarsening. 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 (several paragraphs) but well-structured with clear sections (FRONT DOOR CHECK, WHAT A CANDIDATE IS NOT, READ constraint_coverage BEFORE...). It front-loads the most critical routing decision (execute_plan vs find_sites) and then adds necessary caveats. Every sentence adds value, though it could be tightened; the repeated 'where should I even be looking?' appears three times. Still, it earns a 4 for effective structure.

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 (13 params, many siblings, output schema exists), the description is remarkably complete. It covers usage, exclusions, parameter semantics, error handling (geography_required), free-tier limitations, and provides examples. It also mentions the next_calls handoff and that output schema exists, so the agent knows the return structure is defined. Nothing essential is missing for a correct call.

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?

Though the schema covers 100% of parameters, the description enriches meaning: min_voltage_kv default and thresholds (230+ for hyperscale, 500 for largest), cluster_km collapse behavior, max_gas_km applied only if layer answers, max_fiber_km chord approximation, exclude_moratorium state grain, radius_km default and clamp, and alias equivalences (lng/latitude/longitude). It also provides two concrete call examples that demonstrate parameter combinations.

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

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

The description states a specific verb-resource pair ('find sites' = discover candidate search areas) and immediately differentiates it from siblings: it is 'the first step of data center site selection' answering 'where should I even be looking?'. It explicitly contrasts with analyze_site, rank_sites, and find_alternatives, so an agent can distinguish it without opening schemas.

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

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

The description gives explicit when-to-use and when-not-to-use guidance. It says to call execute_plan for multi-capability questions, then enumerates the inverse query and lists 'Do NOT use to score a site you already have (analyze_site), to rank candidates you already enriched (rank_sites), to find similar FACILITIES to a known one (find_alternatives), or for interconnection-queue survivors (get_refined_queue)'. This is exhaustive and unambiguous.

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

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

Annotations already 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, so the safety profile is known. The description adds valuable behavior: returns a specific object shape, requires attribution to DC Hub (CC-BY-4.0), and clarifies the quote behavior. It doesn't describe rate limits or latency, but for a read-only, idempotent tool with an output schema, it covers the key behavioral expectations 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 dense and front-loaded with the most critical routing decision ('FRONT DOOR CHECK'). Every clause earns its place—the example, the param pointer, the return fields, the attribution requirement. It is longer than ideal, but it earns its length with high information density. Slight redundancy with the schema (enumerating ISOs, params) is acceptable because it reinforces routing.

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

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

For a multi-purpose tool with 5 params (some payment-related) and a broad sibling set, this description is exceptionally complete. It covers when to use, when not to use, what data is returned, an example invocation, required parameter handling (iso), attribution, and the payment flow for autonomous agents. The output schema exists, so return values need no further documentation. Nothing an agent needs to decide between this and a sibling 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 fully documents parameter meanings. The description adds critical selection semantics: it shows via example that "What is the retail power price and gas price in ERCOT today?" maps to iso=ERCOT, and it emphasizes that iso is the required argument for the primary use case. The description also clarifies the mpp_* parameters contextually as part of the autonomous payment flow, though the schema already covers them well. The baseline of 3 is exceeded because the description gives the 'iso required' usage pattern that is not obvious from the schema (which shows 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 states a specific verb and resource: get today's energy pricing for 7 US ISOs, listing exact data fields (retail rate, wholesale/LMP, gas, grid flag). It clearly distinguishes from siblings by explicitly naming what it is NOT for (fuel mix, headroom, gas-to-grid economics) and routes to alternative tools. This is a model of sibling differentiation.

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

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

Explicitly says when to use this tool (simple single-ISO price question) and when NOT to use it (when price is one factor in siting/market comparison, or for fuel mix, headroom, gas economics). It names the alternative tools (execute_plan, get_grid_data, get_grid_intelligence, get_gas_economics) with clear conditions. The 'FRONT DOOR CHECK' framing gives an agent a decision tree.

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 this is read-only, idempotent, and non-destructive. The description adds the key behavioral nuance that exactly one facility is returned and that nearby peers are bundled into the response, plus a clear exclusion of bulk listing. 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 front-loaded with the core scope, then gives field detail, example calls, and an explicit boundary warning. Each sentence earns its place, and the final 'use search_facilities' note is concise and actionable.

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 read-only annotations, 100% schema description coverage, and the presence of an output schema, the description is complete. It covers what the tool does, how to invoke it with realistic examples, what it returns, and when not to use it.

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

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

The schema covers all parameters with descriptions, so the baseline is 3. The description adds value with concrete example identifiers (id=equinix-dc1-ashburn, slug=digital-realty-iad8) and clarifies that lookups can be done by id, slug, or name, which helps an agent map real-world tokens to the schema fields.

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

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

The description clearly states the tool retrieves full metadata for one facility and enumerates the returned fields (name, operator, address, power, cooling, fiber, etc.). It explicitly distinguishes this from search_facilities by saying it returns ONE facility and should not be used to search or list many facilities.

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

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

The description provides direct usage context: it answers specific questions like 'who operates this data center' and 'how many fiber carriers are in that building'. It also gives explicit negative guidance ('do NOT use to search or list many facilities') and names the alternative tool, 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, so the safety profile is covered. The description adds useful behavioral context beyond annotations: data comes via EIA hourly RTO, is 'raw real-time telemetry', and is scoped to one ISO per call. This helps an agent set expectations about freshness, granularity, and scope.

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

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

Three sentences, front-loaded with purpose, then an iso example, then dense exclusion/alternative guidance. Slight redundancy exists ('real-time' appears twice and 'one ISO' repeats a point), but every sentence contributes meaningful routing or scoping information.

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

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

For a read-only data-fetching tool with an output schema and safety annotations, the description covers the key invocation facts: ISO scope, data content, one-ISO limitation, and alternatives. The main residual gap is that it does not explain the 'metric' parameter or the optional payment credential, but those are documented in the schema. Overall, the description is sufficient for correct selection and invocation in most cases.

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 the iso example and mentions the data fields (fuel mix, demand, 24h demand curve), which partially hints at metric options, but it does not explicitly map those to the 'metric' parameter or clarify its accepted values. The schema carries most of the parameter-level 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?

States a specific resource ('real-time electricity grid data for the 7 US ISOs') and the concrete data content (fuel mix, demand, 24h demand curve). It also names the exact ISO list and explicitly contrasts itself with sibling tools (get_grid_intelligence, get_energy_prices, get_grid_scoreboard), so the agent can disambiguate it without opening schemas.

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

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

Provides explicit when-to-use guidance ('Pass iso=PJM') and clear when-not-to-use conditions with named alternatives: not for power-availability/time-to-power/interconnection-queue analysis (use get_grid_intelligence), not for retail/gas pricing detail (use get_energy_prices), and not for non-US grids (use get_grid_scoreboard). This is exemplary routing guidance.

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

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

Annotations already mark the tool read-only, idempotent, and non-destructive, and the description adds substantial behavior beyond that: resolved_from behavior for market inputs, balancing-authority vs ISO data granularity, and a critical warning that time-to-power and queue-wait are different measurements. No contradiction with annotations exists.

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

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

The description is front-loaded with the primary use case and every major clause carries useful routing or behavioral information. However, it is quite long, and some parts—such as the enumerated return field list and the long list of balancing-authority examples—are likely redundant with the output schema and could be trimmed.

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

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

The description covers the triggering question, parameter semantics, output behavior, measurement pitfalls, and explicit sibling exclusions. Given that an output schema exists and annotations already establish the safety profile, 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?

Although schema coverage is 100%, the description adds real meaning: it enumerates valid region_id categories, clarifies accepted aliases, explains how market names resolve to ISOs, and documents the special balancing-authority behavior. This goes well beyond the schema's bare 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 opens with a concrete trigger question and a clear verb-object pair: 'grid-headroom + interconnection-queue brief for one ISO.' It further distinguishes itself from siblings by naming compare_isos and get_grid_scoreboard as the correct tools for other intents.

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

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

The description explicitly says 'Use when a user asks...' and provides a worked example with a real output shape. It also explicitly states what not to use it for and routes to the correct alternatives, 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?

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?

Annotations already establish readOnly, idempotent, non-destructive behavior; description adds rich context: source coverage (EIA vs ERCOT TPIT), row-level source_url/license, summary counts, as_of dates, delisted behavior, and meaning of new_since with backfill exclusion. This materially exceeds annotation coverage.

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

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

Long but densely functional: front-loaded use case, concrete examples, coverage details, filtering semantics, and exclusions. Every sentence carries routing or behavioral information; no filler. The length is justified by the tool's ten-parameter 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 multi-source, ten-parameter tool, the description fully covers scope, field contents, statuses, filters, output summary behavior, provenance, and exclusions. An output schema exists, so return-value documentation is not required. 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?

Schema already documents all parameters at 100% coverage, so baseline is 3. The description adds meaning beyond schema by explaining filtering semantics (e.g., state matching for gas, transmission TX-only, new_since backfill exclusion, in-service window behavior, include_delisted). It omits limit in prose, but schema covers it.

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

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

States a specific verb and resource: answering questions about planned/proposed/approved/under-construction gas pipeline and transmission projects. Clearly distinguishes from the existing network and names sibling tools (get_power_pipeline, get_infrastructure, get_grid_intelligence, get_pipeline) it is not.

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

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

Opens with 'Use when...' and gives concrete examples. Explicitly lists when NOT to use the tool and names the correct alternatives for power generation, existing infrastructure, and data-center construction. No ambiguity remains about routing.

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

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

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.