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

Goes well beyond the annotations by disclosing the consent gate, the identity prerequisite chain (claim_free_key then bind_email, or an OAuth connection), the once-per-terms-version recording semantics, the required accept_terms=true, and that the acceptance lands in DC Hub's lead register with a returned accepted flag and terms version.

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

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

Dense but front-loaded: the consent gate and trigger come first, exclusions last. Every clause carries information, though the single long paragraph could be split for faster scanning.

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

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

For a gated consent-write tool with an output schema and safety annotations already present, all the missing pieces an agent needs are supplied: prerequisites, trigger condition, refusal condition, side effect, and return values.

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

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

Schema coverage is already 100%, so the baseline is 3, but the description adds real meaning: accept_terms is framed as an affirmative human-consent switch rather than a generic boolean, and terms_version is tied to what source_capacity reports. The linkage to the prerequisites is useful context the schema alone doesn't convey.

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

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

States a specific verb and resource ('records that acceptance' of DC Hub's introduction terms) and immediately scopes the effect: it unlocks Capacity Source listing details. It explicitly separates itself from request_capacity_intro and source_capacity, so an agent can route correctly without opening any schema.

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

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

Gives the exact trigger ('Call it when source_capacity returns a listing locked with access.reason terms_acceptance_required'), the hard precondition ('Use ONLY after your human has read and agreed'), an explicit prohibition ('never on your own judgement'), and named alternatives for the two adjacent intents.

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, non-destructive behavior, so the description only needs to add context beyond that. It does: refresh cadence (Fridays 14:00 UTC) and the composition of returned signals (facility_count, operator_count, deployable_mw, hyperscale_ready, rack density, cooling type, composite depth+diversity+power). It does not state coverage limits or data staleness caveats, but the added freshness/return context is solid.

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

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

Front-loads what the index is and what it returns before the usage and exclusion clauses, and every sentence carries routing or field information. It is dense and one clause longer than strictly needed, but not padded.

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

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

An output schema exists, so return values need no prose elaboration, and the description still summarizes them. Combined with use cases, refresh cadence, and sibling disambiguation, an agent has everything needed to select and call it correctly.

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

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

Schema description coverage is 100%: limit and horizon are both documented with type, range, and defaults. The description mentions 30/60/90 days but adds no format, syntax, or edge-case meaning beyond what the schema already carries, so baseline 3 applies.

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

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

States a specific verb, resource, and scope: ranking data center markets by 100MW AI-training deployability over 30/60/90-day horizons. It explicitly distinguishes itself from rank_markets (general ranking) and grid_transition_radar (forward grid emergence), so an agent can route correctly without opening a schema.

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

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

Gives explicit positive use cases (AI capex planning, GPU cluster siting, hyperscaler deal forecasting), a redirect for grid power (DCPI via rank_markets ai_ready), and two explicit do-not-use cases with named alternatives. Nothing is left to inference.

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

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

Annotations already declare readOnly, idempotent, non-destructive, non-open-world, and the schema describes the aliases, so much of the surface is covered. The description does add genuinely non-derivable behavior: hosted coverage rolls out by market (Loudoun VA first) and an out-of-coverage point returns an honest 404 with a coverage list rather than guessing. A 3 reflects real additive context on top of a fully annotated read tool without going much beyond coverage semantics.

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 the two input modes are front-loaded in the first clause, followed by coverage behavior, return shape, handoff, and alternatives. It is dense but well ordered; the enumeration of return fields is partly redundant given an output schema exists, which keeps it from a 5.

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

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

For a tool with an output schema and full annotation coverage, the description covers the remaining unknowns: coverage scope and its rollout, the 404-no-guess guarantee, what representative_point is and why it is not the geometric center (anchor poisoning), and downstream handoff to analyze_site/get_water_risk. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description nonetheless adds the OR logic between geometry and lat/lon (omit geometry to force hosted lookup) and the pass-through role of capacity_mw into the site_evaluation_handoff. The MultiPolygon 'one envelope' note and alias confirmations go slightly beyond the schema field text.

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

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

States a specific action (structured read of a parcel boundary) and two distinct input modes (own GeoJSON, or lat/lon lookup into a hosted parcel layer). It explicitly names the siblings it is not — analyze_site for general site scores and get_refined_queue for the interconnection-queue set — so an agent can discriminate without opening schemas.

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

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

Gives an explicit when-to-use ('when you HAVE a boundary or a point on a specific parcel'), plus when-not conditions routed to named alternatives (analyze_site, get_refined_queue). It even notes queue rows carry no parcel identity so they never auto-join, preventing a wrong tool 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?

Far exceeds the annotations (readOnly/idempotent/non-destructive). It discloses the tiered access model (keyless vs free key vs paid plan), that capacity_mw adds capacity_context without moving overall_score, the missing_coordinates error, the candidate_expired fail-closed behavior, and instructs showing human_message on partial results — behavior an agent could not infer otherwise.

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, opening with the trigger condition before mechanics. It is long, and a few clauses (e.g. the worked example, the docs URL) verge on narrative, but nearly every sentence carries operative information.

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

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

With an output schema present, the description needn't enumerate return fields, and it instead covers the gaps that matter: auth-tier gating, error signals, candidate_id precedence, and the partial-result instruction. Complete for a 12-parameter analysis tool.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds real semantics: lat AND lon must both be present or missing_coordinates fires, capacity_mw does not affect overall_score, and location is a market-centroid read rather than the named parcel. These go beyond the schema field descriptions, though some overlap remains.

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 — evaluate whether a site/coordinate works for a data center — and renders the 0-100 composite plus sub-scores. It names the sibling it depends on for coordinates (get_facility, search_facilities) and the preferred candidate_id source (get_refined_queue), so an agent can place it among 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?

Explicit when-to-use: 'whenever the user asks whether a specific site or coordinate works for a data center' and 'when the user has one location.' It also gives the decision rule between lat/lon and location (market-level read) and the preferred candidate_id path, so the agent knows which input mode to pick.

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

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

With annotations covering only the mutation profile (readOnlyHint=false, idempotent=false), the description carries the remaining burden well: what binding does and does not confer (recoverability yes, durable identity unproven), the free-tier rate change (50 calls/day), transactional-only email use with opt-in marketing, and graceful failure ('if the email can't be accepted, the key keeps working'). This is unusually rich 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?

A ~400-word wall of text with a unicode banner, dated cohort statistics ('0 of 3 mature identities, 2026-08-12'), and repeated warnings about fake emails. The genuinely actionable instructions are interleaved with research narrative, so it is neither front-loaded nor economical; several sentences do not earn their place.

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

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

An output schema exists, so return values need not be explained. The description covers consent/purpose, the failure fallback, tier implications, and the marketing default — everything an agent needs to invoke this correctly and handle edge cases. Nothing material is missing for a 3-parameter mutation tool.

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

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

Schema coverage is 100%, so all three parameters are already documented in the schema, including the placeholder-rejection rule and the api_key omission behavior. The description largely restates these constraints (fake emails rejected, api_key optional, marketing_opt_in default false) rather than adding syntax or format detail beyond them. Baseline 3 applies.

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

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

The description states a specific verb+resource ('Tie your DC Hub key to your human's email') and scopes the benefit precisely: recoverability and free-tier restoration. It also distinguishes itself from the sibling 'recover_my_key' and explains the OAuth alternative path. However, the core purpose is buried under layers of cohort statistics and durability caveats, so an agent must dig to find it.

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-call ('Call this once your human shares their email'), explicit when-NOT-to-call ('If your human hasn't shared an email, ask them first — don't call this tool with a made-up value'), explicit mid-task pause script, and an explicit condition for the alternative path (OAuth requires a 401 challenge). Alternatives and preconditions are all named.

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

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

Goes well beyond the annotations by disclosing the return payload (key + connect_url with key embedded), the exact rate tiers (previews + 2 full answers/tool/day, 50/day with email), the non-idempotent re-mint warning, and the 401 WWW-Authenticate sign-in-vs-key decision. This is behavior an agent cannot infer from readOnlyHint/idempotentHint alone.

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

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

Front-loads the trigger condition and stays dense, though the OAuth/challenge passage is slightly digressive. Nearly every sentence carries routing, rate, or state-management value.

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

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

With an output schema present, return values needn't be fully explained, yet the description still names connect_url and its significance. Combined with rate limits and the sign-in fallback, an agent has everything needed to invoke this correctly.

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

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

Schema coverage is already 100%, so baseline is 3; the description adds real semantics on top by instructing to ask for the email first and pass it only if the user typed it, explaining why (recoverability). client_name remains schema-only but is self-explanatory.

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 ('Mints a free key and returns it plus connect_url') and immediately scopes it against siblings by naming recover_my_key and execute_plan as the alternatives for lost keys and multi-step work.

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 ('Call when the user wants more DC Hub access than keyless allows or asks for a key'), a when-not ('no key is needed to start'), and routing to recover_my_key for lost keys plus execute_plan for the follow-up question.

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

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

Annotations only cover the safe-read profile (readOnly/idempotent/non-destructive); the description adds genuine behavioral context beyond that: a fail-closed candidate contract where expired/unknown ids are dropped AND declared, the distinction between physics floors (unbeatable) and inferred estimates (route_factor 1.4), the confidence_v provenance tier, and an explicit 'do NOT treat this as an engineered latency quote' caveat.

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

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

Front-loaded with purpose, then contract, then return shape, then exclusions; each block is dense with distinct information. It runs long and some of the assumptions/provenance explanation could be trimmed, but almost every sentence earns its place.

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

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

For a 4-parameter analytical tool with an output schema, the definition covers input contracts, the physics-vs-inference caveat, provenance tiers, and failure behavior. An agent has everything needed to call it correctly and to relay results honestly.

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 real semantic value on how parameters interact — candidate_ids resolves to FROZEN mint coordinates (zero transposition), cand_… tokens may be mixed into the sites string, and the example pairs max_latency_us=2000 with a sync-replication budget — though it largely restates schema text.

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 with scope: 'Physics-bounded latency clustering for 2-8 sites — returns viable low-latency clusters and pairwise RTT floors.' It explicitly distinguishes itself from siblings plan_fiber_leadin (route corridors) and get_fiber_readiness (single-site score), so an agent can pick it without opening schemas.

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

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

Gives an explicit when-to-use ('Use when your human wants to know which of N candidate sites can form a synchronous / low-latency cluster (sync replication, active-active pairs, HPC pods)') and frames it as deterministic pruning BEFORE detailed routing. It names two alternative tools and the scenario each covers, leaving nothing to inference.

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

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

Annotations already declare readOnly, idempotent, non-destructive, openWorld, so the safety profile is covered. The description adds real value beyond that: it caps input at 2-4, sketches the returned comparison shape, and warns that avg_time_to_power_months and avg_queue_wait_months are DIFFERENT measurements that must be quoted by name. It does not add operational constraints like rate limits or auth, so a 4 rather than a 5.

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

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

Front-loaded with the usage trigger, then example, params, returns, and exclusions in a logical order. Slightly verbose: the opening two sentences both restate the 2-4 side-by-side comparison, and the full return-key list is largely redundant given an output schema 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 a single required parameter, full schema coverage, and an output schema, the description supplies everything an agent needs: when to use, when not to, the alternative tools, input bounds, and a meaningful caveat about two similar-sounding metrics. Nothing required for a correct call is missing.

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

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

Schema coverage is 100%, so the schema already documents the single 'isos' parameter, its 2-4 range, example, and valid set — this is the baseline-3 case. The description reinforces the same facts but adds no new syntax. It also introduces a value mismatch worth noting: the description lists 'ISO-NE' while the schema enumerates 'ISONE'.

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

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

States a specific verb ('compare') and resource ('2-4 US ISO grids side by side'), names the compared dimensions (fuel mix, demand, renewable/gas share, queue depth, time-to-power), and explicitly names the siblings it is NOT (get_grid_scoreboard, get_grid_intelligence). An agent can distinguish it without opening any schema.

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

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

Gives an explicit trigger ('whenever the user asks to compare two to four US grids side by side'), a concrete example invocation, and explicit exclusions routing to the correct alternatives ('Do NOT use to rank ALL grids globally — use get_grid_scoreboard' and 'for the single-ISO deep brief — use get_grid_intelligence'). Nothing is left to inference.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds genuinely new behavioral context: the tiered gating (keyless gives verdict+power bands only, a free key adds names/counts, full scores/figures and the pick require a paid plan). That auth-tier disclosure is exactly the kind of thing an agent needs and cannot get from annotations.

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

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

Front-loaded with the usage trigger, then input format, return shape, gating, and an example. Dense but every sentence carries distinct information; only the gating clause is slightly packed into one long sentence.

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

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

Covers trigger, input format, return content, and paywall behavior, and an output schema already exists to carry return details. Nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is 100%, so all three parameters (sites, locations, capacity_mw) are already documented. The description's 'lat,lon;lat,lon' format note and MW example restate what the schema provides, so baseline 3 is appropriate.

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

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

States a specific verb+resource (compare sites) and clarifies scope: 2-4 candidate locations, returns analyze_site scores side by side plus a recommended winner. This distinguishes it clearly from analyze_site (single site) and rank_sites without opening either schema.

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

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

Gives an explicit trigger condition ('when the user has 2-4 candidate locations and asks which is best for a data center') plus a concrete example. It does not explicitly exclude or name the closest alternatives (rank_sites, find_sites), which keeps it short of a 5.

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

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

Annotations already declare readOnly/idempotent/non-destructive and openWorld=false, so the safety profile is covered. The description adds genuinely useful behaviour beyond that: a cost/verbosity model ('keep the default cheap' via progressive disclosure) and an auth tier gate ('with a paid key, the per-deal autopsy read'), which an agent needs to set expectations. It stops short of stating rate limits or what a free-key caller sees in place of the paid autopsy read.

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 is front-loaded, which is good, but the prose is padded with marketing cadence ('what is the real play?') and the two closing example questions restate the same two intents already covered earlier. Em-dash asides and quoted phrasing make it longer than it needs to be for a 2-parameter read tool.

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

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

An output schema exists, so return values needn't be spelled out, yet the description helpfully names the deal fields (buyer, seller, value, market) plus the DCPI verdict and time-to-power. The progressive-disclosure contract and paid-key gate are both disclosed. The one loose end is that the paid-tier 'per-deal autopsy read' is described only in vague labels (land/power option vs near-term build vs queue gamble) rather than its concrete output.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema, and the description largely mirrors it (count-only default, top-2 summary, full cited set). It adds only marginal framing ('cheapest', 'escalate only for deals you're drilling into'). 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 (track) and resource (data-center M&A / capex deal flow) with a distinctive twist: the DCPI grid-reality verdict overlaid per market. This lets an agent separate it from siblings like list_transactions and hyperscaler_deals, which presumably lack the DCPI overlay. The example questions ('who is actually buying data centers right now', 'what is the real play behind this deal') pin the intended 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?

Clear guidance on the internal escalation lever: default comparables gives only a count, 'summary' gives top-2 grounding signals, 'full' expands the cited set, with the explicit rule 'escalate only for deals you're drilling into.' It gives context for when the tool is the right call (answering deal-flow and market-quality questions) but never names a sibling alternative for when this is the wrong pick over list_transactions or hyperscaler_deals.

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 destructiveHint=true and readOnlyHint=false, and the description goes well beyond them: deliveries stop, the watch cannot be recovered, the cap_ prefix silently redirects to a different object whose alert emails also stop, and a key (or OAuth for cap_ ids) is required. That is exactly the extra behavioral context the annotation bar asks for.

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 destructive action and consequence, then branching behavior, sourcing, and the anti-use case. Dense but nearly every clause carries information; the quoted 'stop watching this' is mildly decorative but serves intent routing.

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

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

An output schema exists so return values need not be described. Everything an agent needs before calling — irreversibility, credential requirement, sibling source of the ID, cap_ special case, and the no-pause caveat — is present.

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 a single parameter, so baseline is 3, but the description adds real semantics the schema lacks: the cap_ prefix changes the target object and the credential mode, and the ID's provenance is given. Not a 5 only because no format/validation detail is offered for the identifier itself.

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 ('permanently retire a registered standing intent (webhook watch) by intent_id') and immediately distinguishes the cap_ variant, which retires a Capacity Source requirement instead. An agent can tell exactly what is being removed and how it differs from the sibling list_standing_intents / register_standing_intent pair.

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 names the trigger intent ('stop watching this'), the way to obtain the identifier ('Get the intent_id from list_standing_intents or from the register response'), and an explicit exclusion ('Do NOT use to pause temporarily; there is no pause'). This is the full when/when-not/where-from triad.

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

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

Annotations already declare readOnly/idempotent/non-destructive and closed-world, so safety is covered. The description adds genuine context beyond that: it discloses the returned structure (_entity=tool_families with a front_door block) and the important boundary that it is non-canonical navigation rather than the full catalog. It stops short of richer detail (e.g. result size or refresh semantics), so 4 rather than 5.

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

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

Front-loaded with the core purpose and the routing instruction, and every sentence carries information. The family-list enumeration makes the middle sentence a long run-on, but it earns its place by telling the agent what the return contains.

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 rich annotations, the description needs only to explain routing and boundaries — both of which it covers. An agent knows when to call it, what it returns conceptually, and that tools/list remains canonical, so nothing essential is missing.

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

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

Schema description coverage is 100% and the single query parameter is already documented with examples in the schema. The description restates the same optional keyword-filter semantics ('optionally filtered by a query') without adding format or matching behavior beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb+resource+scope: 'navigate DC Hub's tool catalog by FAMILY instead of scanning the whole list.' It distinguishes itself explicitly from the canonical catalog (tools/list) and from the scan-everything approach, so an agent can tell what this tool is for 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?

Explicit routing guidance: 'Call this FIRST when you are unsure which tool fits a task; then call the chosen tool.' It also names the when-not case ('this is a navigation layer, not the exhaustive catalog') and the alternative ('bind a capability map from tools/list, not from here'), leaving nothing to inference.

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

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

Annotations only declare it a safe, idempotent, open-world read; the description adds materially more: quota/tier honesty ("same quota, same paid depth as calling the tool yourself"), execution bounds (max 6 steps, cap 8, fan-out cap 3, ~40s budget), partial-failure behavior (status=not_run with exact tool+args), and the response envelope shape. This is context an agent cannot get from the annotations alone.

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 domain scope and the FRONT DOOR directive before the mechanics, and most sentences carry routing or behavioral payload. It is dense and long, with heavy capitalization and an exhaustive domain list that borders on bloat, but almost nothing is purely redundant.

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

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

For an 11-parameter orchestration tool with a documented output envelope, this covers routing, execution limits, failure semantics, envelope shape, and citation guidance. An agent has everything needed to invoke it correctly and interpret the result.

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

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

Schema description coverage is already 100% and the schema itself explains cohort no-op behavior and merge precedence, so the schema carries the load. The description adds only reinforcement ("pass intent UNCHANGED"; "add market, iso, state or lat/lon when you know them"), which is useful but largely duplicative. Baseline 3 is appropriate.

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

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

States a specific verb+resource (executes a planned multi-step answer path) and enumerates the exact domains it spans. Critically, it names the siblings it is NOT (plan_query when you only want the plan; direct tool calls for single-tool questions), so an agent can disambiguate without opening any schema.

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

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

Explicit when-to-use ("call this FIRST whenever a question spans more than one" domain), when-not ("single-tool questions should call that tool directly"), and the named alternative (plan_query). It even gives trigger phrasings ("rank markets for a 200 MW AI campus", "compare phoenix vs columbus") so routing is unambiguous.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, non-destructive, closed-world), but the description adds meaningful context: the paid-plan gating and the fact that it returns the entire file contents as text rather than a chat listing. The one gap is pagination/size-limit behavior for large shortlists, which is not addressed.

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 primary use case, then example, return shape, and exclusions in a logical order; every sentence carries information. Slightly dense with embedded parentheticals, but 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?

Covers intended use, format options, return payload contents, plan requirement, and explicit sibling alternatives. Even though an output schema exists, the description's summary of return fields (DCPI score, target MW, market, coordinates, notes) is accurate and complete for correct invocation.

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

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

Schema coverage is 100%, so baseline is 3, but the description goes further by stating the default ('csv') and the reason to pick the alternative (geojson for GIS tools like QGIS), tying the enum-like values to a real use case.

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 ('pull their saved DC Hub shortlist OUT of the platform') with concrete intended outcomes (offline analysis, spreadsheet, ingestion). It explicitly names the siblings it is not (list_saved_sites, save_site), so an agent can distinguish it without opening any schema.

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

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

Gives explicit when-to-use conditions plus a worked example ('Export my saved sites as GeoJSON for QGIS'), and states when NOT to use it with the correct alternatives for each case. Nothing is left to inference.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile needs no restating. The description adds genuine context beyond that: the record is a citable, public summary with a named shape ({id, title, text, url, metadata}) and only a subset of facility attributes (name, operator, location, status, market). It stops short of noting whether any context is destroyed, but for a pure read that is minor.

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

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

Three sentences, front-loaded with the action and its precondition, then the return shape, then the routing to get_facility. The parenthetical connector-format note is the one piece of marginal value; otherwise the text is tight and 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?

An output schema exists, so return values need not be spelled out, yet the description still summarizes the shape usefully. Combined with the id precondition and the get_facility escape hatch, an agent has everything needed to call this correctly rather than reaching for a richer facility tool.

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

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

Schema coverage is 100% for the single `id` parameter, and the description's example (equinix-dc1-ashburn) largely duplicates what the schema already states. The only added nuance is the tie back to a prior `search` result, which the schema also carries, so baseline 3 applies.

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

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

States a specific verb (Fetch) and resource (a DC Hub record) and scopes it to ids returned by the `search` tool, which distinguishes it from the many `get_*` siblings. It also names get_facility as the route for full structured specs, so an agent can separate it from that sibling without opening schemas.

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

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

Gives an explicit precondition (id must come from a prior `search` result) and an explicit alternative with its condition: use get_facility or open the url for full structured specs such as capacity MW and coordinates. Both when-to-use and the competing tool are named, not implied.

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

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: this is a discovery operation seeded from one facility, and results are ranked with similarity_score, match_reasons and key_differences. It omits any mention of rate limits, cost, or what happens when no candidates fall inside radius_km.

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?

Well front-loaded: trigger condition first, example second, invocation and params third, return shape fourth, exclusions last. Mostly earns its length, though the explicit 'Returns:' enumeration is partly redundant given a declared output schema, and the parameter sentence is both long and incorrect.

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 decision-relevant surface for a single-seed discovery tool: trigger, example, alternatives to avoid, and result semantics (and an output schema exists, so return values need not be spelled out). The one substantive gap is accuracy rather than omission — the phantom `name` parameter makes the calling contract incomplete/incorrect relative to the schema.

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

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

Schema coverage is 100%, so baseline would be 3, but the description actively misleads: it says 'Params: facility_id or name (the target, required)' while the schema's facility_id description states 'there is no `name` param; an undeclared key is silently stripped.' An agent following the description would pass `name` and get it silently dropped, producing a wrong or failed call. The example's '50MW' does loosely illustrate capacity_mw, but that does not offset the false parameter claim.

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 (find alternatives) plus the exact seed-resource it operates on, and names the sibling tools it is not (score_facility, analyze_site, compare_sites). The parenthetical framing ('what else looks like this?') makes the intent unmistakable against a large sibling list.

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

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

Explicit when-to-use trigger ('a user likes ONE specific facility'), a worked example with concrete inputs, and an explicit when-NOT-to-use clause routing to three named alternatives. It even states the selection rule (single seed → discover candidates) that distinguishes it from compare_sites.

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

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

Annotations only cover safety (readOnly, idempotent, non-destructive), but the description discloses far more: constraint_coverage semantics, the unfiltered fallback with applied:false/warning, the chord-vs-polyline fiber caveat, state-grain hazard/moratorium, the geography_required 400, and free-tier coordinate coarsening. This is unusually rich behavioral context beyond structured fields.

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

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

Front-loads the routing decision well, but is dense and partly redundant — the 'THE INVERSE QUERY' paragraph and the closing 'Do NOT use ...' sentence restate the same sibling list. Several clauses (free tier, hazard grain, chord caveat) could be consolidated 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?

Given a 13-parameter, no-required-parameter tool with an output schema, the description covers input requirements (geography mandatory), constraint behavior, return shape, caveats, and handoffs. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so baseline 3, but the description adds semantics: '230+ for hyperscale, 500 for the largest campuses' for min_voltage_kv, the state-vs-lat/lon requirement, and two fully worked example invocations. It goes modestly beyond the schema's own parameter text.

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 ('find_sites ... answers where should I even be looking') and defines the exact output — candidate search areas anchored on real HIFLD substations. It explicitly distinguishes itself from siblings (analyze_site, get_composite_site_score, rank_sites, find_alternatives, get_refined_queue) so an agent can route without opening any schema.

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

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

Gives an explicit selection rule: use find_sites when the user has NO site yet and wants candidates, and route multi-capability questions to execute_plan. It names the alternatives and the conditions that select them, plus concrete when-to-call examples ('200 MW in Ohio', 'areas near Dallas on 230kV with gas within 5 miles').

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

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

Annotations already declare the safe read/idempotent profile, and the description layers on genuinely new context: the returned shape (survey verdict + pdf_report_url), that the URL needs no login and is valid ~7 days, and that it can be handed to a human. This is behavioral detail the annotations cannot carry.

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

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

Front-loaded with the trigger and the deliverable, followed by a concrete example invocation that reads naturally. It is dense but each element (example, params, returns, alternative) is useful; the explicit 'Params:' block mildly duplicates the schema, so not a perfect 5.

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

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

For a single-call report generator, the description covers the trigger, the full worked example, the parameters, and the return value, and even points to the fallback sibling. The output schema exists, so the return explanation is a bonus rather than a gap-filler, leaving nothing an agent needs missing.

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

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

Schema description coverage is 100%, so the schema already documents every parameter, and the description's 'Params:' list largely restates those same ranges and defaults (capacity_mw 50-500, prepared_by defaults to DC Hub, latency_target default metro). The worked example adds marginal value but does not go much beyond the structured fields, so the baseline 3 holds.

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: generate a branded, multi-page Site Analysis PDF for ONE lat/lon. It immediately distinguishes the deliverable from a raw score and names the sibling that produces only the score. An agent can tell it apart from analyze_site without opening either schema.

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

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

Opens with an explicit trigger ('Use when a user wants a SHAREABLE, branded... client deliverable, not just a score') and closes with the routing rule: 'For just the numeric suitability score (no PDF), use analyze_site instead.' When-to-use and the named alternative are both explicit.

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

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

Annotations already declare readOnly/idempotent/non-destructive, yet the description adds substantial context beyond them: the roster is backend-owned and mutates, the authoritative data is the returned platforms[] array and per-row status, and critically that mcp_active/mcp_ready are CURATED EDITORIAL claims with as_of null, not live measurements. This is exactly the kind of caution an agent needs to avoid relaying stale or misleading status.

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 critical caveats are delivered early, but the middle digression ('rather than any list named in this sentence... a client named here stopped appearing in the roster') is anecdotal justification that does not help an agent call the tool, and the redundant 'Try: get_agent_registry' adds nothing. It is somewhat over-sized for a zero-parameter 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?

An output schema exists, so return formatting need not be explained, and the description is complete on every remaining axis: purpose, when to use, when not to, and the interpretation caveat for the status values. Nothing an agent needs before calling 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 (100% schema coverage), so there is nothing for the description to disambiguate and the baseline is 4. The description cannot add parameter meaning that does not exist.

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

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

States a specific resource (the curated roster of AI platforms/agent frameworks in the DC Hub ecosystem) plus what each row carries (recommended tools, auth tier), and explicitly distinguishes itself from telemetry: 'which AI platforms can connect to DC Hub'. An agent can tell it apart from siblings like get_backup_status without opening any schema.

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

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

Gives explicit when-to-use ('Answers which AI platforms can connect to DC Hub') and when-not ('Do NOT use for platform uptime or feed health (use get_backup_status)'), naming the alternative that should be used instead. Nothing is left to inference.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), but the description adds a genuinely non-obvious semantic caveat: 'unknown' means NOT measured and must not be treated as healthy, with an instruction to read row health before trusting a figure. That is real behavioral context beyond the structured fields. It does not add auth, rate-limit, or caching details, so it is not a 5.

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

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

The purpose and scope constraints are front-loaded, which is good, but the definition is dense and partly redundant: the nine-feed list and the summary-rollup field names duplicate what the output schema already declares, and the fragment 'Try: get_backup_status' is filler that earns no place. It reads as a concatenation of boilerplate rather than a trimmed definition.

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

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

With an output schema present, the description need not explain return values, and it still covers purpose, scope boundary, the sibling alternative, and the 'unknown ≠ healthy' interpretation rule. Nothing an agent needs to call a zero-parameter, read-only health 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?

The tool takes zero parameters, so there is no parameter semantics to disambiguate and the baseline is 4. The description's feed enumeration describes output content rather than inputs, which is fine but adds no parameter-level meaning.

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

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

The description names a specific resource (DC Hub ingest-feed freshness), enumerates the exact feeds covered, and states the returned shape (per-feed rows plus a summary rollup). It also pre-empts the misleading tool name by pinning scope to '/api/health/data-freshness' and distinguishing this from dataset-level freshness. An agent can tell what this returns without opening a schema.

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

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

It gives an explicit triggering question ('are any of your sources stale right now') and an explicit exclusion with the alternative named: 'Do NOT use for the freshness of one dataset (use get_changes); this is ingest health, not content.' Both the when and the when-not are present, so routing against get_changes is unambiguous.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds genuine behavioral context beyond them: the caching workflow ('cache the response generated_at and pass it back next call'), the default window, and the keyed-caller-only portfolio block. It doesn't discuss rate limits, pagination, or failure modes, keeping it below a 5.

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

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

Front-loads the core purpose well, but the description is long and partly redundant: the 'what changed since I last looked' phrasing repeats the opening thesis, and the portfolio-block detail is verbose. Several clauses re-explain the same delta idea rather than adding new information.

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

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

For a low-complexity, two-optional-parameter tool with rich annotations and an output schema, the description covers everything needed: purpose, format of since, default window, caching pattern, and what the response contains. 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 schema already documents both parameters, including the ISO/shorthand formats and 24h default. The description restates that same format info ('Pass since=<ISO-8601> or shorthand "24h"/"7d"') without adding syntax beyond the schema, so baseline 3 is appropriate.

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

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

States a specific verb+resource and scope: 'Incremental sync — what changed in DC Hub since a timestamp.' It explicitly distinguishes itself from the re-fetch pattern ('pulls only the delta instead of re-fetching everything') and enumerates the payload categories (DCPI movers, new facilities, M&A + news, portfolio block). An agent can tell it apart from list/search siblings without opening the schema.

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

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

Gives clear usage contexts — 'what changed since I last looked', 'anything new this week I should know about' — plus a concrete example call (since=7d) and the default (24h). It contrasts with the re-fetch alternative but never names a specific sibling tool that would be preferred for other cases, so it stops short of explicit when-not guidance.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so safety is covered — yet the description adds substantial behavioral context the annotations cannot: strict sourcing (USGS ASCE 7 + NOAA/ACIS), a no-estimation policy for missing data, and the radius_km failure mode where beyond-radius climate returns 'unavailable_exceeds_radius'. This is exactly the added value the dimension rewards.

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

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

Dense but front-loaded: purpose and trigger precede the return-shape block, and no sentence is filler. The inline return-value JSON is partially redundant given an output schema exists, which keeps it just short of a 5.

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

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

For a read-only geo-lookup with 100% schema coverage and a declared output schema, everything an agent needs is present: trigger, coordinate conventions, station-snap behavior, regional limits, sourcing guarantees, and sibling routing. Nothing material is missing.

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

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

Schema description coverage is 100%, so the baseline is 3; the description earns above that by giving a concrete coordinate example and, more importantly, explaining radius_km's operational meaning (snap distance to nearest NOAA station and its overflow behavior). It doesn't clarify the lat/lon alias precedence, but each alias is already documented in the schema.

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

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

States a specific verb and resource ('seismic + climate intel for a lat/lon') and immediately grounds the domain in what it drives (structural bracing cost, cooling design). It explicitly distinguishes itself from the two nearest siblings, get_disaster_risk and get_composite_site_score, so an agent can route without opening any schema.

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

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

Opens with an explicit when-to-use trigger ('Use when a user wants seismic + climate intel for a lat/lon') and closes with explicit alternatives for adjacent needs (natural-hazard ratings → get_disaster_risk; blended verdict → get_composite_site_score). Regional applicability is spelled out too: US ASCE 7 vs non-US → seismic unavailable.

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 safety is covered. The description adds real behavior beyond that: it never imputes a missing factor, water is marked unavailable only outside basin coverage and 'never faked', market/DCPI is v1-unavailable, and it names the live data sources (FEMA NRI, WRI Aqueduct 4.0). No auth, rate-limit, or latency notes, so not a 5.

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

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

Front-loaded with the trigger condition, then differentiators, then an example, then the return shape and alternatives — a sensible priority order. It is dense and long, with the return-shape enumeration arguably padded given an output schema exists, but nearly every clause carries distinct routing or behavior information.

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

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

For a read-only scoring tool with an output schema, the description covers trigger, data provenance, failure semantics, example call, and sibling routing — 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 coverage is 100%, so the baseline is 3; the description's concrete example ('lat=33.45 lon=-112.07 state=AZ') demonstrates the canonical invocation and confirms state is optional context, which is marginal added value over the schema. It does not clarify the alias precedence (lat/longitude, lon/lng) that the schema hints at.

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 — a 0-100 site suitability/risk verdict for a lat/lon — plus a distinctive output feature (explicit per-factor coverage map). It explicitly contrasts itself with siblings: 'unlike analyze_site (full raw data dump)' and 'use rank_markets' for market/DCPI, so an agent can separate it from neighbors without opening a schema.

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

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

Opens with an explicit trigger ('Use when a user wants ONE honest 0-100 site suitability/risk verdict') and closes with a routing table for alternatives: analyze_site for full data, compare_sites for 2-4 sites, rank_markets for whole-market ranking. Both when-to-use and when-to-use-something-else are covered.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), yet the description adds substantial non-obvious behavior: what happens on a non-matching context (generic blurb, matched_category=null, context_understood=false), the extra is_generic_answer/answer_note/next_tools fields in that fallback path, and that this tool never computes a siting answer. That is real disclosure beyond the structured fields.

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

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

Front-loaded with purpose, then example, param constraint, return shape, fallback behavior, and exclusions — a logical order with no filler sentences. The one redundancy is the exhaustive enumeration of return keys (recommendation, matched_category, connect_url, success, etc.) given that an output schema already 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?

For a read-only lookup with annotations and an output schema, the description supplies everything needed: category constraint, fallback semantics, and sibling routing. The residual friction is that the input schema still invites free-text input that the description says will not parse, leaving the agent to reconcile two conflicting signals.

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 schema's own description actively misleads ('Free-text description of the siting request — MW, geography, workload, deadline') while the tool only accepts four literal categories and declares no enum. The tool description corrects this by spelling out the four literal values and warning that free text returns the generic blurb, adding genuine meaning the schema contradicts.

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 ('ready-to-quote DESCRIPTION of DC Hub'), the scope of four categories, and the secondary output (live top-ranked market pocket). It explicitly distinguishes itself from siblings by naming analyze_site, rank_markets, and site_selection_canvas as the tools for the adjacent jobs, so an agent can route without opening any schema.

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

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

Gives a concrete example invocation and an explicit 'Do NOT use for...' list with a named alternative for each excluded case (single lat/lon, rank-by-one-criterion, computed shortlist). Both the when and the when-not conditions are stated, which is the strongest form of routing guidance.

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

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

Annotations already cover read-only/idempotent/open-world safety, but the description adds real behavioral context beyond them: live query vs estimation, county-level resolution, and the coverage=unavailable edge case for non-US points, plus source provenance (FEMA NRI). It loses a point only because a sizable share of the text enumerates return fields that the output schema already supplies.

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

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

Front-loaded with the use case and example before the payload details, and every clause is substantive. The return-shape enumeration is somewhat redundant against the existing output schema and makes the block longer than strictly needed.

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

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

For a point-lookup tool wrapped in annotations and backed by an output schema, this is complete: the agent knows the trigger, the geography limit, the data source, the resolution, and where to go for adjacent questions. Nothing needed to call it correctly is missing.

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

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

Schema description coverage is 100% and the alias relationships (lat/latitude, lon/lng/longitude) are fully documented there. The description adds only the example call using lat/lon, which confirms the canonical names but no format or range detail beyond the schema. 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?

Specific verb+resource (natural-hazard/disaster risk for a lat/lon) with the hazard taxonomy enumerated, and it names the two siblings it is not (get_water_risk, get_composite_site_score). An agent can distinguish it from the ~80 other siblings without opening any schema.

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

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

"Use when a user wants the natural-hazard / disaster risk for a lat/lon" states the trigger, and the closing sentence gives explicit alternatives with their selecting conditions (chronic water stress → get_water_risk; blended site verdict → get_composite_site_score). Routing is fully determined.

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

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

Annotations already cover the read-only/idempotent safety profile, and the description goes well beyond them: 429 handling with retry_after_s, gated-access behavior requiring a human_url, CC-BY-4.0 attribution requirements, and the constraint to pass iso or state but not both. These are operational traits an agent cannot infer from the structured fields.

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

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

Front-loads the most important routing decision and every sentence carries routing, safety, or return-value information. It is dense and the front-door-check block runs long before the core purpose is stated, which is a mild structural cost against a tool this routing-heavy.

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, single-ISO price tool it covers everything an agent needs: routing decision, exclusions, required params, return shape, error handling, gating, and attribution. The output schema exists, and the description does not waste space re-explaining return values beyond a brief shape summary.

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 earns an upgrade by adding the iso enum list, marking iso as required (the schema declares no required params), and adding the iso-vs-state mutual-exclusion rule. It does not explain data_type, which slightly caps the score.

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

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

States a specific verb and resource: live energy PRICING for the 7 US ISOs (retail cents/kWh, wholesale/LMP, Henry Hub-referenced gas, grid-status flag). It explicitly distinguishes itself from siblings (get_grid_data for fuel mix, get_grid_intelligence for headroom, get_gas_economics for behind-the-meter economics). An agent can select it without opening any schema.

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

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

Gives explicit routing rules: use execute_plan when price is only one factor in a siting/comparison question, use get_energy_prices directly for a single-ISO price lookup. It also enumerates when NOT to use it, naming the exact alternative tool for each excluded case. This is textbook when/when-not/alternatives guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds real behavioral context beyond them: output cardinality ('Returns ONE facility in full'), gating requirements ('Gated: give human_url to your human'), and 404 handling. It doesn't cover auth scope or rate limits, so it stops short of a 5.

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

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

The field enumeration, usage examples, and constraints are all relevant and the 'one facility / do not search' constraint is prominent. The opening field list is long and slightly overloaded, but it is front-loaded and almost every clause 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 an output schema present, the description need not explain return values, and it still covers cardinality, the input prerequisite, gating, and error recovery for a 6-parameter lookup tool. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description goes further by showing concrete call examples with literal values (id=equinix-dc1-ashburn, slug=digital-realty-iad8) and framing the id/slug/name fallback chain, which clarifies how the anyOf alternatives should be chosen in practice.

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 ('Get Facility Details' / 'Full metadata for one facility') and enumerates the returned fields (power capacity, cooling, fiber carriers, DCPI verdict, peers). It explicitly distinguishes itself from the sibling search_facilities by stating it returns ONE facility and must not be used to list many.

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 ('Answers "who operates this data center..."'), when-not-to-use (do NOT use to search/list many — use search_facilities), a prerequisite (needs a slug or id from search_facilities), and error recovery (404 → re-run search_facilities). This leaves almost nothing to inference.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds material behavior the annotations cannot: only DCPI market-health has a short-term temporal series, the site-hazard dimensions are deliberately static with a pointer to the point-in-time tool, and missing snapshot history yields coverage:unavailable. This is exactly the integrity context an agent needs to avoid fabricating a delta.

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

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

Front-loaded with the usage trigger, then the return shape, then an INTEGRITY caveat block. It is on the long side and the INTEGRITY block is dense, but nearly every sentence carries non-redundant information an agent needs.

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

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

An output schema exists, yet the description briefly previews the return shape (dcpi_market_health / static_dimensions / summary) and fully covers the integrity caveats and coverage semantics. Nothing material 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%, so the baseline is 3, but the description adds the mutually-exclusive 'facility_id OR market' selection semantics missing from the schema and restates the '7d'/'30d' default. It stops short of detailing slug resolution behavior, but the either/or framing is genuine added value.

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

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

States a precise verb+resource: the temporal *change* in a facility's (or its market's) risk profile, not the level itself. It explicitly distinguishes itself from the static point-in-time siblings (get_composite_site_score / get_disaster_risk / get_climate_intel), so an agent can route correctly without opening a schema.

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

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

Opens with concrete trigger phrasings ("has this site gotten riskier lately?", "which way is this market moving?") and names the alternative tools for the current-value case. The when-to-use and when-not-to-use conditions are both explicit.

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

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

Annotations already cover the safe-read profile (readOnlyHint, idempotentHint, destructiveHint=false), and the description adds genuinely new behavioral facts: free callers receive only a route sample while the full set needs a paid key, and the call is gated with a human_url handoff. That is exactly the extra context annotations cannot express.

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

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

Front-loads usage, then scope, then filters, then gating, then the sibling redirect — a sensible order with almost no filler. The sentence listing returned GeoJSON fields ('carrier, type, fiber count, lit capacity, distance') partly duplicates the output schema, which is the only real waste.

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

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

With 4 optional params, an output schema, and full annotation coverage, the description covers everything an agent needs: purpose, triggers, filter semantics, sample-vs-full gating, and the sibling alternative. Nothing material is left for the agent to guess.

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 exceeds it by adding the market/route_type combination hint ('Great with route_type=longhaul'), the rank_markets provenance of the market slug, and carrier/route_type filtering that the schema does not pair up. It stops short of documenting include_sources or the ~1.2° endpoint rule in prose, so it is additive but not exhaustive.

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 fiber routes / carriers / connectivity for a site or market') and enumerates the route classes it returns (long-haul, metro, dark, IX). It also explicitly carves itself away from the get_facility sibling ('For one building use get_facility'), so an agent can pick it without opening a schema.

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

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

Gives explicit trigger conditions ('whenever the user asks about fiber routes, carriers or connectivity', 'which fiber routes or carriers serve a metro'), a worked example ('Zayo long-haul routes via Dallas'), and the alternative for a narrower scope (get_facility for one building). Filter dimensions are named so the agent knows what to pass.

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/idempotent/openWorld=false, yet the description adds substantial undisclosed behavior: data provenance (PeeringDB, thin outside dense US/EU metros), the meaning of the 'unknown' bucket and null score/single_carrier_risk, and the explicit warning not to report none_in_region as greenfield. This is exactly the kind of semantic context annotations cannot carry.

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

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

Front-loaded with the use case, then example, then params, then return shape, then the critical caveat — a sensible priority order. It is dense and long, with some restatement of schema params and return fields, but nearly every sentence is load-bearing.

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 scored-verdict tool the description covers the interpretation risk (null score vs. genuine build-required) that an output schema alone cannot convey, and it routes to alternatives. An agent can select and read this tool's result correctly without further inference.

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 lat/lon ranges, aliases, and radius_km default/range are already documented in the schema; the description largely restates these. It adds no new syntax or format meaning beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb+resource (fiber-readiness verdict) and scopes it precisely to ONE parcel/site at lat/lon, naming what the output actually answers (near-net distance, carrier count, single-carrier risk). It clearly distinguishes itself from get_fiber_intel (routes between metros) and analyze_site (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?

Gives an explicit when-to-use framing, a concrete example query, and explicit when-NOT-to-use with named alternatives (get_fiber_intel for carrier routes, analyze_site for full suitability). Conditions that select each sibling are stated, not implied.

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 full safety profile (readOnly, idempotent, openWorld, non-destructive), and the description substantially exceeds them: it discloses the burner-tip price rule (EIA PEU delivered gas, trailing-12-month mean, 9-of-12 month reporting floor, $0-$20 bounds), the null-with-reason behavior for withheld states (AZ, GA, FL), and the gas_to_grid_status switch field. The lengthy WITHDRAWN/RESTORED changelog partly muddies what is true *now*, which keeps this from a 5.

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

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

The core purpose is front-loaded, which helps, but the body is bloated with internal changelog narration (starred WITHDRAWN/RESTORED dates) that does not help an agent invoke the tool. The genuinely load-bearing warnings (no cross-date $/MWh comparison, no do-it-yourself derivation) are buried mid-paragraph rather than surfaced.

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 price tool with an output schema already present, the description covers the remaining behavioral gaps an agent needs: withholding rules, null/status fallbacks, and data-integrity warnings. Return-field explanation (burner_tip contents) is somewhat redundant with the output schema but not harmful.

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

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

Schema description coverage is 100%, so both parameters are already documented and the baseline is 3. The description adds only marginal meaning for `market` (example slugs, pointer to rank_markets) and never mentions `heat_rate_btu_per_kwh` except obliquely via 'CCGT/peaker heat-rate scenarios'.

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

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

The opening sentence names a specific resource (Henry Hub spot, regional basis differential, delivered industrial + electric gas tariff in $/MMBtu) for a clearly bounded scope (US data-center market). The closing instruction explicitly separates it from a sibling (get_grid_data) so an agent can route without opening a schema. It is verbose, but the purpose itself is unambiguous and sibling-distinguishing.

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

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

It gives an explicit exclusion plus alternative ('Do NOT use for the electricity grid fuel mix (use get_grid_data)') and states where valid slugs come from (rank_markets / get_market_dcpi_rank). It does not, however, differentiate usage against the nearest-looking siblings like get_gas_index or get_gas_intelligence, so a routing question remains.

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 safety (readOnly, idempotent, non-destructive, closed-world), yet the description adds genuinely decision-changing behavior: UNSCORED is absence rather than a low score, dcgi comes back null with an unscored_reason, and gas_price_series attributes the EIA source. The withdrawal/restoration defect narrative (case-blind TYPEPIPE term, non-deterministic tie-break, hardcoded constants) is provenance rather than invocable behavior, which keeps this short of a 5.

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

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

The payload is dominated by a changelog: three named defects, two dates each with a ★ marker, and a methodology URL. Only two sentences (UNSCORED semantics, the sibling hand-off) change how an agent calls the tool; the rest is archival detail that pushes the actionable content to the middle of the block.

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

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

An output schema exists and carries the return shape, so the description needn't explain fields. What remains — null/verdict semantics for unpriced states, source-series attribution, the pre/post-2026-08-08 comparability break, and the two sibling lanes — is enough for an agent to call this correctly and interpret the result.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema. The state description in the schema repeats the UNSCORED and gas_price_series semantics nearly verbatim from the tool description, so the description adds no parameter meaning beyond structured data. Baseline 3.

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

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

The opening clause names a specific resource and scope: 'Data Center Gas Index (DCGI) — the per-US-state natural-gas suitability score.' It also routes to two siblings (get_gas_intelligence, get_gas_economics), so an agent can place it. However, the core purpose is immediately buried under a version-history banner, which blunts the first-sentence signal.

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 hands off adjacent domains: 'Use get_gas_intelligence for pipeline, operator and parent-midstream data' and points to get_gas_economics for gas-fired $/MWh figures. That implicitly defines this tool's lane as state-level DCGI scoring, but there is no positive statement of when to reach for DCGI versus, say, get_market_intel or get_market_dcpi_rank.

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/openWorld/idempotent/non-destructive, so the bar is low, yet the description goes well beyond: synthetic-labeled basis, null delivered prices 'surfaced honestly, never fabricated', deliberately omitted feeds (gas storage/LNG/firm capacity), per-field data_basis provenance, and dated withdrawal/restoration caveats on dcgi_score and gas_to_grid_usd_per_mwh. These are real behavioral traits (data comparability, caching hazards) an agent cannot get from annotations.

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

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

Usage guidance is front-loaded and well-placed, but the description is grossly oversized: the when-to-use instruction is stated twice in near-identical wording, and a large block of dated withdrawal/restoration history and cache warnings ('DO NOT quote a DCGI score cached before 2026-08-30') crowds out the core signal. Much of that versioning detail belongs in the referenced /api/v1/dcgi/methodology endpoint rather than in a selection-time description.

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, open-world per-state intelligence brief with an output schema and full annotation coverage, nothing an agent needs to call it correctly is missing: scope, routing, provenance, null-handling and deliberate omissions are all disclosed. The output schema carries the return-shape burden, so the description's completeness is sufficient.

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 both parameters are documented there, so the schema does the heavy lifting; the baseline is 3. The description restates the region param ('US state code or name, e.g. "TX" | "Texas" | "Virginia"') but never mentions the 'state' alias that exists in the schema, so it adds nothing beyond structured data.

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 ('fuses the Data Center Gas Index, live Henry Hub, gas-to-grid $/MWh, pipeline-operator presence, and live grid gas share into one per-STATE brief') and explicitly positions itself relative to siblings as 'the GAS analogue of get_grid_intelligence.' An agent can distinguish it from get_grid_intelligence and get_gas_index without opening any schema.

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

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

It states when to use ('whenever the user asks about gas-fired or behind-the-meter power for a data center in a US state') with sample phrasings, and gives explicit when-not-to-use routing: 'Do NOT use for electricity grid headroom (use get_grid_intelligence) or the DCGI score alone (use get_gas_index).' Both alternatives are named with the condition that selects them.

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

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

Annotations already declare the safe read-only/idempotent profile, and the description adds real value on top: the dataset size and coverage, the return shape (summary of total MW by fuel + count by status, plus largest units), and the semantic of pipeline=true as JUST the forward set. It stops short of pagination/rate-limit or default-limit behavior, so it is strong but not exhaustive.

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

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

Long but front-loaded: scope, dataset, filters, return shape, examples, and exclusions in a deliberate order, with no filler sentences. Density is high and every clause carries routing or filter information, though it is close to over-stuffed for a single description.

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

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

Given a 7-param optional schema with 100% coverage, a present output schema, and read-only annotations, the description still fully covers scope, filters, return format, and sibling disambiguation. Nothing an agent needs to invoke this correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds meaning beyond the schema: fuel is described as a comma-union with the accepted values, pipeline=true is spelled out as 'announced + pre-construction + construction' only, and bbox is given as minLng,minLat,maxLng,maxLat. It adds genuine interpretation on top of already-complete schema docs.

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

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

States a specific verb+resource ('Global Integrated Power Tracker' asset inventory of 182,000+ geolocated units) with explicit scope (WORLDWIDE / non-US) and enumerates the fuels and statuses covered. It explicitly differentiates itself from three named siblings (get_grid_intelligence, get_grid_scoreboard, get_power_pipeline), so an agent can route correctly without opening a schema.

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

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

Opens with the when-to-use condition ('when a user asks about power plants/units WORLDWIDE or in a NON-US country') and closes with explicit when-NOT-to-use plus the correct alternatives for each excluded case. Also supplies concrete example queries ('what power is being built in India'), leaving nothing to inference.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuine context beyond that: the upstream data source (EIA hourly RTO), that it is raw real-time telemetry for a single ISO, and the geographic boundary. Return format is not described, but an output schema exists, so this is not a real gap.

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

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

Front-loaded with the core capability and scope, then alternatives and exclusions. Dense but every clause earns its place; minor redundancy between the ISO list in the first sentence and the iso=PJM note.

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 source, geographic scope, metric scope, and sibling routing. With an output schema present, return values need not be explained, so nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters, making 3 the baseline. The description reinforces parameter meaning by enumerating the 7 ISO values and giving metric focus examples (fuel_mix, demand, demand_curve) but adds little beyond the schema.

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

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

States a specific verb+resource (real-time electricity grid data) with data fields (fuel mix, demand, 24h demand curve), the exact scope (7 US ISOs listed by name), and the source (EIA hourly RTO). An agent can distinguish it from siblings 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?

Explicitly names when NOT to use it (power-availability, time-to-power, interconnection-queue analysis) and routes to the correct alternatives: get_grid_intelligence, get_energy_prices, and get_grid_scoreboard for non-US grids. Clear when/when-not/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 only declare read-only/idempotent behavior, and the description adds the operationally important traits: quota by key tier (free = a few briefs/day, keyless = trimmed preview, paid = unlimited) and a specific failure mode (non-ISO codes return region_not_covered). It also warns that two similarly named metrics (avg_time_to_power_months vs avg_queue_wait_months) are different, preventing a reporting error.

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

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

Front-loaded with the use case, but it is loosely assembled and repeats itself: "Free = preview" restates the earlier free-key sentence, and the ISO enumeration appears twice. The content earns its place but the duplication and run-on phrasing cost it.

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

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

An output schema exists so return values need not be spelled out, and the description still covers triggers, valid identifiers, failure modes, and key tiers. For a 4-alias, anyOf-required tool, an agent has everything needed to select and call it correctly.

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

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

Schema coverage is 100% so the baseline is 3, but the description contributes real meaning: it constrains iso to the seven US ISOs, states the error behavior for other codes, and warns that market is not an alias for region_id ("Ashburn" is not a grid code). This adds value for invocation accuracy beyond the schema text.

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

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

States a specific resource and scope: grid capacity, demand and reliability for one grid region, callable for US ISOs or a market. It enumerates exactly what comes back (demand, fuel mix, queue depth, DCPI scores, time-to-power, reserve margin), which separates it from siblings like get_grid_scoreboard, get_iso_context, and compare_isos.

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

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

Opens with an explicit trigger ("use this whenever the user asks about grid capacity, demand or reliability") and lists the concrete question shapes it answers (power availability, headroom, time-to-power). It also clarifies the alternative input path (a metro/market name resolves to its ISO) rather than leaving the agent to guess.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description goes well beyond them: it warns that freshness is non-uniform, that US fuel mix lags demand by 18-24h, that demand_period and mix_period are separate clocks, and that each row carries mix_age_hours/demand_vs_mix_lag_hours. This is exactly the operational caution an agent needs before narrating any row as 'now'.

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

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

The trigger and the sibling routing are front-loaded, and most sentences earn their place by carrying accuracy caveats. It is nonetheless overlong and dense: the full enumeration of US ISOs, EU bidding zones and data sources is more scope detail than selection requires, and the parenthetical about counts_basis.eu_zones_live adds noise.

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

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

An output schema exists, so the description need not explain return shape, and it uses its space instead for the caveats that the schema can't convey (freshness fields, geothermal-inclusive alternative metric, unranked partials). For a no-arg, high-complexity aggregation tool, nothing an agent needs to call or interpret it correctly is missing.

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

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

The tool takes zero parameters, so the baseline is 4; there is nothing for the description to disambiguate on the input side. The description instead spends its budget on output semantics (which is appropriate given the empty 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 (a globally ranked grid scoreboard) and explicitly differentiates itself from siblings: 'vs compare_isos (pairwise) or get_grid_data (single ISO)'. It also names the exact ranking basis (renewable_share_pct = wind+solar+hydro) and the covered feeds, so an agent knows precisely what it gets back.

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

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

Opens with the trigger condition ('whenever the user asks how grids compare right now: demand, fuel mix or renewable share') and closes with the alternative-selection rule naming compare_isos and get_grid_data. It further spells out the when-not cases (Brazil has no gas share, AU/SG are unranked partial_grids), so the agent won't misuse the results.

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