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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description doesn't need to restate safety. It adds useful behavior beyond annotations: the refresh schedule ('Refreshed Fridays 14:00 UTC'), a data-completeness caveat ('where facility data carries them'), and the composite-score composition. A small gap is that it doesn't explain how 'top' is ranked, but this is minor for a read-only index.

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 earns its place: purpose, return fields, freshness, use cases, exclusions. It front-loads the ranking action before drifting into field lists and caveats, and it uses dashes and short clauses to keep it scannable.

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

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

With an output schema present, return-value documentation is handled structurally. The description covers the tool's purpose, output highlights, freshness, data caveats, intended uses, and exclusions, so an agent has everything it needs to 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?

Both parameters have 100% schema description coverage, so the baseline applies. The description repeats the 30/60/90 horizon but adds no new semantics for limit or horizon beyond what the schema's descriptions already provide.

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 action ('ranks data center markets') and a precise scope (where 100MW of AI training capacity can land in 30/60/90 days). It also enumerates the returned fields and distinguishes itself from rank_markets and grid_transition_radar, 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?

It states explicit use cases (AI capex planning, GPU cluster siting, hyperscaler deal forecasting) and gives direct exclusions with sibling alternatives: 'Do NOT use for a general best-markets ranking (use rank_markets) or forward grid-emergence (use grid_transition_radar)'. This is textbook when/when-not guidance.

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

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

The description discloses read-only behavior (consistent with readOnlyHint), algorithmic details (representative_point uses centroid of largest member, never multi-part geometric center), and error semantics (honest 404). It adds valuable context beyond annotations, fully transparent about what the tool does and does not do.

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

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

The description is dense but well-organized, with a single paragraph using semicolons to separate distinct ideas. It front-loads the core function and then expands on coverage, return fields, and usage. While slightly long, it avoids redundancy and each clause adds necessary detail, earning a high but not 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?

The description is fully self-contained: it explains what the tool does, the input modes, coverage, error behavior, return fields, how to chain with other tools (site_evaluation_handoff), and when to use alternatives. It leaves no significant gaps for an agent to correctly invoke 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 input schema already provides rich descriptions for all parameters (coverage 100%), including aliases, geometry format, and optional capacity_mw. The tool description reiterates these points but does not add significant new meaning beyond the schema. It meets the baseline for high schema coverage but does not enhance parameter understanding further.

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 performs a structured read of a parcel boundary, accepts either a GeoJSON polygon or lat/lon coordinates, and explicitly distinguishes it from sibling tools (analyze_site, get_refined_queue) by naming use cases. It is precise and unambiguous.

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

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

The description provides explicit when-to-use guidance: 'use when you HAVE a boundary or a point on a specific parcel and want it anchored + sized', and contrasts with alternatives. It also discloses coverage limitations ('rolling out by data-center market — Loudoun County VA first') and error behavior ('returns an honest 404'), leaving no ambiguity about applicability.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description goes far beyond this by revealing important behaviors: location resolves to a published centroid, not the parcel; candidate_id ignores lat/lon and fails closed when expired; capacity_mw deliberately does not move overall_score; and the free/paid tier split is disclosed. No contradiction exists.

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

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

The description is long, but the length is justified by the tool's complexity: 14 parameters, multiple input modes, tiered returns, and sibling differentiation. It is front-loaded with the core use case and example, and every sentence adds necessary operational detail. Slightly over-long for a quick scan, but appropriately structured.

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

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

Given the complex input modes, output shape, free versus paid behavior, and many sibling tools, the description covers everything an agent needs: it explains what each parameter does, what the return contains in both tiers, what to use instead, and what caveats apply. Nothing essential is missing.

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

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

Schema coverage is 100%, but the description adds real semantics beyond the schema: the mutual exclusivity of lat/lon vs candidate_id vs location, the resolution quirk that 'Ashburn, VA' won't resolve, the meaning of capacity_context, and the default behavior of include_* booleans. This is high-value parameter explanation, not repetition.

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

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

The description opens with a precise use case — one specific lat/lon for a full multi-factor data-center suitability read — and then distinguishes from siblings like compare_sites and find_alternatives. It names the resource, the action (analyze site), and the scenario clearly.

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 versus alternatives: use it for ONE site with a full suitability read; do NOT use it to compare 2+ sites (use compare_sites) or to find matching sites (use find_alternatives). It also routes to dedicated tools for water/disaster/climate/tax reads. This is exemplary 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?

Far beyond the annotations (readOnlyHint=false, destructiveHint=false), the description discloses the functional effects (key recoverability, free tier restored at 50 calls/day), the failure mode ('If the email can't be accepted, the key keeps working'), the negative consequence of fake emails (key becomes unrecoverable), the consent constraint on marketing, and even the honest caveat that the durability benefit is UNPROVEN with a 0-of-3 cohort. 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?

Front-loading is strong — the ★ heading and the first sentence deliver the core scope. However, the roughly 400-word description is a dense stream of consciousness mixing cohort evidence, pricing tiers, consent policy, and digest marketing into one paragraph. Most sentences earn their place, but the lack of sectioning hurts scannability for an agent trying to extract the key decision rules quickly.

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 consent implications, failure modes, tier-gating, and 3 parameters, the description covers everything: when to call, prerequisites (human-shared email), effects, failure behavior, consent requirements, and return value ('Returns the unlocked benefits + confirmation'). The output schema exists, so the return format is already structured; nothing an agent needs to invoke correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3. The description adds consequence-level meaning beyond the schema: invented or placeholder emails are rejected server-side and make the key unrecoverable, omitting api_key binds the session-active key, and marketing_opt_in must follow explicit human agreement with an unsubscribe guarantee. This is genuinely additive, though it stops short of specifying email format validation.

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: 'Tie your DC Hub key to your human's email so the key is RECOVERABLE.' It goes further than most by explicitly stating what it does not do ('does NOT make your identity durable') and contrasts itself with the OAuth path, making differentiation from siblings like recover_my_key, claim_free_key, and subscribe_digest immediate without opening their schemas.

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

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

Call conditions are explicit: 'Call this once your human shares their email' and '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 (OAuth sign-in) with the exact condition that selects it (401 WWW-Authenticate challenge), and provides a concrete PAUSE-and-ask script for the tier-gate scenario.

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 provide negative hints (readOnlyHint=false, destructiveHint=false). The description compensates richly: it discloses side effects (re-minting restarts allowance, orphans history), dependencies (OAuth requires human, no agent path), and client limitations (paste-a-URL connectors cannot use the key). It also reveals measured statistics and caveats, going well beyond annotation capabilities.

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 extremely long and repetitive, with multiple sections re-emphasizing the same points (e.g., key survival, client types, statistics). While the bullet-like asterisks provide some structure, the core action is not front-loaded, and many sentences are verbose. A tighter description could convey the same guidance in half the 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?

Given the tool's complexity—multiple client types, conflicting advice, return values, and workflow—the description is exceptionally complete. It explains the return object (though output schema exists), how to use the key, what to do after minting, and how to handle edge cases. No critical operational aspect is left unaddressed.

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

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

Schema coverage is 100%, so both parameters are described in the schema. The description adds meaningful semantics: the email parameter is explained as making the key recoverable across sessions and the durable anchor for hosted web clients, while client_name is for attribution. This goes beyond the simple schema descriptions and clarifies the optional email's value.

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

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

The description eventually states the core action 'Mint a FREE DC Hub dev key instantly — no email, no browser, ONE call' and distinguishes it from siblings like recover_my_key and unlock_more_data. However, the purpose is buried after a long preamble about alternatives, so it is not front-loaded. Still, it is specific about verb, resource, and 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 gives explicit when-to-use ('Call this the moment you hit a paywall or a partial preview'), when-not-to ('Do NOT call this again if you already hold a key'), and names alternatives (recover_my_key, unlock_more_data, DURABLE IDENTITY). It also explains client-specific applicability (challenged vs. not challenged), leaving no ambiguity about when this tool is appropriate.

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

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

Beyond the readOnlyHint=true and destructiveHint=false annotations (already signaling a non-destructive query), the description discloses key assumptions: the 1.4 route_factor, the assurance that floors are physics-based while estimates are inferred, the fail-closed behavior on metadata ('each resolves to its FROZEN mint coordinates'), and the request to always quote confidence_v when relaying results. It also explicitly includes the idempotentHint behavior of dropping unknown candidates and declaring them, which is a critical side-effect disclosure.

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

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

The description is dense but efficient. Every sentence carries informational weight, using advanced organization with headers like 'CANDIDATE CONTRACT' and a clear example block. It front-loads the core value proposition, then details the contract, and concludes with boundaries of scope and alternatives. The structure allows skimming for the use case before the demo JSON block.

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

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

Given the presence of an output schema and 100% input schema coverage, the description doesn't need to repeat their details. It completes the picture by explaining the domain model (dark-fiber screening, confidence tiers), the assumptions behind the physics (route factor, SMF-28 specifics), and the precise conditions under which to apply the results. An agent has all the information needed to invoke this tool and interpret its 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 coverage is 100% and it leans on that. The description adds value by clarifying the relationship between sites and candidate_ids (interchangeable, mixable), the semantics of FROZEN coordinates, and the resolution of cand_... tokens. As a result, it receives a higher score than if it merely duplicated the schema, though it does introduce domain terms (route_factor, confidence_v) without fully defining them, which is a minor gap.

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

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

The description clearly defines the tool as 'physics-bounded latency clustering for 2-8 sites,' explicitly stating it returns clusters, pair-level estimates, and a candidate contract before routing. It is distinguished from siblings like plan_fiber_leadin and get_fiber_readiness, and the core function—clustering sites by latency physics—is unmistakable against its 80+ 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 includes explicit when-to-use guidance ('before any detailed routing'), a clear alternative ('For actual route corridors use plan_fiber_leadin; for single-site connectivity score use get_fiber_readiness'), and even an example invocation. It specifies the exact use case (sync replication, active-active pairs, HPC pods) and what the tool is NOT for ('Do NOT treat this as an engineered latency quote').

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

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

Annotations already cover the read-only and idempotent safety profile. The description adds behavioral nuance beyond annotations by warning that avg_time_to_power_months and avg_queue_wait_months are DIFFERENT measurements and that avg_queue_wait_months is a proxy from live queue depth. This prevents the agent from quoting the wrong metric. It also documents the return shape, though an output schema appears to exist.

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

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

Dense but efficiently structured: trigger condition, example, parameter constraints, return shape, critical measurement caveat, and exclusions each earn their place. The most important information (when to use and what it compares) is front-loaded, and the caveats are clearly highlighted.

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

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

Covers every context an agent needs for correct invocation: the use case, the alternative tools for adjacent scenarios, the exact valid input domain, the return structure, and the subtle measurement distinction. With one required parameter and a highly specified description, nothing essential is missing.

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

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

Schema description coverage is 100%, so the parameter is already documented as a comma-separated list with valid values. The description adds value by repeating the 2-4 max constraint, spelling out the 7 valid ISOs, and giving a concrete example call (compare_isos isos='PJM,ERCOT,CAISO').

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 a side-by-side of 2-4 ISO grids') and enumerates exactly what is compared: fuel mix, demand, renewable/gas share, interconnection-queue depth, time-to-power. It also distinguishes itself from get_grid_scoreboard and get_grid_intelligence, making its scope 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 it ('instead of N sequential get_grid_intelligence calls') and when not to use it ('Do NOT use to rank ALL grids globally (use get_grid_scoreboard) or for the single-ISO deep brief (use get_grid_intelligence)'). The example with PJM, ERCOT, CAISO further ground the intended use case.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, and the description adds valuable behavioral context: it runs analyze_site on each parcel, ranks by overall_score, and crucially notes that capacity_mw does NOT affect overall_score. The free-tier preview vs. paid full result is also disclosed. 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 weight: an example call, param explanations, output shape, exclusions, and payment caveat. It is front-loaded with purpose and usage. While not short, it is appropriately dense for a tool of this 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?

Given the tool's complexity (5 params, output schema, payment flow, and exclusions), the description is remarkably complete. It includes an inline output schema, explains the free vs. paid behavior, clarifies capacity_mw's limited role, and names the sibling alternatives. Nothing needed for correct invocation is missing.

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

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

All 5 params are described in the schema (100% coverage), so the baseline is 3. The description adds critical semantics beyond the schema: the exact format of locations (semicolon-separated lat,lon pairs), the non-impact of capacity_mw on scoring, and the two-step mpp_pay/mpp_credential payment flow. This extra context earns a 4.

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

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

The description states a specific verb (compare) and resource (2-4 candidate parcels) with a clear winner-picker outcome. It explicitly distinguishes from analyze_site (single site) and rank_markets (whole markets), so an agent can immediately tell when this tool is appropriate.

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 ('when a user has narrowed to 2-4 candidate parcels') and when not ('Do NOT use for a single site... or to rank entire markets'), naming the alternatives. The paid-tier distinction is also disclosed, leaving no ambiguity about context.

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?

Even with readOnlyHint/idempotentHint/destructiveHint annotations covering the safety profile, the description adds substantial behavioral detail: progressive disclosure, paid-key gating, default comparables count, escalation levels, and the fact that verdict text is always included. None of this contradicts the annotations.

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

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

The description is dense but organized: purpose and output first, then progressive-disclosure behavior, then use-case framing and an example. It is longer than minimal, yet each clause adds meaningful information for a tool with two parameters and layered output modes.

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, idempotent tool with an output schema and full parameter documentation, the description covers everything needed to select and call it correctly: what it returns, what the verdict/autopsy means, access tiers, comparables behavior, and an example. There is no missing essential context.

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

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

The schema already documents both parameters with 100% coverage, so the baseline is 3. The description adds value by explaining the cost/effort rationale ('keep the default cheap'), the escalation semantics ('escalate only for deals you're drilling into'), and by reinforcing the default limit with an example call. This is above baseline but the schema still carries much of the 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?

The description uses a specific verb-resource pairing: it returns data-center M&A/capex deal flow with the DCPI grid-reality verdict overlaid per market. This clearly distinguishes it from generic siblings like list_transactions or hyperscaler_deals by adding the analytic 'what is the real play' layer.

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 clear context for when to call it ('who is actually buying data centers right now', 'what is the real play behind this deal') and includes a concrete invocation example. It does not explicitly name alternatives to prefer for neighboring questions, so it lacks the when-not-to-use component that would make it a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=false, and destructiveHint=false. The description adds value by detailing what the tool returns (front_door block with execute_plan/get_changes, families with tools) and clarifying it's a navigation layer, not exhaustive. Does not contradict 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 somewhat long but every sentence adds value: purpose, return structure, usage directive, and canonical-source warning. It is front-loaded with the main purpose and well-structured, though slightly verbose for a navigation tool.

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

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

Given the tool has an output schema (not shown) and the description explains the return structure and canonical source, nothing essential is missing. An agent can correctly call this tool and interpret results based on the description alone.

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 the single optional query parameter, which already has a descriptive explanation. The description only reiterates 'optionally filtered by a query,' adding no new semantics beyond what the schema provides. 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 clearly states the tool's purpose: navigate DC Hub's tool catalog by family rather than scanning the whole list. It names the specific families returned and explicitly contrasts with tools/list, making its scope unambiguous.

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

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

The description explicitly instructs to call this tool first when unsure which tool fits a task, then call the chosen tool. It also warns against binding capability maps from here, directing to tools/list as canonical. Clear when and when-not guidance.

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

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

Even though readOnlyHint, idempotentHint, and destructiveHint are already present, the description adds critical behavioral context: it describes quota/free-tier consumption, deterministic no-LLM routing, wave-by-wave execution, angle-bracket hand-off resolution, caps, ~40s budget, not_run statuses, and the plan_execution envelope. This is a transparent explanation of how the orchestration actually behaves.

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

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

The description is long and dense, but it front-loads the core purpose with 'THE FRONT DOOR' and then gives usage, behavioral, cap, output, and citation details. The domain list is broad perhaps too broad, but each section conveys actionable guidance. It is not perfectly concise, but it is structured appropriately for a complex orchestrator.

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 tool has an output schema, so return values are covered, while the description covers orchestration details, step statuses, manual continuation when a step is not run, and how to compose the final answer from executed results and cite the source. The description is complete for an agent to understand what it will get back and what to do with it.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds valuable guidance: it stresses that `intent` must be passed through UNCHANGED, clarifies that `cohort` is experimental and should not go inside the intent string, and maps the caps to actually executed steps. Some of this is already in the schema, but the weight here is sufficient to exceed baseline.

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

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

The description identifies execute_plan as a unified planner for data-center siting, grid and AI-compute infrastructure, and states it is 'THE FRONT DOOR' for multi-step questions. It also distinguishes itself from siblings like plan_query and direct tool calls, so an agent can clearly tell when this is the right entry point.

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 'call this FIRST whenever a question spans more than one' domain, 'Use for multi-step questions when you want the answer path run for you', and instructs to 'use plan_query instead when you only want the plan to run yourself; single-tool questions should call that tool directly.' This is direct, actionable guidance with alternatives and exclusion 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description usefully adds what the operation returns ('full file contents as text — CSV rows or a GeoJSON FeatureCollection...') and the exact fields included (DCPI score, target MW, market, coordinates, notes). It also flags the PRO entitlement gate. Slight deduction for not covering edge-case behavior like empty shortlists or large-result handling.

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 but every element earns its place: trigger phrase, mini-example, param summary, return type, and exclusions. It's a bit of a run-on wall of text—the em-dash stitching of example into a separate clause is awkward—but front-loads the trigger and uses scannable 'Params:' and 'Returns:' labels. A tighter restructure could earn a 5.

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

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

Given an output schema exists (so return-value shape need not be re-explained) and annotations carry the read-only/idempotent/destructive profile, the description covers the key operational needs: when to invoke, what format to request, what comes back, and which siblings NOT to use. Gaps—such as how empty shortlists behave or whether the export is synchronous—are minor given the output schema covers structured return 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?

The XSD: schema covers 100% of the single parameter with a clear description of 'csv' (default) and 'geojson' formats. The description reinforces this and adds a concrete usage example ('export_dataset format=geojson') plus a QGIS use case. This aligns with the baseline-3 expectation when schema already documents parameters well; the description adds a small but not transformative increment.

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+scenario: 'pull their saved DC Hub shortlist OUT of the platform' for offline analysis. It goes further by naming and differentiating from siblings ('Do NOT use to list sites in-chat (use list_saved_sites)...'). An agent can immediately and unambiguously determine this is the bulk-download tool.

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?

Text explicitly states when to use ('Use when a user wants to pull their saved DC Hub shortlist OUT of the platform'), provides a concrete trigger example, and gives clear exclusions with named alternatives (list_saved_sites, save_site). Explicit exclusion of in-chat listing vs. saving directly routes an agent to the correct tool among 100+ 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?

The annotations already cover read-only, non-destructive, and idempotent behavior, so the bar for description-only transparency is lower. The description adds useful behavioral context: the tool returns a citable summary rather than full facility specs and that it is shaped for the OpenAI Deep Research / ChatGPT connector format.

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

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

Two sentences, no filler. The main function and source of the id are front-loaded, followed by the return shape and alternative path. 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?

For a single-parameter read tool with an output schema, this is complete: it states the input source, the output shape, the limitation versus full data, and the preferred alternative. An agent has everything needed to use it correctly.

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

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

The schema already documents the single `id` parameter at 100% coverage and even provides an example. The description reinforces that the id must come from a prior `search` result, but adds no material semantic information beyond the schema, so a baseline 3 is appropriate.

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

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

The description states a specific verb and resource: it fetches a single DC Hub record by id, distinguishes itself by returning a citable public summary rather than full specs, and explicitly contrasts with get_facility. An agent can tell exactly what this tool does without needing to open 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 explicitly says the id should come from a prior `search` result and directs agents wanting full structured specs to get_facility or the URL. This gives clear when-to-use and when-not-to-use guidance, plus a named alternative.

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

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

Annotations already mark this as read-only, idempotent, and non-destructive. The description adds useful behavioral context: it returns ranked alternatives with similarity_score, match_reasons, and key_differences versus the target, and that it discovers candidates from a single seed facility. However, it does not mention the silent-stripping behavior or the absence of a name parameter, which is only disclosed in schema text.

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

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

The description is well-structured and front-loaded with the core use case, example, return shape, and exclusions. It earns most of its sentences, but the inaccurate parameter enumeration adds noise and should be corrected or removed.

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

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

With an output schema and full schema descriptions, the tool is mostly self-sufficient, and the description covers usage and exclusions well. But the param mismatch and omission of match_on/exclude_operator leave an agent with conflicting signals that undermine completeness.

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

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

Schema coverage is 100%, so the baseline is 3, but the description's parameter list actively conflicts with the schema: it says 'facility_id or name' and mentions capacity_mw, while schema explicitly states there is no name param and has no capacity_mw property. It also omits match_on and exclude_operator. This is misleading rather than 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?

The description clearly identifies the operation: finding similar, nearby alternatives to a single facility the user likes. It gives a concrete example and contrasts itself with score_facility/analyze_site and compare_sites, so an agent can tell exactly what this tool is for.

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

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

It states explicit use conditions ('when a user likes ONE specific facility'), provides an example, and gives explicit exclusions with named alternatives ('Do NOT use to score one site... or to compare a known short-list...'). This leaves no ambiguity about when to invoke it.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context beyond those hints: the result is a branded 5-page PDF with a ready-to-open, no-login link valid ~7 days, plus defaults for prepared_by and latency_target. 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?

Though longer than average, every sentence carries selection or invocation information: trigger condition, example call, parameter meanings/defaults, return shape, link expiration, and sibling routing. It is front-loaded with the use condition and closes with the alternative tool.

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

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

For a 10-parameter PDF-generation tool, the description covers the full call path: when to use it, how to construct arguments, what the return envelope contains, and how to handle the result (hand the link to a human). The existence of an output schema lowers the burden for return-value documentation, and the description still summarizes the survey object.

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 meaning beyond the schema by spelling out defaults ('prepared_by ... defaults to DC Hub', 'latency_target ... default = nearest real carrier hotel'), giving ranges (50-500 MW), and calling out required lat/lon, which helps even though the schema's required array is empty.

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 'Use when a user wants a SHAREABLE, branded multi-page Site Analysis PDF for ONE lat/lon' — a specific verb, resource, and scope. It also explicitly contrasts with analyze_site ('For just the numeric suitability score (no PDF), use analyze_site instead'), so an agent can distinguish this tool from its 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?

It provides a clear trigger condition, a concrete worked example command, and an explicit alternative: 'For just the numeric suitability score (no PDF), use analyze_site instead.' It also scopes the tool to ONE lat/lon, aiding routing away from multi-site or cluster tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description goes further by disclosing that the roster is backend-owned and changes, statuses are curated editorial claims rather than live measurements, and the response carries as_of null so 'MCP Active' should not be relayed as a live connection count. This is rich 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 longer than strictly necessary, with some redundancy such as repeating the purpose and including the 'Try: get_agent_registry' hint. However, it is front-loaded with the core purpose and each major warning earns its place by preventing a plausible misuse of the tool.

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

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

Given the tool has no parameters and an output schema is present, the description covers everything needed: purpose, response structure, key status values, caveats about editorial vs measured data, and explicit non-uses. It is complete 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?

There are zero parameters, so there is nothing for the description to clarify at the parameter level. The baseline for zero parameters is 4, and the description appropriately focuses on response semantics instead.

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 defines a curated roster of AI platforms and agent frameworks and explicitly answers the question 'which AI platforms can connect to DC Hub'. It also differentiates itself from telemetry tools by stating it is NOT live per-caller telemetry, and points to get_backup_status for uptime/feed health.

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 usage context: use it as an ecosystem/capability index, and do NOT use it for platform uptime or feed health. It names the alternative tool (get_backup_status) and tells the agent to read the platforms[] array from the response rather than any static list.

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

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

Annotations already mark this as read-only, idempotent, and non-destructive. The description adds valuable behavioral nuance beyond annotations, especially that an 'unknown' feed has not been measured and is not equivalent to healthy, plus the exact scope boundary of /api/health/data-freshness.

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 information-dense and front-loaded, with scope first, rollup semantics, and exclusion guidance. The feed list and 'Try: get_backup_status' sentence add minor redundancy but do not seriously hurt usability.

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 no-parameter tool with output schema and safety annotations already present, the description completes the picture: it explains what each row means, what the rollup contains, how to interpret 'unknown', and how to route to get_changes when needed. 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?

There are zero parameters, and schema description coverage is 100%, so there is no parameter confusion. The description correctly focuses on result semantics rather than inventing parameter guidance. The baseline for a zero-parameter tool is 4.

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

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

Description states a specific resource (DC Hub ingest layer) and action (per-feed freshness health check), enumerates feeds, and provides a summary rollup. It distinguishes itself from siblings by explicitly excluding dataset-level freshness, so an agent can select it accurately.

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?

Contains explicit guidance: 'Answers are any of your sources stale right now' and directly names the alternative: 'Do NOT use for the freshness of one dataset (use get_changes); this is ingest health, not content.' This gives clear when-to-use and when-not-to-use conditions.

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 detailing the conditional portfolio block for keyed callers, the per-site verdict flips, excess-power deltas, alerts fired, and new facilities near each site. It also discloses the important sync behavior of caching generated_at and passing it back, which is non-obvious and valuable for correct invocation.

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: purpose, return contents, conditional behavior, parameter guidance, example query, and answer-form matching. It is front-loaded with the core concept and avoids filler while covering a complex tool efficiently.

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 of moderate complexity with an output schema, the description is remarkably complete. It covers the sync mechanism, the exact categories of returned changes, the conditional portfolio block for saved-site callers, the generated_at caching pattern, and the practical 'what changed' use cases. No critical operational detail appears missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful usage detail beyond the schema by showing actual invocation patterns ('since=7d'), explaining the default of 24h, and tying the since parameter to the cached generated_at field. This elevates it to a 4.

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

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

The description opens with a specific, action-oriented definition: 'Incremental sync — what changed in DC Hub since a timestamp', clearly identifying the resource (DC Hub changes) and the operation (pulling only the delta). This distinguishes it from sibling data-lookup tools like get_news or get_facility by focusing on what changed over time rather than current state.

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 frames when to use it: 'so an agent pulls only the delta instead of re-fetching everything' and gives natural-language triggers like 'what changed since I last looked'. It does not name specific alternative tools or exclusions, but the context strongly implies the intended use case, meriting a 4 rather than a 5.

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

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

Annotations (readOnlyHint, idempotent, non-destructive) already establish safety; the description then goes well beyond: it discloses sourcing guarantees ('grounded STRICTLY in USGS ASCE 7 + NOAA climate normals via ACIS'), the 'never estimated' missing-data policy, radius fallback semantics ('unavailable_exceeds_radius'), and geographic coverage limits. It even documents conditional nulls ('extreme_max_wet_bulb_f (null if source lacks it)'). No annotation contradiction.

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

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

Zero fluff—every clause earns its place, and the first sentence front-loads the core trigger with strong scoping. The trade-off is density: a multi-line inline return-shape blob sits in the middle, which is hard to parse on sight and could plausibly live in the (available) output schema or be trimmed to key-name snippets. Despite that, the overall structure is tight for a description covering so many critical behaviors.

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 this complex (6 params, radius-based geography, multi-source data, geographic/COI/coverage constraints), this description covers the decision surface: when, what, where, data provenance, edge cases, and what the response contract looks like. With output schema plus this rich behavioral text, an agent has no unresolved ambiguity in picking or invoking it. The only minor gaps (e.g., explicit wording on non-US climate fallback, exact input validation rules) are minor against the 100% schema coverage and the detailed behavioral notes.

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% (aliases, defaults, and examples all documented), so the schema does the heavy lifting. The description adds meaning by example ('get_climate_intel lat=33.45 lon=-112.07') and by clarifying radius_km's runtime consequence (snap vs available/success vs exceeds-radius). However, it introduces minor friction by calling lat 'required' in prose and noting the 'available'/'unavailable' states in a way that slightly duplicates rather than extends schema info. Net mild value-add 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?

Opens with a specific verb+resource ('seismic + climate intel for a lat/lon') tied to concrete business outcomes ('data-center structural bracing cost' and 'cooling design'). It distinguishes itself from siblings by naming get_disaster_risk and get_composite_site_score as the tools for adjacent needs. An agent facing 80+ siblings could unambiguously confirm this is the USGS/NOAA climate-seismic lookup and route elsewhere for ratings or blended scores.

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

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

Gives explicit when-to-use ('Use when...'), when-not-to-use ('non-US → seismic unavailable', 'beyond it climate returns unavailable_exceeds_radius'), and names two alternative tools with their distinguishing conditions. The one-line preamble preceding the return shape ('the layer that drives...') also clarifies what problem prompts should mention. For the two closest siblings, routing 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 the tool readOnly, idempotent, and non-destructive. The description adds substantial behavioral detail beyond that: it scores only over validated factors, never imputes missing factors, treats water as unavailable only outside basin coverage, and exposes confidence as complete|conditional. 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 information-dense: use case, coverage rules, example, return shape, and sibling routing are all front-loaded and purposeful. Every sentence earns its place for a composite scoring tool with nuanced availability semantics.

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 output schema exists, the description still explains the critical behavioral context: which factors are validated, how unavailability is represented, what confidence means, and which sibling tools cover adjacent use cases. Nothing an agent needs to invoke this correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters. The description reinforces usage with a concrete example (lat=33.45 lon=-112.07 state=AZ) and mentions state improves lookups, but it does not add new semantic meaning beyond what the schema provides.

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

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

The description opens with a specific use case: a single 0-100 site suitability/risk verdict for a lat/lon with an explicit per-factor coverage map. It explicitly contrasts itself with analyze_site and names the output fields, so an agent can distinguish it from siblings without inspecting schemas.

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

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

It says 'Use when...' and gives explicit routing guidance: analyze_site for full data, compare_sites for 2-4 sites, and rank_markets for whole-market ranking. It also directs market/DCPI needs to rank_markets, leaving no ambiguity about when this tool is the right choice.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description discloses exact behavior on non-matching input: 'you get the GENERIC blurb with matched_category=null and context_understood=false', the additional fields (is_generic_answer, answer_note, next_tools) and the always-returned payload shape. No contradiction with annotations; readOnlyHint is consistent with returning copy rather than mutating state.

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

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

The description is dense and front-loaded with the primary use case, then details fallback behavior and exclusions. A few points are repeated (free text does not parse / does not compute an answer), but the length is justified by the need to correct the schema and route to siblings.

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 tool with an output schema, the description covers valid inputs, invalid-input behavior, returned fields, additional generic-answer fields, and exclusions. An agent has everything needed to call it correctly and interpret the response.

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's own parameter description is misleading ('Free-text description of the siting request'), and the tool description compensates by enumerating the only valid literal values ('general, investment, site-selection, technical') and explicitly warning that free text does not parse. That is critical added meaning beyond the schema, effectively correcting 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?

The description states a specific purpose: returning a ready-to-quote description of DC Hub in one of four categories plus the live top-ranked market pocket. It explicitly contrasts itself with a siting-answer computation ('It does NOT compute a siting answer from free text'), and the category list differentiates it from sibling analysis 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?

Gives explicit when-to-use ('ready-to-quote description... live top-ranked market pocket'), when-not-to-use with named alternatives ('Do NOT use for a single specific lat/lon (use analyze_site), to rank by ONE criterion (use rank_markets), or for an open-ended siting question... (use site_selection_canvas)'), and even describes next_tools fallback guidance returned on non-matching context.

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, and the description adds meaningful behavioral context: it is a live query, never estimated, county-level resolution, and returns coverage=unavailable outside US coverage. This goes well beyond the annotations and helps the agent set expectations.

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, data source, example, return shape, coverage behavior, and alternatives. It is front-loaded with the trigger condition and ends with routing guidance, making it easy to scan.

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 output schema exists, annotations cover safety, and the input schema is fully documented, the description is complete for an agent to select and invoke this tool correctly. It covers use case, source, coverage edge case, return structure, resolution, and alternatives.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds a concrete example with lat=33.45 and lon=-112.07, but it does not substantially enrich parameter meaning 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 states a specific verb and resource: it retrieves natural-hazard/disaster risk for a lat/lon, listing concrete hazard types and naming the FEMA National Risk Index as the data source. It also distinguishes itself from sibling tools by explicitly naming get_water_risk and get_composite_site_score as alternatives, 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?

The description opens with 'Use when a user wants...' and provides clear conditions, including coverage limitations for points outside US NRI coverage. It explicitly routes to alternatives for chronic water stress and blended site verdicts, giving the agent both when-to-use and when-not-to-use guidance.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds context beyond that: it is a live read, has a grid-status flag, requires attribution to DC Hub (CC-BY-4.0), and has no planner overhead. This is meaningful extra behavioral guidance 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 long, but nearly every sentence earns its place: trigger, exclusions, alternatives, params, output shape, attribution. It is front-loaded with the routing decision and uses clear visual markers. Slight redundancy ('IS the right call' / 'Use when') keeps it from a 5.

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

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

For a simple single-ISO price-lookup tool with rich annotations and an output schema, the description covers selection criteria, param usage, return shape, attribution, and all important sibling differentiators. Nothing an agent needs to decide whether to call this tool is missing.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description goes beyond the schema by explicitly marking iso as required, restricting it to the 7 US ISOs, and giving a concrete example (get_energy_prices iso=ERCOT). It does not fully explain the interaction of state/data_type, but those are already described 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 states a specific verb-resource pair ('live energy PRICING for the 7 US ISOs') and enumerates exactly what it returns. It also distinguishes itself from siblings by naming what it is not (fuel mix, headroom, gas-to-grid economics), so an agent can select it without ambiguity.

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

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

It gives an explicit trigger ('Use when a user asks what does power/gas COST in <ISO> right now?') and a hard exclusion rule (call execute_plan when price is one factor in siting/market comparison). It also lists each alternative sibling for each excluded case, leaving no ambiguity.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds value beyond this by disclosing the operational boundary — it returns exactly one full record and must not be used as a search/list primitive — plus the specific metadata contents of the response. It stops short of disclosing edge behaviors (e.g., behavior when an id/slug is not found), but for a read-only idempotent fetch this is a minor gap.

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

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

The core scope ('Full metadata for one facility') is front-loaded, followed by a dense field list, usage examples, and the explicit do-not-use constraint. Each sentence earns its place — the metadata enumeration sets expectations, the examples aid parameterization, and the exclusion prevents misuse. It runs slightly long relative to a two-sentence ideal but has no filler or repetition.

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

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

Given an output schema exists (so return-value details need not be restated), annotations cover the safety profile, and parameter coverage is 100%, the description is complete. It communicates scope (one facility), the do-not-use-for-searching boundary, usage examples, and the specific data returned. An agent has everything needed to invoke it correctly for a read-only, idempotent 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 coverage is 100%, so the baseline is 3. The description adds value beyond the schema by providing concrete, realistic example values (equinix-dc1-ashburn, digital-realty-iad8) that show an agent what valid id/slug look like, and reinforces that id is an alias for facility_id from a prior search result. These examples meaningfully help an agent populate the lookup parameters correctly.

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 ('Full metadata for one facility'), enumerates the exact fields returned (operator, address, lat/lon, MW total/used, cooling type, fiber carriers, commissioning year, status, DCPI verdict, peers), and answers concrete questions ('who operates this data center and how big is it'). It clearly distinguishes from the search_facilities sibling by emphasizing it returns exactly ONE facility, so an agent can tell them apart 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 with two working examples ('Try: get_facility id=equinix-dc1-ashburn — or get_facility slug=digital-realty-iad8') and an explicit exclusion with the named alternative ('do NOT use to search or list many facilities (use search_facilities)'). Nothing about when to use it vs alternatives is left to inference.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, covering the safety profile. On top of that, the description discloses the data-integrity contract: only DCPI market-health has a temporal series, static dimensions are declared static, and coverage:unavailable is returned when no snapshot history exists. This goes well beyond what annotations express.

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

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

Front-loaded with the trigger, then return shape, integrity notes, params, and alternatives in logical order. The INTEGRITY paragraph is lengthy but earns its place given the tool exists to prevent fabricated deltas. The 'Returns {...}' line is somewhat redundant since an output schema exists, and the all-caps emphasis is noisy — minor deductions.

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 three-plus complex behaviors (temporal delta semantics, integrity constraints across static dimensions, input alternatives, and an output schema), everything an agent needs is present: when to call, what it returns, what happens on missing data, and where to route point-in-time questions. No critical guidance 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 value by making the mutual-exclusion relationship explicit ('facility_id OR market') and glossing the since format and default — a relationship not encoded in the schema's per-parameter docs, which treat each parameter independently. Minor deduction because most parameter detail is already 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?

Uses a specific verb-resource pair (get/return facility risk delta), distinguishes the temporal ask from static prediction, quotes two natural-language triggers, and directly contrasts itself with three sibling tools (get_composite_site_score, get_disaster_risk, get_climate_intel). It is unambiguous what this tool computes and how to tell it apart from 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?

Opens with an explicit 'Use when a user asks what has CHANGED' trigger and example queries, then closes with an explicit when-not-to-use statement pointing to sibling tools for point-in-time risk. It even warns against misuse by stating the static dimensions 'never' get a fabricated delta. No gap in routing exists.

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 important behavioral context: it clarifies that the 'market' parameter filters routes by proximity (~1.2°), and it specifies the return format (GeoJSON FeatureCollection with properties). It also explains the MPP payment flow (challenge and token), which goes beyond the schema. Minor gap: no mention of rate limits or data freshness, but the description adds substantial value beyond annotations.

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

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

The description is dense but well-organized, front-loading the core use case and example, then covering params, return format, and exclusions. It is longer than average but every sentence serves a purpose. Slight rambling in the MPP explanation, but the structure is logical and scannable.

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

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

With a rich output schema present, the description doesn't need to explain return values in depth, but it does. It covers full parameter usage, the payment workflow, return format ready for Leaflet, and explicit alternatives. For a moderately complex tool with no required params, this is comprehensive and leaves no critical gaps for an agent to call it correctly.

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

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 for key parameters: it explains 'market' works with 'route_type=longhaul' to map backbones, and details the 'mpp_pay' and 'mpp_credential' payment steps (challenge, token, $0.50 per call). It clarifies 'carrier' can be omitted for all carriers and 'route_type' values are enumerated in prose. Since the description enriches the schema and clarifies the payment flow, it earns a 4.

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

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

The description clearly states the tool's purpose: scoring candidate sites for fiber depth, mapping long-haul routes, and assessing dark-fiber availability. It names specific verbs and resources (e.g., 'map long-haul routes', 'assess dark-fiber availability') and distinguishes it from siblings like get_facility and analyze_site. The example with 'Zayo long-haul routes through Northern Virginia' concretely illustrates usage.

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 (e.g., scoring fiber depth, mapping routes) and explicitly lists what not to do: 'Do NOT use to count fiber providers at a single facility (use get_facility) or for IX interconnection-density scores (use analyze_site).' This is a model of clear routing to alternatives.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds the crucial behavioral nuance that an 'unknown' near_net_bucket is NOT 'bad' — explaining the PeeringDB thin-coverage caveat, that carrier_data_coverage='none_in_region' yields null score/risk and 'unknown' bucket and must not be reported as greenfield/unserved/build-required, and that only 'confirmed' with carrier_count 0 means a real fiber build. This is precisely the kind of interpretation risk that an agent cannot infer from schema or annotations, and it's disclosed clearly.

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

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

The description is long, but every sentence earns its place: the usage trigger, the example with params, the return-field map, the PeeringDB caveat, and the exclusions. The most decision-relevant content (when to use and the 'unknown is not bad' caveat) is front-loaded. It loses one point only because the parameter list and return-field list partially duplicate the input schema and output schema, which are already structured, so some text is redundant.

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-parcel verdict tool with a rich output schema that already documents the return shape, this is complete. It explains the one ambiguity an agent will hit (coverage-driven 'unknown' buckets), gives the exclusions, names the alternatives, and the output schema covers return values. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100% and every parameter (lat, lon, lng, latitude, longitude, radius_km) is described inline with ranges and defaults. The description adds the example values (lat=39.04, lon=-77.48, radius_km=50) and clarifies the aliases, but the main added value is the return-object semantics rather than parameter syntax. Baseline 3 applies because the schema is complete; the example and the alias note nudge it to 4.

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

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

The description states a specific verb+resource ('get... FIBER-READINESS / connectivity verdict for ONE parcel or site') and a precise scope, and includes a concrete example. It differentiates itself from the two obvious siblings by naming get_fiber_intel and analyze_site, so an agent can tell them apart without opening either schema.

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

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

The description opens with 'Use when you need...', scopes it explicitly to one parcel or site vs. routes/metro context (get_fiber_intel) vs. multi-factor score (analyze_site), and closes with explicit do-not-use exclusions naming the alternatives. It also gives a worked example invocation. There is no ambiguity about when to select this 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?

Despite the light annotations (readOnlyHint/idempotentHint/destructiveHint), the description alone carries the full safety-and-quality burden: it discloses that the $/MWh gas-to-grid metric is WITHDRAWN, explains the data-quality failure with specifics (5.5x divergence across five surfaces, a physically impossible $6.73/MWh for Phoenix stamped 'live'), states that $/MMBtu layers are still returned, and names the status field (gas_to_grid_status) that carries the reason. No annotation is contradicted.

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

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

The purpose is front-loaded in a single crisp sentence, and the withdrawal notice is clearly delimited with a dated marker. The narrative is somewhat verbose — the 5.5x/$6.73/Phoenix backstory could be tightened — but the length is defensible because it justifies why the $/MWh must not be trusted, which is critical safety information 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?

For a tool of this complexity (a withdrawn output, data-quality caveats, and a conditional parameter), the description covers nearly everything: returned layers, withdrawn metric, status field, invocation pattern, and the key sibling exclusion. An output schema exists so return-value documentation is not the description's burden. The only real gap is that the fate of the heat_rate_btu_per_kwh parameter after the withdrawal (ignored vs. error) is left slightly ambiguous.

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 per the baseline the schema already documents both market and heat_rate_btu_per_kwh. The description adds modest value by clarifying the $/MMBtu unit context and by explaining that heat-rate scenarios pertain to the withdrawn $/MWh output, but it does not systematically deepen the semantics of either parameter 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 first sentence names a specific deliverable — behind-the-meter/gas-fired power inputs for a US data-center market (Henry Hub spot, regional basis differential, delivered industrial + electric gas tariff in $/MMBtu, each with source labels) — which is far more specific than the generic title. It also differentiates itself from the sibling set by explicitly carving out what it is NOT (electricity grid fuel mix, handled by get_grid_data).

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

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

The description gives an exact invocation pattern ('Pass market=<slug>' with concrete examples), and states an explicit exclusion with a named alternative: 'Do NOT use for the electricity grid fuel mix (use get_grid_data).' It also gives behavioral guardrails about not quoting cached $/MWh figures or deriving them without disclosure, which is operational guidance an agent can act on.

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

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

Beyond annotations (read-only, idempotent, non-destructive), the description discloses material behavioral facts: the index was 'WITHDRAWN 2026-08-08, RESTORED 2026-08-30' after defect repairs, old figures are not comparable, and unpriced states return 'verdict UNSCORED with dcgi null and an `unscored_reaon` — absence, not a low score.' It also names the output field `gas_price_series` and where methodology corrections live. This is exactly the kind of context annotations cannot express.

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

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

The description is dense with audit history, star bullets, and repeated withdrawal-and-restoration warnings: 'Withdrawn 2026-08-08, restored 2026-08-30' and 'do NOT compare' appear multiple times across the description and parameter text. The first sentence earns its place, but the detailed three-term defect narrative and duplicated caveats could be cut by more than half without losing 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?

Annotations and output schema cover safety and return structure, and the description adds genuine caveats (unpriced verdicts, non-comparable vintages, alternative tool). However, both parameters are optional and the description never states what happens when `state` is omitted or what the default limit actually is, leaving a real calling gap.

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

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

With 100% schema coverage, the baseline is 3; the `state` parameter description goes further by explaining the return verdict, `gas_price_series`, the `unscored_reaon` absence semantics, the corrected-index warning, and a sibling pointer. `limit` remains generic ('default varies by tool'), so not every parameter is enriched.

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 clause defines the tool as 'Data Center Gas Index (DCGI) — the per-US-state natural-gas suitability score,' which gives a concrete resource and scope. It stops short of an explicit action verb such as 'returns' or 'fetches,' and the correction-history text dilutes the clarity, so it does not reach 5.

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 ends with an explicit routing instruction: 'Use get_gas_intelligence for the per-state pipeline and operator brief,' which names a sibling and its purpose. It does not provide broader when/when-not conditions or distinguish among the many energy-related sibling tools, so it is a useful pointer rather than full selection 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?

Very rich behavioral disclosure beyond annotations: it reveals the history of withdrawn/restored DCGI terms, warns that pre-2026-08-08 figures come from a different index and must not be compared, states that gas_to_grid_usd_per_mwh and the delta remain withdrawn due to a 5.5x defect, and insists on reading the status fields rather than assuming they move together. It also discloses deliberate omissions and the 'never fabricated' honesty policy.

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

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

The description is long but well-organized and front-loaded with the use case before caveats. It uses clear labels (Params, Returns, warnings) and bold/star emphasis for critical warnings. There is minor redundancy in repeating the 'two different states' warning and the withdrawn/restored narrative, but each sentence carries substantive operational guidance.

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

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

Given the tool's complexity and the rich output schema context, the description is exceptionally complete. It covers what fields are returned, per-field provenance, which fields are null and why, what is deliberately omitted, which status fields to read, and which sibling tools to use instead. Nothing an agent needs to call this safely and correctly appears to be 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 already provides 100% description coverage for both parameters, so the baseline is 3. The description only repeats the region format ('US state code or name, e.g. "TX" | "Texas" | "Virginia"') without adding new meaning beyond the schema. The schema also has a 'state' alias that the description does not clarify, though this is not a significant gap.

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

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

The description opens with a specific verb and resource: 'Use when a human asks about gas-fired or behind-the-meter power economics for a data center in a US state'. It clearly differentiates itself from siblings by naming get_grid_intelligence as the GAS analogue and explicitly excluding grid headroom and DCGI-score-only use cases.

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 guidance with concrete example questions ('is gas power cheaper than the grid in Texas?') and explicit when-not-to-use guidance with named alternatives: 'Do NOT use for electricity grid headroom (use get_grid_intelligence) or the DCGI score alone (use get_gas_index).' This leaves no ambiguity about tool selection.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: the data source (GEM Global Integrated Power Tracker), coverage scale (182,000+ geolocated units, 170+ countries), per-unit attributes (fuel, MW, status, start year, operator/owner, lat/lng), and the return shape (summary by fuel/status plus largest units). This goes beyond what annotations alone convey.

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

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

The description is long but every section earns its place: scope, fuel coverage, data provenance, filter semantics, return values, example query, and sibling exclusions. It is front-loaded with the primary use condition. Slightly dense, but for a 7-parameter global-coverage tool with several sibling rivals, the length is justified.

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 of this complexity — 7 optional parameters, global scope, multiple closely related siblings, and an output schema present — the description covers all decision-relevant context: primary use case, exclusion conditions with named alternatives, parameter semantics, data provenance, and expected outputs. Nothing an agent needs to select or invoke this tool correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds genuine semantic value above the schema: it explains pipeline=true as 'JUST the forward set: announced + pre-construction + construction', that fuel is a 'comma-union', and demonstrates parameter interaction with 'get_global_power country=India pipeline=true'. This enriches the bare schema 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 names a specific verb+resource (retrieve the Global Energy Monitor Global Integrated Power Tracker asset inventory) and precisely scopes it: WORLDWIDE/non-US, operating plus forward pipeline, all fuels. It distinguishes itself from siblings by name (get_grid_intelligence, get_grid_scoreboard, get_power_pipeline) with an explicit do-not-use boundary, so an agent can select it correctly without ambiguity.

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

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

Provides explicit when-to-use guidance ('Use when a user asks about power plants/units WORLDWIDE or in a NON-US country') and explicit when-not-to-use with named alternatives ('Do NOT use for US grid telemetry/headroom (use get_grid_intelligence / get_grid_scoreboard) or the US planned-generator feed (use get_power_pipeline)'). Also supplies a worked example query, 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 declare readOnlyHint=true and destructiveHint=false, so the agent knows it's a safe read operation. The description adds important behavioral context: real-time telemetry, single-ISO scope ('for one ISO'), and the data source via EIA. It also implies potential rate/size constraints by warning against heavy analyses. Minor deduction for not explicitly stating response size or rate limits, but this is well-covered for the read-only annotation.

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

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

A single, dense paragraph front-loads the core purpose before routing to alternatives. Every clause earns its place; no filler words.

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

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

For a read-only, idempotent tool with full schema coverage and no nested objects, this description covers purpose, usage, provenance, and scope completely. The explicit exclusions preempt common agent mis-selections and cover the highest-risk failure modes.

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

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

Schema covers 100% of parameters, so the baseline is 3. The description adds value by giving a concrete example ('Pass iso=PJM'), reminding that iso is required despite schema listing it as optional, and naming the valid ISOs. This example meaningfully reduces agent confusion about the parameter format.

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

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

The description clearly states the tool provides real-time electricity grid data for 7 specific US ISOs, listing each abbreviation. It names the source (EIA hourly RTO) and specific data types (fuel mix, demand, 24h demand curve). This distinguishes it from many siblings, and explicitly names get_grid_intelligence and get_energy_prices as alternatives for other use cases.

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 and when-not-to-use guidance. It states the tool is for real-time telemetry and explicitly directs away from power-availability, time-to-power, interconnection-queue, and retail/gas pricing analyses to get_grid_intelligence and get_energy_prices. It also gives global alternatives (get_grid_scoreboard) for non-US grids. This is a model of clear routing.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable behavioral context beyond that: the critical warning that avg_time_to_power_months and avg_queue_wait_months are different measurements with different derivations, the market-to-ISO resolution behavior with the resolved_from block, and the balancing-authority versus ISO data-granularity caveat. There is no contradiction with the annotations.

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

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

The description is front-loaded with the trigger phrase and a concrete example, then moves through params, returns, and caveats. It is dense and long, but nearly every sentence carries operative information, including the metric-distinction warning and sibling exclusions. The only slight drawback is that it reads as a wall of text; a little structuring could make it more scannable, but it is not padded.

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

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

Given the tool's complexity (6 params, multiple input modes, a rich output schema, and subtle metric distinctions), the description is exceptionally complete. It covers parameter aliases, market vs ISO resolution, balancing-authority scope limits, the resolved_from behavior, the full return list, the non-interchangeability of two time metrics, and sibling tool routing. 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 description coverage is 100%, so baseline is 3, but the description goes well beyond the schema. It explains alias behavior (iso/region accepted for region_id), the semantic difference between market= and region_id=, the market-resolution process, the PJM-DOM zone case, and even the mpp_pay/mpp_credential payment flow. This is rich semantic clarification that the schema alone does not provide.

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 leads with the exact user question it answers ('can I get N MW of power in <ISO> and how long will it take?') and names the tool as the 'flagship grid-headroom + interconnection-queue brief for one ISO'. It gives a concrete PJM example and explicitly distinguishes itself from compare_isos and get_grid_scoreboard, so an agent can tell it apart from siblings without opening their schemas.

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

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

Opens with 'Use when a user asks...' and includes a realistic example showing region_id='PJM'. It explicitly states when NOT to use the tool ('Do NOT use to compare 2+ ISOs side-by-side (use compare_isos) or for the global greenest-first ranking (use get_grid_scoreboard)'), naming the exact alternatives. This is fully explicit 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 readOnly/idempotent annotations, the description discloses important behavioral traits: freshness is not uniform, rows carry mix_age_hours/freshness_basis, and the US EIA data has a known lag. It explicitly instructs the agent to read mix_age_hours before narrating any row as current, and explains that some grids are listed unranked in partial_grids. No contradictions with annotations.

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

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

The description is a single dense paragraph that packs in a wealth of information, but it is overlong and would benefit from structured bullets or sections. The repeated 'answers' phrases and trailing 'Try: get_grid_scoreboard' add redundancy, though the opening efficiently states the tool's global scope.

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 freshness caveats, partial coverage, regional anomalies, data sources, attribution, and clear use cases. Combined with the presence of an output schema, an agent has everything needed to call and correctly interpret the tool without additional lookups.

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 parameters, so no parameter-specific documentation is needed; the schema coverage is 100% by definition. The description instead adds value by explaining output field semantics (mix_age_hours, demand_vs_mix_lag_hours, renewable_share_pct), which is above the baseline for a no-parameter tool.

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

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

The description immediately identifies the tool as a global grid scoreboard, enumerates all covered regions, and specifies the ranked metrics (renewable share %, gas share %, fuel mix, demand). It also differentiates itself from siblings by explicitly contrasting with compare_isos (pairwise) and get_grid_data (single ISO), leaving no ambiguity about what the tool returns.

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 states concrete use cases: answering 'which grid worldwide is greenest, or most gas-reliant, for siting a data center?' and 'which grid is cleanest right now'. It also gives exclusion criteria by naming alternatives (compare_isos for pairwise, get_grid_data for single ISO) and warns about edge cases like Brazil having no gas share and AU/SG being unranked.

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 critical behavioral details: the capacity_type trap ('gen' is NOT available load and must never be relayed as siting capacity), the sample_complete=false/capacity_floor_mw honesty mechanics, the 'never a silent zero' not-published behavior, and the explicit coverage limitation. This is far more than annotations provide.

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

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

The description is long but every sentence earns its place: purpose is front-loaded, calling modes are grouped, warnings are explicitly separated, and exclusions come at the end. Despite the length, it reads as a dense, organized operating manual rather than filler.

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

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

Given the tool's complexity, the description covers purpose, all invocation modes, parameter semantics, return value semantics, coverage limitations, example calls, and exclusions to sibling tools. An agent has everything needed to select and invoke this tool correctly, and the output schema covers the return structure.

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

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

Schema coverage is already 100%, but the description adds substantial meaning beyond the schema: it explains the dangerous semantic difference between load vs gen capacity, clarifies that radius_km is ignored in utility mode, shows how min_mw is used, and describes the no-args mode that returns the coverage list. The capacity_type warning alone justifies a top score.

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 ('Utility-PUBLISHED feeder hosting capacity — the MW a NAMED distribution feeder can actually take') and explicitly distinguishes this from transmission, interconnection queue, and retirement headroom by naming the sibling tools. It also states the exact questions it answers, so an agent cannot confuse it with neighboring power-grid 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 explicit when-to-use guidance: three calling modes (lat/lon, utility/market, no args), a concrete example invocation, and an explicit 'Do NOT use for...' section naming the correct alternatives. This leaves no ambiguity about when to select this tool over siblings.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, so the safety profile is covered. The description adds behavioral context beyond annotations: it returns raw assets joined to HIFLD/EIA, includes counts and max voltage for substations, and notes the configurable radius. It does not mention pagination or response format, but the output schema exists, so this is acceptable.

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 a single dense paragraph that front-loads the core purpose, enumerates asset types, gives concrete usage examples, and routes to an alternative—all without wasted words. Every sentence adds information; no filler.

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

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

Given the tool's complexity (multiple asset layers, filters, aliases) and the presence of a full input schema and output schema, the description covers everything an agent needs: what assets are returned, how radius works, example invocation, and the explicit exclusion of scored verdicts. 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?

Schema description coverage is 100%, so each parameter is already documented. The description adds meaningful context beyond the schema: it explains that radius_km is the configurable search radius, ties min_voltage_kv to transmission/substations (>69 kV overlay), and provides a concrete example of lat/lon/radius usage. This adds value beyond the structured schema.

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

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

States a specific verb and resource: 'get_infrastructure' returns nearby infrastructure assets for a location, enumerating exact asset types (substations, transmission lines, pipelines, power plants) and the kind of data returned (distance, capacity). It also names the sibling 'analyze_site' and contrasts itself by being raw vs. scored, making the purpose unambiguous and distinguishable.

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 answers representative questions ('what is near this parcel', 'how far is the nearest substation and what voltage is it'), gives a concrete example call (lat=33.45 lon=-112.07 radius_km=25), and explicitly states when NOT to use it ('do NOT use for a single scored site-suitability verdict (use analyze_site)'). This is clear when-to-use vs. alternative 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 readOnly, idempotent, and non-destructive behavior, and the description adds meaningful context: it is real-time, aggregates multiple component signals, and returns specific outputs such as percentile rank, trend direction, and component scores. No annotation contradiction exists.

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

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

The description is compact and well-structured: core capability first, return detail second, usage examples and exclusions last. Every sentence carries information, and the alternatives are named rather than implied.

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 zero parameters, a rich output schema, and annotations covering safety, the description fully covers what the tool does, what it returns, and how to use it correctly. Nothing critical for an agent to invoke this tool is missing.

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

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

The input schema has zero parameters, so the baseline is 4. The description adds useful semantic context by showing how the market is specified in an example, though this example references a market argument not present in the schema, which creates minor ambiguity about the actual parameter contract.

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: it returns a real-time composite market health score from 0-100 and specifies the aggregated inputs. It explicitly distinguishes itself from get_market_intel and rank_markets, making its purpose unambiguous relative to siblings.

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

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

The description gives direct usage guidance: it answers particular questions, provides a concrete invocation example, and explicitly says when NOT to use it, naming the alternatives to use instead for full market metrics and multi-market ranking.

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 annotations (readOnlyHint, idempotentHint, destructiveHint), the description discloses important dynamic behavior: the `projects` field changes shape depending on whether `iso` is provided, ERCOT is the only ISO with non-null `data_center_gw`, and the response includes provenance in `top_subregions`. This is valuable context that annotations cannot convey.

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

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

The description is long but densely packed with essential information. It front-loads the core purpose, then adds critical shape-change caveats, usage boundaries, and alternative routing. There is no fluff; each sentence contributes to correct invocation or interpretation.

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

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

With a single optional parameter, a rich output schema, and annotations covering safety and idempotency, the description fully covers all needed context: purpose, scope, behavioral quirks, data source caveats, and explicit do/don't usage. No significant gap remains for an agent to call this correctly.

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

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

Although the schema already documents the `iso` parameter at 100% coverage, the description adds crucial semantics: omitting `iso` returns an all-ISO summary object, while including it returns an array of per-project rows. It also enumerates the valid ISO values and highlights the special ERCOT behavior, significantly enriching the parameter's meaning.

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 an ISO-level interconnection queue snapshot with a specific verb ('snapshot') and resource, and it explicitly distinguishes itself from related tools like get_grid_intelligence and grid_transition_radar. It also explains the unique ERCOT large-load data center field, making the tool's purpose unmistakable.

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

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

The description explicitly states when to use this tool ('queue-depth site-selection and AI/data-center-load saturation intel') and when not to use it ('single-site time-to-power read' or 'forward-looking emergence'), naming the exact alternative tools. This removes ambiguity about tool selection.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description does not contradict these. Beyond the annotations, it adds rich behavioral context: the 'greedily filled' priority-order token-budget behavior, the per-section as_of timestamp and citable URL, the omitted field when the budget is exceeded, and the output envelope {sections, used_tokens, omitted}. This gives an agent accurate expectations about side effects and output characteristics.

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 block earns its place: front-loaded core purpose, contents list, a concrete example, parameter summary, return-shape summary, explicit alternatives, and a required citation. The only minor redundancy is the Params block mirroring the schema, but the overall structure is efficient and well-ordered.

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 an output schema (which already documents return values), safety annotations, two parameters, and a crowded sibling space, the description leaves nothing essential missing: it covers when to use it, when not to use it, alternatives, parameter ranges and defaults, the token-budget filling behavior, the return structure, and even the citation source. An agent has all information needed 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?

Schema coverage is 100% and both parameters have detailed descriptions in the schema, including the max_tokens behavior ('sections are filled in priority order until the budget is spent'). The tool description largely repeats this information, adding an example invocation ('Brief me on ERCOT...') and restating the ISO enum values already in the schema. This is baseline 3: the schema does the heavy lifting, with marginal added value from the example.

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

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

The description states a specific verb and resource: returns a token-budgeted context pack for a US ISO/RTO, listing concrete contents (grid snapshot, DCPI verdict mix, queue depth, LMP, news). It clearly distinguishes itself from siblings by calling itself 'the narrative briefing pack' and naming alternatives like get_grid_data, get_grid_intelligence, and compare_isos, so an agent can select it without ambiguity.

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

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

Explicitly states when to use: 'when an agent needs a WHOLE-grid briefing it can drop straight into its context window.' It also gives a precise do-not-use list: raw single-ISO telemetry (use get_grid_data), per-ISO decision brief (use get_grid_intelligence), multi-ISO scalar comparison (use compare_isos), and non-US grids (use get_grid_scoreboard). This is ideal routing guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and destructiveHint=false, and the description is fully consistent — a briefing pack is a safe, repeatable read. Beyond annotations, it discloses real behavioral traits: sections are greedily filled in priority order under the max_tokens budget, over-budget content lands in an omitted field, and each section carries its own token count, as_of timestamp, and citable URL. It also adds the citation requirement ('Cite "DC Hub (dchub.cloud)"').

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 front-loads the core purpose and budget behavior before the details, and nearly every clause adds information: the section list, per-section metadata, omission behavior, the example, and the exclusions. It loses a point for being one dense paragraph with em-dash asides and for duplicating schema content (parameter ranges and defaults appear in both places), which adds length without new 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?

For a tool with two parameters, a documented output schema, and many siblings, the description covers everything needed to invoke it correctly: the triggering scenario, explicit exclusions with alternatives, parameter semantics, the return shape ({sections, used_tokens, omitted}), a concrete natural-language-to-call example, and the citation obligation. No gap remains that would force the agent to guess or open another tool's schema.

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

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

Schema coverage is 100% — both market and max_tokens are documented with type, constraints, defaults, and provenance ('valid slugs come from rank_markets / get_market_dcpi_rank'). The description largely restates this content ('Params: market ... max_tokens ... 200-8000, default 4000'), so its marginal value over the schema is limited to the worked example mapping 'Brief me on the Columbus data-center market' to market=columbus max_tokens=4000. Baseline 3 applies because the schema carries the heavy lifting.

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: it returns a token-budgeted WHOLE-market context pack for a data-center market, listing the exact sections it contains (DCPI verdict, power & grid, 12-month outlook, M&A, pipeline, comps, risk, news). It explicitly differentiates from siblings via the 'Do NOT use' clause naming get_market_dcpi_rank, get_market_intel, and rank_markets. This 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?

The description states the triggering condition upfront ('Use when an agent needs a WHOLE-market briefing it can drop straight into its context window') and gives an explicit exclusion list with the correct alternative for each case: single metric → get_market_dcpi_rank, raw structured metrics → get_market_intel, cross-market ranking → rank_markets. It reinforces the boundary by labeling itself 'the narrative briefing pack,' so no inference is required.

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