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

Annotations already establish readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context beyond those: refresh cadence ('Refreshed Fridays 14:00 UTC'), composite-score composition ('depth + diversity + power'), and a data-availability caveat ('cooling-type signals where facility data carries them'). No contradiction with annotations.

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

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

The description is front-loaded with the core ranking purpose, then supplies return fields, refresh timing, use cases, and exclusions in compact sentences. Every sentence earns its place; there is no repetition of the input schema or annotation fields.

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

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

For a tool with two optional parameters, an output schema, and read-only annotations, the description covers what the tool returns, what the ranking means, when it was refreshed, when to use it, and when to use alternatives. Nothing an agent needs to select or invoke it correctly is missing.

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

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

Schema description coverage is 100%, so the input schema already documents limit and horizon with ranges and defaults. The description adds conceptual framing by tying horizon to '30/60/90 days' and 'deployable_mw,' but it does not add parameter-specific syntax beyond the schema. Baseline 3 is appropriate because the schema carries the parameter-documentation burden.

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

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

The description opens with a specific verb and resource: 'ranks data center markets' by 'where 100MW of AI training capacity can land in the next 30/60/90 days.' It is immediately distinguishable from siblings by explicitly stating what it is not ('Do NOT use for a general best-markets ranking... or forward grid-emergence').

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

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

The description gives explicit use contexts ('AI capex planning, GPU cluster siting, hyperscaler deal forecasting') and explicit alternatives with the condition that selects them: use rank_markets for general best-markets ranking and grid_transition_radar for forward grid-emergence. This leaves no ambiguity about when to invoke this tool.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower — yet the description adds substantial behavioral context on top: the honest-404-with-coverage-list failure mode ('never a guess'), the staged hosted-layer rollout (Loudoun County VA first), the representative_point subtlety (centroid of the LARGEST-area member, never the multi-part geometric center which 'can land off-parcel... and poison every point-keyed read'), and the site_evaluation_handoff wiring. These are behavioral traits no annotation could express, including a rationale for a potentially surprising design choice.

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

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

The description is dense at roughly 190 words, but every clause earns its place: function, both modes, coverage rollout, failure behavior, return fields, handoff target, and sibling routing. It is front-loaded with the core verb+resource and the two-mode explanation. It is at the upper bound of acceptable length, which is justified by the tool's two-mode complexity, but it still demands a full read.

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

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

For a tool with two invocation modes, a hosted-coverage boundary condition, a multi-field return payload, and fan-out to downstream tools, the description covers every decision an agent needs: both input paths, the failure contract (404 plus coverage list), the key return-field design nuance (largest-area centroid), the handoff pipe into analyze_site + get_water_risk, and exclusions. An output schema exists to carry the formal return structure, and the failure-mode text goes beyond what structured fields could convey.

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

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

Schema description coverage is 100%, and the schema already documents the mode relationship ('used with lon when geometry is omitted', 'Omit to look up the hosted parcel containing lat/lon instead') and the capacity_mw pass-through. The description reinforces the either/or framing ('pass your own GeoJSON... OR just lat+lon') but adds little meaning beyond what the parameter descriptions already provide, so the baseline-3 applies.

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

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

Opens with a specific verb+resource ('Structured read of a parcel BOUNDARY') and enumerates two concrete invocation modes: passing a GeoJSON boundary or supplying lat/lon for hosted-layer lookup. It actively differentiates itself from siblings by naming analyze_site (general site score) and get_refined_queue (interconnection queue) as the things it is NOT, so an agent can disambiguate without opening other schemas.

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

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

Gives explicit routing: 'Use when you HAVE a boundary or a point on a specific parcel and want it anchored + sized', then names the alternatives with their selection conditions — analyze_site for a general lat/lon site score and get_refined_queue for interconnection-queue data. It even explains WHY the queue tools cannot auto-join (queue rows carry NO parcel identity), which prevents a whole class of misuse.

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

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

Beyond readOnly/idempotent annotations, it discloses key behaviors: location resolves to market centroid rather than parcel, candidate_id uses frozen mint and fails closed with candidate_expired, capacity_mw adds a capacity_context block without moving overall_score, and free vs Pro returns are clearly separated.

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

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

Long but dense: front-loaded use case, example, parameter notes, return structure, and routing exclusions. No filler; the length is justified by 12 parameters and several behavioral caveats.

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

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

Covers input modes, output shape, free/pro constraints, alias semantics, failure behavior, and alternative tools. An agent has everything needed to decide, call, and interpret this tool without extra lookups.

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

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

Even with 100% schema coverage, the description adds meaning: it explains parameter relationships and side effects (capacity_mw sizing, location's resolved_from block, candidate_id ignoring lat/lon, state improving tax lookup), which are not evident from the schema alone.

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

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

The description opens with an explicit use case ('ONE specific lat/lon... full multi-factor data-center suitability read') and gives a concrete example. It differentiates itself from siblings by naming what it is not (compare_sites, find_alternatives).

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

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

It provides explicit when-to-use guidance, a call example, and direct exclusions with named alternatives: water/disaster/climate/tax reads route to get_water_risk etc., 2+ sites to compare_sites, site matching to find_alternatives.

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

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

The description goes far beyond the annotations, explaining the behavioral consequences of binding: the key becomes recoverable, durability is not guaranteed, binding restores the free tier at 50 calls/day, and the email is used only for recovery and receipts. It also discloses the failure behavior when an email is rejected. This is exceptionally transparent for an AI agent.

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

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

The description is well-structured with clear sections and front-loaded purpose, but it is verbose. The honest-ladder explanation, the detailed cohort caveat, and the lengthy marketing opt-in discussion could be tightened while preserving the essential guidance. Every section is useful, but not every sentence is maximally economical.

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

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

For a tool with a consent-sensitive side effect, this description is exceptionally complete. It covers when to call, what happens after binding, the key's recoverability limits, the free-tier behavior, email usage restrictions, marketing opt-in conditions, and error behavior. An agent has essentially everything needed to invoke this tool correctly and responsibly.

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

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

The schema already covers all three parameters with clear descriptions, providing a strong baseline. The tool description adds meaningful extra semantics: api_key can be omitted to bind the session-active key, marketing_opt_in should only be true after explicit consent, and the email must be explicitly provided by the human. This enriches the schema without contradicting it.

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

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

The description states a clear verb and resource: 'Tie your DC Hub key to your human's email so the key is RECOVERABLE...' It also explicitly contrasts what binding does and does not do, setting it apart from related tools like recover_my_key and claim_free_key. This is precise, specific, and unambiguous.

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

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

The description gives explicit when-to-use guidance ('Call this once your human shares their email'), what to do if no email is available ('ask them first'), and what not to do ('NEVER invent, guess, or use a placeholder address'). It even discusses the only alternative that is measured to retain access (OAuth sign-in) and when binding is the best available option. This leaves no room for the agent to misuse the tool.

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

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

Despite annotations being sparse (readOnlyHint=false, destructiveHint=false, idempotentHint=false), the description discloses significant behavioral traits: re-minting restarts daily allowance and orphans history, keys are not durable for hosted web clients, OAuth requires a human, and measured statistics on key survival. It contradicts no annotations; annotations correctly flag this as not read-only, not idempotent, not destructive at the boolean level, and the description adds crucial nuance beyond those flags.

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

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

The description is extremely long and densely packed, with multiple all-caps sections and embedded metrics. While every section carries real guidance, the sheer volume makes it hard for an agent to parse quickly, and key operational facts (call when hitting paywall, set X-API-Key, don't re-mint) are buried among cohort statistics and conditional client caveats. It is not concise, though it is structured with ★ markers.

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

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

Given the tool's complexity—two optional params, a return object, and wildly different client contexts—the description covers all necessary branches: OAuth-capable clients, header-capable clients, paste-a-URL connectors, lost-key recovery, and post-mint next steps. The output schema exists, so return values need not be restated, and the description references the key fields (api_key, connect_url, etc.) appropriately. Nothing essential is missing.

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

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

Schema coverage is 100% and both parameters are described in the schema, so baseline is 3. The description adds meaningful context: email makes the key recoverable across sessions and is the durable anchor for hosted clients, while client_name is for attribution. It explicitly states the key still mints without an email and that email should only be an address the human explicitly gave. This exceeds schema-only semantics.

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

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

The description clearly states the tool's purpose: to mint a free DC Hub dev key with one call, returning an api_key to set as X-API-Key. It distinguishes itself from siblings like recover_my_key and unlock_more_data by explicitly naming alternatives. However, the purpose is buried under extensive pre-mint guidance, so an agent scanning for the verb may initially find it less crisp.

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

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

The description gives explicit when-to-use guidance: call it the moment you hit a paywall or partial preview, and explicitly says do NOT call it if you already hold a key, naming recover_my_key as the alternative for lost keys. It also provides clear when-not-to-use conditions for OAuth/handshake-capable clients and paste-a-URL connectors, directing those to sign-in or connect_url respectively. This is unusually thorough usage routing.

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

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

Even with readOnlyHint and idempotentHint annotations, the description adds substantial behavioral context: fail-closed handling of expired/unknown candidate ids, deterministic pruning, inference via route_factor 1.4, and the caveat that estimates are not engineered latency quotes. The annotations and description are fully consistent.

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

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

The description is long but information-dense and front-loaded with the core purpose and use case. The output-field enumeration partly duplicates the existing output schema, but the compact return summary, explicit contract, example, and alternatives make the length justified.

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

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

Given the tool's complexity, the description covers the input contract, candidate-id resolution rules, output shape, confidence provenance, failure semantics, caveats, and sibling-tool routing. Nothing critical for an agent to select and call this tool correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces key semantics like the candidate-contract fail-closed behavior and sync-replication latency ranges, but these are already present in the input schema. It adds examples but not significant new parameter meaning beyond the schema.

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

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

The description states a specific verb and resource: physics-bounded latency clustering of 2-8 sites returning viable clusters and pairwise RTT floors. It explicitly distinguishes itself from plan_fiber_leadin and get_fiber_readiness, and the 'deterministic pruning BEFORE detailed routing' phrasing makes its role unmistakable.

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

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

The description explicitly says when to use the tool: when the human wants to know which candidate sites can form a synchronous/low-latency cluster. It also gives clear when-not-to-use guidance: do not treat results as engineered quotes, and use plan_fiber_leadin or get_fiber_readiness for adjacent needs.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds important behavioral nuance by warning that avg_time_to_power_months and avg_queue_wait_months are different measurements and must be quoted by name — a subtle trap that the schema alone would not reveal.

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

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

The description is front-loaded with the primary use case and every sentence carries value — example, parameter guidance, return shape, metric warning, and exclusions. It loses one point because some content duplicates the input schema's valid-value list and the output schema's field list.

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

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

For a comparison tool with a single parameter, annotations, and an output schema, the description is complete: it states when to use, provides a concrete example, explains the difference between two confusing metrics, and explicitly routes the agent away from inappropriate uses. Nothing needed for correct invocation is missing.

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

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

Schema coverage is 100% and already lists the valid ISO values and the 2-4 range. The description repeats this information and adds an example call, but does not add meaningful semantics beyond the schema. This meets the baseline for full schema coverage.

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

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

The description states a specific verb and resource: 'side-by-side of 2-4 ISO grids' with the exact comparison dimensions listed. It clearly distinguishes from siblings by naming get_grid_intelligence and get_grid_scoreboard as the alternatives for different use cases.

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

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

Explicitly says when to use: when a user wants a side-by-side in one call instead of N sequential get_grid_intelligence calls. It also provides explicit do-not-use conditions with named alternatives: do not use for global ranking (use get_grid_scoreboard) or single-ISO deep briefs (use get_grid_intelligence).

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive, and the description reinforces this by saying it runs the analyze_site read. It adds non-obvious behavior: capacity_mw is forwarded to each site but does not affect overall_score, and it discloses that the tool is paid/Pro with a locked free-tier preview.

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

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

The description is dense but well organized, with usage context, an example, parameter guidance, return details, and exclusions. It is longer than strictly necessary because it restates a detailed return shape even though an output schema exists, but the extra detail is structured and useful.

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

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

For a tool of this complexity, the description covers when to use it, what it does, parameter behavior, output characteristics, paid-tier restrictions, and explicit alternatives. Nothing critical is missing for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, and the description still adds meaningful semantics beyond the schema. It explains the locations semicolon delimiter and 2-4 limit, gives a typical capacity_mw range, and clarifies that capacity_mw does not influence the ranking. This prevents an agent from misinterpreting the parameters.

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

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

The description states a precise scope: a side-by-side winner picker for 2-4 candidate parcels, ranking by overall score with a recommended pick and reason. It clearly differentiates from analyze_site and rank_markets, making the tool's purpose unambiguous.

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

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

It explicitly says to use this when a user has narrowed to 2-4 candidate parcels and wants a comparison, and provides a concrete example. It also gives clear exclusions: do not use for a single site (use analyze_site) or to rank entire markets (use rank_markets), leaving no ambiguity about when this tool is appropriate.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds genuinely valuable behavior: progressive disclosure, default comparables count, paid-key gating, escalation paths via 'summary' and 'full', and the fact that verdict text is always included. This goes well beyond the structured annotations.

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

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

The description is longer than minimal but every sentence earns its place: core behavior, progressive disclosure, paid-key caveat, comparables escalation, and an example. It is front-loaded with the main purpose before diving into disclosure mechanics. Slight redundancy in the quoted questions could be trimmed, but overall it is well structured.

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

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

Given an output schema exists and annotations carry the read-only/idempotent safety profile, the description provides everything an agent needs: what is returned, default behavior, paid-key restriction, comparables escalation, and the kind of questions it answers. No critical operational detail is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful usage nuance: 'limit' is exemplified with a default of ~15, and 'comparables' gets a clear escalation ladder (none cheap, summary for top-2 signals, full for drilling in). It clarifies cost/behavior implications, not just types — a real addition over the schema.

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

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

Description states a specific resource — data-center M&A/capex deal flow — and a distinct output: deals with DCPI grid-reality verdicts and per-deal autopsy reads. It differentiates itself from generic transaction or market tools by overlaying 'what is the real play?' on each market. The verb 'Returns' plus named output components make the tool's job unambiguous.

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

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

Provides clear use-case context: answering 'who is actually buying data centers right now' and 'what is the real play behind this deal', plus a concrete 'Try deal_autopsy limit=15' example. It does not explicitly name alternatives like list_transactions or get_market_intel, so the guidance is strong on context but lacks explicit when-not-to-use exclusions.

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

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

The description goes beyond the readOnly/idempotent annotations by explaining the tool's navigation-layer behavior, its filtered output, and its non-exhaustive relationship to tools/list. It warns that this is not the exhaustive catalog and tells the agent where to get full schemas, which is valuable behavioral context.

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

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

The description is dense but mostly earns its length: it front-loads the purpose, then adds return shape, family list, usage guidance, and canonical-source caveats. The final capability-map binding note is somewhat niche but still useful, so the structure is efficient without being bloated.

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

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

For a meta-tool with one optional parameter and an output schema, the description covers all essential operational context: when to call it, what it returns, how filtering works, where the authoritative catalog lives, and what to do after discovery. Nothing critical is missing.

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

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

The schema already covers the single optional `query` parameter with examples and meaning, so the description adds little parameter-level information beyond restating that filtering is optional. With 100% schema description coverage, the baseline score applies.

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

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

The description states a specific verb and resource: 'navigate DC Hub's tool catalog by FAMILY instead of scanning the whole list.' It clearly identifies what the tool returns (_entity=tool_families) and differentiates itself from the canonical tools/list, making its meta-tool role distinct from sibling tools.

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

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

The description gives explicit when-to-use guidance: 'Call this FIRST when you are unsure which tool fits a task.' It also provides an exclusionary rule by stating that tools/list remains canonical and that capability maps should be bound from tools/list, not from here, and references execute_plan/get_changes for refresh.

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

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

Annotations already cover readOnly/idempotent/non-destructive traits; the description adds meaningful execution behavior: each step is "a real tools/call under YOUR key — same quota..." with no extra data access, a "~40s budget" with "status=not_run" and exact continuation args, and the requirement to "Compose your final answer FROM executed[].result and cite 'DC Hub, dchub.cloud'." No contradiction with annotations.

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

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

Though long, the description is organized into scannable, bolded segments (scope, front-door mandate, mechanics, tier honesty, usage alternatives, limits, output usage) with zero filler. Every sentence carries operational or routing information, and the most critical usage instruction is front-loaded.

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

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

For a complex 11-parameter orchestration tool, the description covers when to use it, how execution works, caps and timeouts, what the envelope contains, how to continue if steps are not run, and how to cite results. The presence of an output schema means return values don't need to be spelled out further.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces key guidance like "Pass the user's question through UNCHANGED as intent" and the cohort tag placement rule, but these already appear in the schema; it adds little beyond what the structured parameter descriptions provide.

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

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

The description states a specific verb and resource: "Unified data-center siting, power-grid capacity and AI-compute infrastructure planner" that "plans AND answers" via one call. It differentiates from siblings by declaring itself "THE FRONT DOOR" for multi-topic questions and explicitly contrasts with plan_query and direct single-tool calls.

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

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

Provides explicit when-to-use guidance: "Use for multi-step questions when you want the answer path run for you" versus "use plan_query instead when you only want the plan to run yourself" and "single-tool questions should call that tool directly." It also directs the agent away from stale training data toward execute_plan for cross-cutting questions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavior beyond annotations: it returns the full file contents as text, describes the CSV and GeoJSON shapes, lists the included fields, and notes the PRO context of the operation.

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

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

The description is dense but every sentence contributes: use case, example, parameter summary, return format, and exclusions. The most important usage guidance is front-loaded, and the sibling distinction is placed at the end where it completes the decision rule without cluttering the opening.

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

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

For a single-parameter, read-only, idempotent export tool, this description covers usage triggers, format choices, output content, and alternatives. The output schema and annotations cover the remaining mechanical details, and no critical gap remains for an agent to call this tool correctly.

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

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

Schema coverage is 100% for the single format parameter, so the schema already carries the parameter meaning. The description adds extra value by specifying the default value ('csv' default), elaborating the GeoJSON use case (GIS tools like QGIS), and demonstrating usage with an example.

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

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

The description gives a specific verb-resource pair ('export saved DC Hub shortlist OUT of the platform') and clarifies the bulk-download nature. It is clearly distinguished from siblings by explicitly saying this is not the in-chat list tool or the save tool.

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

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

It states exactly when to use it ('when a user wants to pull their saved DC Hub shortlist OUT...'), gives a concrete example, and explicitly names alternatives it should not be used for: list_saved_sites and save_site. Format selection guidance for CSV vs GeoJSON is also provided.

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

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

Annotations already declare readOnlyHint and idempotentHint true, so the safety profile is covered. The description adds context by specifying the output format, the 'public summary' nature, and the connector format, which goes beyond the bare structured fields.

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

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

Two sentences with no filler. The tool's action and input source are front-loaded, followed by output format and a useful pointer to an alternative. Every sentence earns its place.

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

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

With one required parameter, an output schema, and read-only/idempotent annotations, the description covers what the tool does, where the id comes from, what it returns, and how to get richer data. No critical gap remains for an agent to invoke it correctly.

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

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

Schema coverage is 100%, and the schema already explains the id is a facility slug from a prior search result with an example. The description repeats the same guidance without adding new parameter semantics, matching the baseline for high schema coverage.

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

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

The description states a specific verb and resource ('Fetch a DC Hub record for an id') and clearly distinguishes it from get_facility, which provides full structured specs. It also names the sibling search tool as the source of the id, so an agent can tell exactly what this tool does.

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

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

It says when to use the tool: for an id returned by the `search` tool, to get a citable public summary. It also explicitly points to the alternative (get_facility or open the url) when full structured specs are needed, making the selection criteria clear.

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

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

Annotations already carry the read-only, idempotent, non-destructive safety profile, lowering the burden. The description adds genuinely useful behavior beyond that: it returns ranked alternatives with similarity_score, match_reasons, and key_differences versus the target, and it clarifies discovery semantics versus scoring/comparison. However, it stops short of disclosing default radius/limit or empty-result behavior, and it does not surface the silent key-stripping behavior that the schema itself flags.

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

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

The structure is sound — use case first, then a worked example, then returns, then exclusions — and the exclusion clause is efficient. But the param-summary sentence is stale and factually wrong against the schema, so one of the four sentences is positively harmful rather than earning its place. Slightly over-packed for what it conveys.

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

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

With an output schema present and 100% param schema coverage, the burden shifts to usage context, which the description covers well: when to use, what it returns, and what to use instead. The critical gap is the inconsistent param list, which could cause an agent to invoke it with invalid arguments (name, capacity_mw) that are silently stripped. For a simple read-only tool this is a notable but not fatal completeness defect.

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

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

Schema coverage is 100%, giving a baseline of 3, but the description's param summary actively misleads: it advertises 'facility_id or name' and 'optional capacity_mw' while the schema explicitly states 'there is no `name` param; an undeclared key is silently stripped' and contains no capacity_mw property at all. It also omits the real optional params match_on and exclude_operator. An agent following the description would pass phantom keys and get them silently dropped.

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

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

The description anchors on a specific verb+resource — discovering alternative facilities similar to one seed facility — and illustrates it with a concrete query example ('Find alternatives to the Ashburn QTS campus for about 50MW.'). It also names what it is not (score_facility, analyze_site, compare_sites), so an agent can distinguish it from siblings at a glance.

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

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

The trigger condition is explicit and front-loaded ('when a user likes ONE specific facility and wants similar nearby options'), and the exclusion clause names the exact alternatives to use instead ('use score_facility or analyze_site' for single-site scoring, 'use compare_sites' for head-to-head short-list comparison). The closing line — 'this DISCOVERS candidates from a single seed facility' — leaves no ambiguity about when to invoke it.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description does not contradict these. It adds valuable behavioral detail: the PDF link is ready-to-open, requires no login, is valid ~7 days, and the report structure via the return object. This exceeds the minimum needed given annotation coverage.

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

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

The description is long but every sentence contributes: when-to-use, an example, parameter semantics, return shape, and alternative routing are all packed in. It is front-loaded with the core purpose and example, though the parameter list could be more readable as structured bullets.

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

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

Given the tool's complexity (10 params, no required, output schema present), the description covers all necessary aspects: input aliases, defaults, return object shape (survey + pdf_report_url), link validity, and when not to use it. The presence of an output schema further reduces the need to document return values, and the description complements rather than repeats it.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema: it highlights that lat/lon are required (even though the schema marks all params optional), gives a typical capacity range (50-500 MW), and explains default behavior for prepared_by ('defaults to DC Hub') and latency_target ('default = nearest real carrier hotel'). It also clarifies aliases (lng/latitude/longitude).

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

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

The description opens with a specific verb and resource: 'generate a SHAREABLE, branded multi-page Site Analysis PDF for ONE lat/lon'. It explicitly contrasts with 'not just a score' and later names the sibling analyze_site, so an agent can immediately distinguish it from related tools.

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

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

The description states exactly when to use it ('when a user wants a SHAREABLE... PDF'), provides a concrete example, and closes with the exclusion: 'For just the numeric suitability score (no PDF), use analyze_site instead.' No inference is needed.

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

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

Annotations already establish read-only/idempotent safety, but the description goes further: it discloses that the roster is backend-owned and changes, that statuses are 'CURATED EDITORIAL claims, not measurements', that as_of is null, and that relying on an enumerated list can produce stale results. This is exactly the kind of contextual behavior an agent needs.

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

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

The description is front-loaded with the core purpose and then layers critical caveats. It is longer than strictly necessary, with emphatic formatting and repeated warnings, but every sentence contributes a distinct behavioral or usage point rather than padding.

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

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

With no parameters, an output schema present, and annotations covering safety, the description supplies the remaining essential context: what the response represents, how to interpret statuses, why lists go stale, and which sibling tool to use instead. Nothing critical is missing.

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

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

There are zero parameters, so the baseline is 4. The description adds no parameter documentation because none is needed, and it instead clarifies the response shape (platforms[] array, status values, as_of null), which is appropriate for a no-input tool.

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

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

The description states a specific verb and resource: it is a 'curated roster of the AI platforms and agent frameworks' and explicitly answers the question 'which AI platforms can connect to DC Hub'. It also clearly distinguishes itself from telemetry tools by framing itself as a capability index rather than live measurement.

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

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

The description gives explicit when-to-use guidance ('Answers which AI platforms can connect to DC Hub'), explicit when-not-to-use guidance ('Do NOT use for platform uptime or feed health'), and names the alternative tool (get_backup_status). This leaves little to inference.

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

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

Annotations already cover readOnly/idempotent/destructive safety, and the description adds meaningful behavioral nuance: that a feed reporting 'unknown' has NOT been measured and is not equivalent to healthy, and to read health before trusting figures. It also discloses that the scope is exactly what /api/health/data-freshness serves, with nothing wider. This exceeds what annotations convey.

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

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

The description is somewhat long but well organized: output structure, semantic caveat, the question it answers, and scope/exclusion. Each sentence earns its place; the 'Try: get_backup_status' is slightly redundant but harmless. A small deduction for verbosity, but still tightly written.

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

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

For a tool with zero parameters and a read-only verdict, the description fully specifies the return shape (per-feed rows with health, record_count, refresh_interval, scheduler, and a summary rollup), the important interpretation of 'unknown', and the boundary against get_changes. There is no practical information an agent needs to call it correctly that is missing.

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

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

The tool takes zero parameters, and the input schema is empty, so the baseline is 4. The description doesn't need to clarify parameter syntax; it focuses on output and usage, which is appropriate for a parameterless read-only endpoint.

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

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

The description names a specific resource and verb: 'Per-feed freshness for the DC Hub ingest layer' with one row per feed, and answers a concrete question ('are any of your sources stale right now'). It also explicitly differentiates from siblings by saying 'Do NOT use for the freshness of one dataset (use get_changes)', so an agent can tell it apart from get_changes and similar tools.

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

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

The description gives explicit when-to-use ('Answers "are any of your sources stale right now"') and when-not-to-use with a named alternative ('Do NOT use for the freshness of one dataset (use get_changes); this is ingest health, not content'). This leaves no ambiguity about when the tool is appropriate.

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

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

Annotations already declare readOnly and idempotent; the description adds conditional portfolio behavior for keyed callers with saved sites, the cache-and-pass-back generated_at workflow, and the default 24h window — all beyond the structured annotations. No contradictions.

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

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

Long but every phrase earns its place: definition, return categories, conditional behavior, parameter syntax, use cases, example. Front-loaded with 'Incremental sync' and organized with dashes and line breaks.

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

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

Covers what it returns, conditional portfolio block, parameter usage, caching recommendation, and example call; an output schema exists for field-level detail. There is no meaningful gap for agent invocation.

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

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

Schema already covers both parameters (100% coverage), so baseline is 3; description adds the workflow of caching generated_at and passing it back as since, and gives a concrete example (since=7d), which is extra semantic value beyond the schema.

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

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

States 'Incremental sync — what changed in DC Hub since a timestamp' with a specific verb and resource, and enumerates the return categories. This clearly distinguishes it from siblings like get_news or fetch by its delta scope.

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

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

Gives concrete trigger use cases ('what changed since I last looked', 'anything new this week I should know about') and explains it replaces re-fetching everything. It does not explicitly name sibling alternatives or exclusion conditions, so it stops short of full routing guidance.

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

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

Beyond the readOnly/idempotent annotations, the description discloses data provenance (USGS ASCE 7, NOAA via ACIS), a strict no-estimation policy, explicit unavailable states for missing data, and radius-dependent failure behavior. This gives the agent a strong mental model of side effects and edge cases.

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

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

The description is long but information-dense and front-loaded with purpose and scope. Every sentence earns its place, especially the grounding, example call, return shape, and exclusions. It could be slightly more scannable with structure, but it is appropriately sized for the tool's complexity.

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

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

Given the output schema exists, the description still covers the main return sections, failure modes, data sources, geographic limitations, and alternatives. It is complete enough for an agent to select and invoke the tool correctly, including knowing what happens when data is missing or the site is outside the US.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful usage context beyond the schema: the concrete example invocation, the purpose of radius_km as a station-snapping distance, and the consequence of exceeding it. This lifts it above baseline but doesn't add deep format details for every parameter.

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

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

The description states a specific purpose: providing seismic and climate intel for a lat/lon, tied to structural bracing and cooling design. It clearly names the resource and distinguishes itself from related tools like get_disaster_risk and get_composite_site_score.

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

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

It explicitly says 'Use when' with a concrete use case, and gives alternatives: 'For natural-hazard ratings use get_disaster_risk; for one blended verdict use get_composite_site_score.' It also explains scope limitations for non-US locations and radius behavior, so an agent knows when this tool is or isn't appropriate.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description goes well beyond these by disclosing key behavioral traits: it 'never imputes a missing one', water is 'unavailable' only outside basin coverage 'never faked', market/DCPI is v1-unavailable, and it only scores over VALIDATED factors. It also gives an explicit example call. This provides rich behavioral context that annotations don't cover, making the tool's operation transparent.

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

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

Though the description is long, it is information-dense with zero waste. The first sentence front-loads the core purpose and scope, then immediately contrasts with siblings, explains coverage behavior, gives a concrete example, lists the return object fields, and ends with explicit routing to alternatives. Every sentence earns its place, and the structure is logical and scannable.

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

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

The tool has an output schema that covers return values, so the description doesn't need to explain them in depth. The description covers the key behavioral nuances (never fakes, validated-only factors, conditional confidence), the exact alternative tools, and a working example. Given the complexity of the scoring logic and the large sibling set, the description is thoroughly complete — an agent has everything needed to invoke it correctly.

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

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

Schema description coverage is 100% for all 6 parameters, so the schema already documents each param (aliases, units, ranges). The description adds a concrete example call (lat=33.45 lon=-112.07 state=AZ) that illustrates usage, and clarifies that lat/lon are required in practice despite optional schema flags. This adds marginal value beyond the schema, so a 4 is appropriate per the baseline-plus-extra rule.

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

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

The description states a specific verb+resource+scope: 'ONE honest 0-100 site suitability/risk verdict for a lat/lon WITH an explicit per-factor coverage map'. It clearly distinguishes from siblings by contrasting with analyze_site (full raw data dump) and naming the exact alternatives. An agent can immediately know what this tool does without opening the schema.

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

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

The description gives explicit when-to-use ('Use when a user wants ONE honest 0-100 site suitability/risk verdict'), when-not-to-use ('Unlike analyze_site...', 'market/DCPI is v1-unavailable (use rank_markets)'), and names specific alternatives: analyze_site for full data, compare_sites for 2-4 sites, rank_markets for whole-market ranking. It also explains the coverage logic (validated factors vs. unavailable). This is a model of usage guidance.

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

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

Goes well beyond annotations by detailing the exact return object, fallback behavior when context does not match, and the critical caveat that free text does not parse. Annotations already declare readOnly/idempotent/destructive hints; the description adds edge-case behavior and response shape without contradiction.

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

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

The description is long but every sentence earns its place: purpose, example, parameter rule, return contract, non-matching behavior, and exclusions. It is well-structured and front-loaded with the main intent, with no filler.

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

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

For a tool with one parameter, rich annotations, and an output schema, the description fully covers the invocation contract, the edge case of invalid input, and the key exclusions. An agent has all necessary information to select and call this tool correctly.

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

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

Though schema coverage is 100%, the schema's parameter description is misleading ('Free-text description...'), while the tool description corrects it by enumerating the four literal accepted categories, giving an example call, and explaining the null/generic consequences of invalid input. This is essential meaning that the schema fails to provide.

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

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

The description clearly states a specific use case: obtaining a ready-to-quote description of DC Hub in one of four categories plus a live top-ranked market pocket. It distinguishes itself from siblings by naming analyze_site, rank_markets, and site_selection_canvas, so an agent can immediately tell where this tool fits.

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

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

Explicitly states when to use the tool (descriptive category lookup) and when not to use it (single lat/lon, single-criterion ranking, open-ended siting questions), naming the exact alternative tool for each exclusion. It also describes behavior for invalid context, preventing misuse.

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

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

The annotations already establish that this is read-only, non-destructive, and idempotent. The description goes well beyond those by disclosing that results come from a live authoritative FEMA dataset, are never estimated, are county-level, and that non-US points return coverage=unavailable. This materially helps the agent reason about results and edge cases without contradicting the annotations.

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

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

The description is dense but well-organized: use case, data source, example, return semantics, resolution, and alternatives. It is front-loaded with the most decision-relevant information. The main minor inefficiency is that the return-structure summary partly duplicates what an output schema would already provide, but the high-level semantic notes (e.g., 0-100 higher=worse) still earn their place.

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

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

For a geospatial hazard tool, the description covers everything an agent needs: input coordinates, hazards included, data provenance, geographic coverage constraints, county-level resolution, output semantics, and sibling alternatives. The rich output schema handles structural return details, and the description supplies the interpretive and routing context on top.

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

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

Schema description coverage is 100%, so the parameters are already documented in the input schema. The description adds a concrete example and implicitly signals that lat/lon are needed, but it doesn't add substantially new meaning beyond the schema. The baseline-3 score is appropriate because the schema carries the parameter-documentation load.

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

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

The description opens with a specific, actionable use case ('Use when a user wants the natural-hazard / disaster risk for a lat/lon'), names the specific resource (FEMA National Risk Index), and lists covered hazard types. It also clearly distinguishes itself from nearby sibling tools by naming get_water_risk and get_composite_site_score, so there is no ambiguity about what this tool uniquely provides.

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

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

The description gives an explicit when-to-use statement and an explicit when-not-to-use (or use-alternative) statement: chronic water stress → get_water_risk; blended site verdict → get_composite_site_score. It also clarifies geographic coverage limitations and provides a concrete example invocation, so an agent knows exactly when and how to deploy the tool.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds valuable behavioral context: attribution requirement to DC Hub (CC-BY-4.0), the live/real-time nature of the data, and the 'one round trip, no planner overhead' operational characteristic.

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

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

The description is front-loaded with the most important routing decision and packs a lot of useful context into a dense block. It is somewhat verbose and repeats the 'live price' concept a few times, but it earns its length given a large sibling set and the need to prevent misuse.

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

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

The description covers purpose, when to use, when not to use, exact parameter guidance, an example, return fields, and attribution. Since an output schema exists, the return shape is already structured, so no additional return documentation is needed.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds requiredness for iso despite the schema's required list being empty and gives a concrete example: iso=ERCOT. It does not add meaning for state or data_type beyond what the schema already describes, which is fine.

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

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

The description clearly states the specific verb+resource: live energy pricing for the 7 US ISOs, including retail rate, wholesale/LMP context, natural-gas price, and grid status. It also distinguishes itself from sibling tools by name, such as get_grid_data, get_grid_intelligence, and get_gas_economics.

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

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

The description gives explicit when-to-use and when-not-to-use guidance, including a front-door check routing to execute_plan for siting/market-comparison questions. It names exact alternative tools for excluded cases: get_grid_data, get_grid_intelligence, and get_gas_economics, and even provides an example query.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description does not need to restate safety. It adds useful behavioral details beyond annotations: returns exactly one full facility, includes peer facilities nearby, and lists the specific metadata categories covered. It also communicates the tool is a targeted lookup, not a search.

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

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

The description is three sentences but packs the return fields, use cases, example calls, and the key exclusion into a tight structure. No sentence is wasted, and the most important information (what it returns, one facility only) is front-loaded.

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

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

The tool has a rich output schema, complete parameter documentation, and annotations covering safety. The description adds the missing contextual elements: concrete example calls, explicit scope restriction, and routing to search_facilities. Nothing essential is missing for an agent to invoke it correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by giving concrete example values (equinix-dc1-ashburn, digital-realty-iad8), clarifying that id is a usable alias, and noting that name is the fallback when no id/slug is known. These concrete examples help an agent construct valid calls.

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

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

The description uses a specific verb (get) with a clear resource (one facility) and enumerates exactly what fields are returned. It explicitly contrasts itself with search_facilities by stating it returns ONE facility, not a list, which makes sibling differentiation immediate.

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

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

The description gives concrete invocation examples ('Try: get_facility id=equinix-dc1-ashburn') and an explicit exclusion: 'do NOT use to search or list many facilities (use search_facilities).' This tells the agent exactly when to call this tool and which alternative to use instead.

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

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

Annotations already establish readOnly, idempotent, non-destructive behavior, and the description adds valuable behavioral context beyond that: it discloses that only DCPI market-health has a temporal series, that static dimensions are declared static rather than fabricated, and that missing snapshot history yields coverage:unavailable. This integrity-related transparency is genuinely useful for an agent deciding whether the result is trustworthy.

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

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

The description is long but every sentence earns its place: use case, return value, integrity constraints, parameter clarification, output shape, and alternatives. It is front-loaded with the trigger phrasing and temporal angle, and it contains no filler or repetition.

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

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

With a rich output schema already present, annotations covering safety, and a description that explains the temporal semantics, integrity constraints, parameter relationship, and alternative tools, an agent has everything needed to select and invoke this tool correctly. Nothing important is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds real value by clarifying the OR relationship between facility_id and market, giving example formats for since ('7d'/'30d'), and noting the default. This goes beyond the schema's individual parameter descriptions, though not dramatically so.

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

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

The description states a specific verb ('get'), a precise resource ('facility risk delta'), and the exact conceptual scope: temporal change in a facility's or market's risk profile. It explicitly names the temporal question it answers and contrasts itself with static point-in-time tools, making it clearly distinguishable from siblings.

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

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

The description is explicit about when to use the tool: when a user asks what has changed recently, such as 'has this site gotten riskier lately?'. It also names the alternative tools for point-in-time risk (get_composite_site_score / get_disaster_risk / get_climate_intel) and states what to do when no snapshot history exists, giving the agent clear routing rules.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds valuable behavioral context: the market filter returns ONLY routes touching that metro, and the response is a GeoJSON FeatureCollection ready for Leaflet/Mapbox. This goes beyond the structured metadata without contradicting it.

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

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

The description is longer than average but every sentence carries weight: usage triggers, a worked example, parameter detail, return format, and exclusion guidance are all present. It is front-loaded with the use case and logically organized, though a few clauses could be trimmed without losing meaning.

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

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

Covers usage, parameters, return format, and alternatives. The optional include_sources parameter is only documented in the schema, but that is fine since schema coverage is 100%. No critical operational details like pagination or rate limits are mentioned, but for a read-only GeoJSON tool with high schema coverage, the description is sufficiently complete.

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

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

Schema coverage is 100%, so the baseline is 3. The description enriches this by enumerating all allowed carrier values, the four route_type options, concrete market examples, and the 'either endpoint within ~1.2°' behavior for the market filter. This adds real meaning beyond the schema's brief field descriptions.

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

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

The description states specific verbs and resources: scoring candidate sites for fiber depth, mapping long-haul routes between metros, and assessing dark-fiber availability. It explicitly distinguishes itself from get_facility and analyze_site with clear routing to alternatives.

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

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

Provides explicit when-to-use context ('Use when scoring... mapping... assessing...') and explicit when-not-to-use exclusions ('Do NOT use to count fiber providers at a single facility (use get_facility) or for IX interconnection-density scores (use analyze_site)'). This leaves no ambiguity about selection.

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

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

Annotations already declare read-only/idempotent, and the description adds substantial behavioral context beyond them: PeeringDB is global but thin outside dense US/EU metros, 'unknown' is not 'bad', and carrier_data_coverage determines whether score and single_carrier_risk are null. It explicitly warns not to report a 'none_in_region' site as greenfield, unserved, or build-required—information annotations cannot convey.

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

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

Front-loaded with the core purpose and a concrete example; every sentence earns its place, including the counter-intuitive 'unknown' caveat and sibling exclusions. It is long, but the density of consequential detail—null semantics, coverage distinction, and bucket meanings—justifies the length.

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

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

Covers the full call context: what the tool returns, what each bucket means, when values are null, and when to use alternatives. Even with a rich output schema, the description adds interpretive semantics (e.g., 'unknown' vs 'confirmed', single-carrier risk) that the structured schema cannot express, so an agent has everything needed to call and interpret the result correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds value by explicitly marking lat and lon as required even though the schema's required array is empty, and by tying radius_km to 'reachable fiber carriers' with default and range. It also gives a concrete example invocation with parameter values, reinforcing meaning beyond the schema.

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

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

States a specific verb and resource: 'get the FIBER-READINESS / connectivity verdict for ONE parcel or site (lat/lon)' with concrete outputs (near-net distance, carrier count, single-carrier risk). It also distinguishes itself from siblings by naming what it is not: route mapping and full multi-factor suitability.

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

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

Explicitly scopes usage: 'Use when you need the FIBER-READINESS / connectivity verdict for ONE parcel or site' and gives exclusions with named alternatives: 'Do NOT use to map carrier ROUTES between metros (use get_fiber_intel) or for a full multi-factor site suitability score (use analyze_site).' Also clarifies the critical 'unknown' vs 'no carrier' interpretation, which is essential for correct use.

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

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

Goes well beyond the readOnly/idempotent annotations by disclosing a data-quality withdrawal: the $/MWh layer is no longer returned, gas_to_grid_status carries the reason, and the endpoint previously served physically impossible values. This is exactly the behavioral context an agent needs to avoid misusing cached or derived numbers.

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

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

The core purpose and parameter call are front-loaded, and the withdrawn-feature warning is clearly separated. It is longer than most tool descriptions, but the extra sentences carry important safety caveats rather than filler; a little trimming of the historical explanation would make it tighter.

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

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

For a read-only data lookup with full parameter documentation and an output schema, the definition covers what is returned, what was withdrawn, how to detect it, and which sibling to use instead. No critical information is missing for correct invocation.

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

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

Schema description coverage is 100%, so the schema already documents market and heat_rate_btu_per_kwh. The description only repeats the market=<slug> format with examples and does not add meaning beyond the schema, so the baseline 3 applies.

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

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

Opens with a specific verb and resource: 'Behind-the-meter / gas-fired power inputs for a US data-center market,' enumerating Henry Hub spot, regional basis differential, and delivered industrial + electric gas tariff in $/MMBtu. This precisely identifies what the tool returns and distinguishes it from related data lookups.

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

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

Explicitly states when to use it for gas-fired power inputs and gives a direct exclusion with an alternative: 'Do NOT use for the electricity grid fuel mix (use get_grid_data).' It also forbids quoting withdrawn $/MWh values or deriving them silently, which is actionable guidance for an agent.

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

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

The annotations already list readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description adds substantial behavioral context: the withdrawal/restoration history, the three repaired defects, the UNSCORED-vs-low-score semantics, and the explicit guidance that UNSCORED means absence rather than a poor score. It also names the gas_price_series field as a way to see which EIA series priced the state.

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

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

The description is long, but most sentences earn their place because the tool history is genuinely complex. It is front-loaded with the core purpose, then gives correction history, data-interpretation warnings, and sibling routing. Some redundancy exists between the main description and the state parameter description, so it is not maximally concise.

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

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

For a tool with withdrawal/restoration history, scoring semantics, and a sibling-data boundary, the description is remarkably complete. Combined with the output schema, the agent has enough context to call the tool correctly, interpret UNSCORED results, avoid comparing incompatible values, and route pipeline-related queries to get_gas_intelligence.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description and state parameter go beyond the schema by explaining what the response includes (DCGI score, verdict, gas_price_series, unscored_reason) and how to interpret UNSCORED. The limit parameter receives no additional description, but that is acceptable given the schema already defines its range and behavior.

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

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

The description opens with a precise verb-plus-resource statement: it provides the per-US-state Data Center Gas Index (DCGI) natural-gas suitability score. It also clearly differentiates itself from get_gas_intelligence by stating that pipeline, operator, and parent-midstream data belong to that sibling tool, and it warns that gas-fired $/MWh figures are not restored here.

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

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

The description gives explicit routing guidance: use get_gas_intelligence for pipeline, operator, and parent-midstream data, and avoid treating restored DCGI values as comparable to pre-2026-08-08 figures. It also clearly marks gas-fired $/MWh values as still withdrawn, telling the agent what this tool does NOT cover.

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

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

Annotations already provide readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds far beyond that: the DCGI withdrawal/restoration history, the still-withdrawn gas_to_grid $/MWh, the instruction not to quote cached scores, the honest null-handling of delivered_price, and the warning to read dcgi_status and gas_to_grid_status independently. This is exceptional behavioral disclosure.

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

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

The description is dense and information-rich but overly long and unstructured. It front-loads the use case well, but then dumps a long return-object fragment and a complex index-correction history in a single run-on paragraph. The key warnings ('do not compare pre-2026-08-08 figures', 'do not quote cached DCGI scores') are buried mid-text. Every sentence earns its place, but the lack of paragraph breaks and ordering hurts scannability.

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

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

Given the tool's complexity, rich output schema, and many sibling tools, the description is remarkably complete. It covers the return shape, field semantics, omitted data (gas storage, LNG, firm capacity), data provenance via data_basis, current index statuses, and exclusions. The output schema also exists to document return values, so the description doesn't need to restate them. Nothing critical is missing for an agent to call this tool correctly.

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

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

Schema coverage is 100%, giving a baseline of 3. The description adds value by explaining that 'state' is an alias for 'region' and giving examples of accepted values ('TX' | 'Texas' | 'Virginia'). It does not go into deeper semantics for each field, but the schema already documents both parameters, so the added alias/example clarification justifies a 4.

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

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

The description states a specific verb and resource: answering human questions about gas-fired or behind-the-meter power economics for US data centers. It explicitly names the GAS analogue of get_grid_intelligence and differentiates itself from get_gas_index and get_grid_intelligence. This is a clear, specific purpose that an agent can easily distinguish from siblings.

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

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

The description opens with 'Use when a human asks about gas-fired or behind-the-meter power economics' and gives concrete example user questions. It explicitly states exclusions: 'Do NOT use for electricity grid headroom (use get_grid_intelligence) or the DCGI score alone (use get_gas_index)'. This is excellent when-vs-when-not routing with named alternatives.

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

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

Annotations already signal read-only, idempotent, non-destructive. The description adds meaningful behavioral context: the dataset scope (182k units, 170+ countries), the semantics of pipeline=true being exactly the forward set (announced + pre-construction + construction), and the return shape (summary of total MW by fuel + count by status plus largest units). It does not contradict the annotations.

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

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

Though fairly long, every sentence earns its place: use-case scoping, dataset scale, filter options, return summary, example calls, and explicit exclusions. The key 'when to use' instruction is front-loaded, and the negative routing is clearly placed at the end. Formatting with bold and code examples improves scannability.

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

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

Given 7 optional parameters, no enums, and a large sibling set, the description covers the full decision space: what data is available, how each important filter behaves, what the response contains, and which related tools to use instead in specific situations. An output schema exists, so not detailing every return field is acceptable. An agent has everything needed to invoke this tool correctly.

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

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

Schema coverage is 100%, but the description still adds value by explaining the union semantics of comma-separated fuel values, the exact bbox format (minLng,minLat,maxLng,maxLat), the pipeline filter collapsing multiple statuses, and showing real examples of country and fuel values. This goes well beyond the schema's one-line descriptions.

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

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

The description defines a specific verb plus resource: 'power plants/units WORLDWIDE or in a NON-US country' with both operating and forward pipeline. It explicitly differentiates from US-focused siblings by naming get_grid_intelligence, get_grid_scoreboard, and get_power_pipeline as the alternatives, so an agent can select this tool without ambiguity.

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

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

It gives explicit when-to-use context (worldwide/non-US, all fuels, including pipeline) and explicit when-not-to-use with named alternatives for US grid telemetry/headroom and US planned-generator feeds. It also provides example queries and a concrete recommended call ('Try: get_global_power country=India pipeline=true').

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is clear. The description adds behavioral context beyond annotations: data comes from EIA hourly RTO telemetry, is raw real-time telemetry, is scoped to one ISO per call, and covers a 24h demand curve. This helps set expectations about freshness and granularity.

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

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

The description is dense but every clause earns its place: it states the data scope, source, acceptable values, and key exclusions with sibling pointers. The most important usage constraint is front-loaded, and no filler or repetition exists.

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

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

Given the rich input schema, output schema presence, and annotations covering safety and idempotency, the description provides the remaining necessary context: data source, ISO coverage, raw real-time nature, what not to use it for, and fallback tools. Nothing critical is missing for an agent to select and call this tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by clarifying that iso is effectively required ('Pass iso=PJM (any of the 7)') despite the schema showing 0 required parameters, and by giving concrete metric examples (fuel_mix, demand, demand_curve) and a period example (24h). This extra context helps the agent construct valid calls.

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

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

The description names a specific verb-resource pair: retrieving real-time electricity grid data for seven named US ISOs, with explicit data types (fuel mix, demand, 24h demand curve). It clearly differentiates from sibling tools like get_grid_intelligence and get_energy_prices.

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

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

The description gives explicit when-to-use guidance: use for real-time ISO telemetry, and explicitly says not to use for power-availability, time-to-power, interconnection-queue, or retail/gas price analysis, naming get_grid_intelligence and get_energy_prices as alternatives. It also routes non-US grids to get_grid_scoreboard.

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

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

Annotations carry the safety profile (readOnlyHint, idempotentHint, destructiveHint all safe), so the bar is lower and the description earns full credit for context beyond them. It discloses three critical behavioral traits: market names resolve to their ISO via the DCPI row with a resolved_from block, balancing authorities return only live generation mix while other metrics stay ISO-level, and the two time metrics are non-interchangeable with the queue-wait derivation formula (12 + 0.6 months/GW, clipped 12-66). These are exactly the traps that would corrupt an agent's output. No contradiction with annotations.

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

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

Information-dense but long (roughly 280 words). It is front-loaded with the trigger use case and example, and every clause earns its place — the alias list, BA caveat, metric warning, and sibling routing are all high-value. The return-field enumeration is partially redundant with the output schema, but it anchors the essential time-to-power vs queue-wait warning, so the length is largely justified.

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

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

For a high-complexity tool (4 params, three input modes, a counterintuitive resolution quirk, and a metric disambiguation), the description covers the critical decision points: valid inputs, market resolution behavior, BA data-scope limits, metric non-interchangeability, and when-not-to-use. Gaps are minor: no error behavior for invalid regions, and the schema's '0 required params' label sits awkwardly against the description's implication that a region or market is needed.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real value beyond the schema: it groups iso/region/region_id as aliases, enumerates the full 7-ISO valid set plus 40+ balancing-authority examples, documents the special PJM-DOM zone for Ashburn, and clarifies that market is not an alias but a name resolved to a larger ISO. The only reason it isn't a 5 is that the schema already covers much of the same ground.

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

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

The description names a specific verb+resource+scope: 'the flagship grid-headroom + interconnection-queue brief for one ISO', anchored to a concrete trigger question ('can I get N MW of power in <ISO> and how long will it take?') and a worked example call. It distinguishes itself from siblings by name ('Do NOT use to compare 2+ ISOs side-by-side (use compare_isos) or for the global greenest-first ranking (use get_grid_scoreboard)').

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

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

Explicit when-to-use guidance is given as a verbatim user-intent trigger, and explicit when-not-to-use exclusions name the exact sibling alternatives (compare_isos, get_grid_scoreboard). The market-vs-ISO edge case is also covered with a warning that the figures describe the ISO, which is larger than the market named — leaving no ambiguity about interpretation.

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

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

Beyond the readOnlyHint/idempotentHint annotations, the description discloses important behavioral traits: freshness is not uniform, mix and demand have separate clocks with mix_age_hours and demand_vs_mix_lag_hours fields, some grids report no gas share, and Australia/Singapore are unranked in partial_grids. This level of caveat disclosure is exceptional and prevents the agent from misinterpreting stale or partial data.

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

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

The description is long and dense, but it earns its length given the complexity of the data source and the many caveats. It is front-loaded with the core scope and key data, then systematically covers freshness, exceptions, and provenance. Minor redundancy like 'Try: get_grid_scoreboard' and the very long parenthetical enumeration prevent a perfect score, but the structure is purposeful.

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

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

For a zero-parameter tool, the description is remarkably complete: it lists all regions, all metrics, freshness caveats, source attribution, unranked grids, Brazil's missing gas share, and the specific fields to check before narrating results. Given the output schema exists, this provides everything an agent needs to call and interpret the tool correctly.

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

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

The tool has zero parameters, so the input schema is trivial and the description cannot add parameter-level meaning. The baseline for 0-param tools is 4, and the description instead enriches understanding of the returned fields (mix_period, mix_age_hours, freshness_basis, partial_grids, counts_basis), which is appropriate for this parameterless tool.

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

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

The description names a concrete resource ('GLOBAL grid scoreboard') and specifies exactly what it returns: ranked grids with renewable share, gas share, fuel mix, and demand. It also distinguishes itself from sibling tools by explicitly comparing against compare_isos (pairwise) and get_grid_data (single ISO), so an agent can select it unambiguously.

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

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

The description gives explicit when-to-use guidance: 'One call answers which grid worldwide is greenest, or most gas-reliant, for siting a data center?' and explicitly contrasts with alternatives ('vs compare_isos (pairwise) or get_grid_data (single ISO)'). It also gives example queries ('which grid is cleanest right now', 'how is ERCOT doing at this moment'), leaving no ambiguity about when this tool is the right choice.

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

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

Annotations already mark the tool read-only, idempotent, and non-destructive, and the description adds substantial behavioral context: returned values are split by capacity_type, distinct_feeders vs geometry_rows_scanned are never conflated, sample_complete=false indicates a capped read, and out-of-coverage points return an explicit not-published answer rather than a silent zero. No contradiction with annotations.

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

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

The description is front-loaded with the core purpose and critical capacity_type caveat, and nearly every sentence carries substantive information. However, it is very long and dense, enumerating 18 utilities and including extended examples and exclusions, which pushes the limits of conciseness even though the content is relevant.

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

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

Given the tool's complexity, optional parameters, and output schema, the description is remarkably complete: it covers coverage geography, return structure, failure behavior, capacity_type interpretation, invocation modes, and sibling disambiguation. There is no critical context an agent would need that is absent.

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

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

Schema description coverage is 100%, and each parameter is already well documented, so the baseline is 3. The description does reinforce the critical capacity_type semantics and call modes, but most of that meaning is already present in the input schema. It adds minimal new parameter-level detail beyond what the schema provides.

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

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

The description opens with a specific verb+resource: 'Utility-PUBLISHED feeder hosting capacity — the MW a NAMED distribution feeder can actually take.' It clearly distinguishes this tool as the distribution FEEDER layer and names what it is not, separating it from siblings like get_grid_intelligence and get_interconnection_queue.

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

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

Usage guidance is explicit and actionable: it lists the three call modes (lat/lon, utility/market, no args), states the questions it answers, and explicitly says which sibling tools to use instead for transmission proximity, interconnection queues, and retirement headroom. This is far beyond a vague 'use for capacity questions.'

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

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

Annotations already declare readOnlyHint and idempotentHint, so the description adds value by revealing the output nature: raw nearby assets joined to HIFLD/EIA, with distance+capacity per asset. It doesn't contradict annotations and gives useful context about what the tool does with the data.

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

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

Dense and front-loaded: the first sentence covers purpose and scope, followed by output details, example questions, an example call, and a guardrail. Slight redundancy with the title, but the structure is efficient and every sentence earns its place.

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

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

Combined with the rich input schema and output schema, the description covers the asset layers, return metrics, data provenance, and the key sibling distinction. It doesn't mention default radius_km, but that is delegated to schema annotations and is a minor omission for a tool this well specified.

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

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

Schema coverage is 100%: every property has a description. The description adds a worked example and explains radius_km as configurable, but it does not add per-parameter meaning beyond the schema. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific verb+resource: 'Nearby infrastructure for a location' and enumerates four asset categories with specific metrics (count, max voltage_kv, distance, capacity). It also explicitly distinguishes itself from analyze_site by labeling its output as raw assets rather than a scored verdict.

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

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

Provides a concrete example invocation and a direct exclusion: 'do NOT use for a single scored site-suitability verdict (use analyze_site)'. This routes agents to the correct sibling for scoring while conveying this is the geo-spatial lookup tool.

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

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

Annotations already establish readOnly, idempotent, and non-destructive behavior. The description adds valuable behavioral context: 'real-time', the aggregation components, and the specific outputs (index value, percentile rank, trend direction, component scores). It does not overstate side effects and aligns with the annotation safety profile.

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

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

The description is front-loaded with the core definition and returns, and every sentence adds useful detail. It is slightly longer than necessary due to repeated 'one composite health number' language and both an example and a disambiguation clause, but the structure remains clear and scannable.

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

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

The description covers output semantics, example usage, and sibling tool routing, and an output schema exists, so return-value documentation is not required. However, the missing/contradictory parameter mechanism for selecting a market leaves a fundamental gap: the agent knows what the tool does but not how to formally supply the required market context.

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

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

The input schema declares zero parameters, yet the description suggests calling 'get_intelligence_index market=northern-virginia' and describes the tool as returning a score 'for a market'. This mismatch means an agent cannot reliably construct a valid call from the schema, and the description's parameter guidance actively conflicts with the structured input definition.

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

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

The description names a specific resource ('composite market health score'), a concrete scale (0-100), and the underlying components, so an agent knows exactly what the tool computes. It also explicitly contrasts itself with get_market_intel and rank_markets, making sibling differentiation strong.

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

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

The description gives a concrete invocation example, states what questions it answers, and explicitly says when NOT to use it by naming two alternatives: get_market_intel for the full metric set and rank_markets for ranking multiple markets. This is clear and actionable routing guidance.

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

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

Even with readOnly/idempotent/non-destructive annotations covering the safety profile, the description discloses critical dynamic behavior beyond those: 'The `projects` field CHANGES SHAPE with the call' and gives the specific array-versus-summary-object shapes. It also surfaces ERCOT-specific data provenance and the null behavior for other ISOs, which an agent must know to interpret results safely.

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

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

Though dense, the description is carefully ordered: core function, key exception, sources, parameter usage, shape-change warning, use cases, and exclusions. The starred shape warning is front-loaded at the exact point where it matters, and every sentence carries load-bearing information with no filler.

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

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

With an output schema present, the description need not enumerate return fields, but it still covers the purpose, the parameter's effect, the only ISO with non-null data_center_gw, the provenance, and explicit sibling routing. The tricky `projects` shape change is called out even though it risks being redundant with an output schema, which demonstrates thoroughness for callers.

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

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

The single iso parameter is already fully documented in the schema with allowed values and omit behavior (100% coverage), so the baseline is 3. The description adds value by linking the parameter to the dynamic shape of `projects` — 'with iso= it is an ARRAY...; with iso omitted it is the all-ISO SUMMARY OBJECT' — giving the parameter semantic weight beyond the schema's field listing.

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

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

The description opens with a crisp verb+resource+scope: 'ISO interconnection queue snapshot: total queued GENERATION capacity ... per ISO.' It immediately distinguishes itself from sibling tools by name (get_grid_intelligence, grid_transition_radar) and specifies the exact fields returned, so an agent can tell what it does without opening the schema.

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

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

Usage guidance is explicit and bidirectional: 'Use for queue-depth site-selection and AI/data-center-load saturation intel' and 'Do NOT use for a single-site time-to-power read (use get_grid_intelligence) or forward-looking emergence (use grid_transition_radar).' It also instructs how to vary the call ('Pass iso=ERCOT ... to drill down'), leaving no ambiguity about when to choose this tool.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, but the description adds substantial behavior beyond that: greedy priority-order filling under max_tokens budget, per-section token counts with as_of timestamps and citable URLs, a used_tokens/omitted response shape, and an explicit citation requirement ('Cite DC Hub'). This meaningfully enriches the agent's model of what a call does and what it will get back.

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

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

The description is long but dense and well-ordered: use case, package contents, example, params, return shape, exclusions, citation. The use case is front-loaded. Minor deduction because the 'Params:' block largely duplicates what the schema already specifies at 100% coverage, and the parenthetical listing of contents is somewhat run-on; still, nearly every sentence earns its place.