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

Annotations only supply safety flags (readOnlyHint=false, idempotentHint=false, destructiveHint=false); the description goes well beyond them by disclosing prerequisites (an identified caller via claim_free_key + bind_email, or an OAuth connection; accept_terms=true), the once-per-terms-version recording behavior, and the side effect of writing to DC Hub's lead register. It even states what unlocks afterward (listing details open), which is exactly the guidance an agent needs before invoking a non-read-only tool.

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

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

Front-loaded with the trigger condition and constraint ('never on your own judgement'), and each clause carries signal (prerequisites, return, exclusions). It is densely packed into few sentences with parenthetical asides, which is efficient but slightly harder to scan than a shorter definition would be.

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 two-parameter, non-read-only tool with an output schema, the description covers trigger condition, caller identity prerequisites, version semantics, return values, and sibling exclusions. Nothing an agent needs to invoke it correctly is missing, and the output schema handles the return shape.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds provenance the schema does not: terms_version should come from access.unlock.terms.version returned by source_capacity, and omitting it sends the currently published version. These are real usage rules beyond the field documentation.

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 ('accept_capacity_terms' records acceptance of DC Hub capacity introduction terms) with the exact artifact named and linked. It explicitly distinguishes itself from the two nearest siblings, request_capacity_intro and source_capacity, so an agent can route 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?

States the precise triggering condition: call only when source_capacity returns a listing locked with access.reason terms_acceptance_required, 'never on your own judgement.' It also names the two prohibited uses and the correct alternative for each (request_capacity_intro, source_capacity), which is explicit when/when-not guidance.

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

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

Annotations already cover the safety profile (read-only, idempotent, not open-world, non-destructive), so the description's real contribution is freshness ('Refreshed Fridays 14:00 UTC') and the composite score's composition (depth + diversity + power), which the agent cannot get from annotations. The field enumeration partly duplicates the existing output schema, keeping it 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?

Front-loaded with trigger and scope, and the use-case and do-not-use sentences each carry routing value. The one dense sentence enumerating return fields is somewhat long and partly redundant with the output schema, but no sentence is pure filler.

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

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

Given only two optional params, an output schema, and full annotation coverage, the description supplies everything else an agent needs: freshness cadence, what the score means, primary use cases, and explicit sibling alternatives. No gaps remain for correct invocation.

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

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

Schema description coverage is 100%, so both params (limit, horizon) are already documented, and the description only echoes the 30/60/90 horizon values in prose without adding format or edge-case guidance. Per the high-coverage baseline this is a 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?

States a specific verb and resource ('ranks data center markets') plus a precise scope ('where 100MW of AI training capacity can land in the next 30/60/90 days'). It explicitly distinguishes itself from three siblings (rank_markets, grid_transition_radar, and DCPI/rank_markets ai_ready), so an agent can route correctly 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?

Opens with an explicit trigger ('Use this when the user asks where AI compute capacity could land'), names concrete use cases (AI capex planning, GPU cluster siting, hyperscaler deal forecasting), and gives two explicit 'Do NOT use for' exclusions with the correct alternative for each. 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, but the description adds substantial behavior beyond that: out-of-coverage points return parcel_not_covered with an analyze_site preview plus coverage list and "never a guess," and representative_point is deliberately the largest member's centroid rather than the geometric center to avoid poisoning point-keyed reads. It also states hosted layer scope (VA, IL, TX, OH, UT, OR, IA, WY counties) and the downstream handoff.

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 "Use this when..." and organized logically (inputs, return shape, handoff, alternatives). Dense with parentheticals and slightly long, but nearly every clause carries actionable 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 analysis tool with an output schema present, everything an agent needs is there: both input modes, coverage scope, failure behavior, return shape, and the handoff to analyze_site and get_water_risk. Nothing essential is missing.

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

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

Schema coverage is 100%, so the schema already documents all parameters including aliases and geometry format. The description restates the geometry-vs-lat/lon alternative and the capacity_mw pass-through, adding modest clarity on the OR relationship but mostly reflecting what the schema already says.

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: "structured read of its boundary" for a land parcel, with both input modes (own GeoJSON vs. lat/lon hosted-layer lookup) and outputs named. It is clearly distinguishable from analyze_site and get_refined_queue, which are both explicitly named.

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 ("when you HAVE a boundary or a point on a specific parcel and want it anchored + sized") and names alternatives with their selection conditions: analyze_site for general lat/lon site scores, get_refined_queue for the queue survivor set. Even notes that queue rows carry no parcel identity, so they never auto-join.

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

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

Beyond the read-only/idempotent annotations, it discloses return contents, capacity_mw semantics that do not move overall_score, keyless/free/paid data limitations, partial-result human_message/link behavior, missing_coordinates errors, and frozen candidate_id fail-closed behavior. This adds substantial operational context.

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

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

The description front-loads the use case and return contract, then covers key tiers, partial-result handling, and coordinate constraints. It is dense and somewhat long, but most sentences earn their place.

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

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

For a 12-parameter, zero-required tool with full schema coverage, annotations, and an output schema, the description covers input modes, auth/data tiers, error conditions, and result-handling. Nothing critical 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 schema already carries the baseline; the description adds important meaning for capacity_mw, candidate_id, location, and lat/lon requirements. It does not add much beyond schema for the include_* flags or state parameter.

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

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

States a specific verb/resource and decision support: whether a site or coordinate works for a data center, with composite and sub-scores. It is clear, but it does not explicitly distinguish itself from close siblings such as score_facility, get_composite_site_score, or generate_site_analysis.

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

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

Provides a clear trigger ('Use this when the user asks...'), coordinate sourcing from get_facility/search_facilities, candidate_id preference for queue survivors, and key-tier/partial-result handling. It lacks explicit when-not guidance or alternative routing versus rank_sites/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 declare this is a non-readonly, non-idempotent, non-destructive mutation; the description goes well beyond that by spelling out what binding does (makes the key recoverable via recover_my_key) and what it does not do (does not make identity durable), plus the consent rule for marketing. It does not state what happens on a repeat bind of an already-bound key despite idempotentHint=false, which is the one meaningful behavioral gap.

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

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

The usage trigger is correctly front-loaded, but the middle passage carries a lot of weight that does not help select or invoke the tool — the cohort statistics ('0 of 3 mature identities, 2026-08-12') and the OAuth aside read as internal justification rather than invocation guidance.

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

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

With an output schema present, return values need not be described; the description covers the mutation's benefit, its limits, and consent prerequisites well. What is missing is failure behavior (already-bound key, rejected placeholder address) which matters for a non-idempotent write.

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; the description only reinforces the email constraint ('pass only an address they typed'). It adds nothing beyond the schema on api_key or marketing_opt_in, 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?

The first sentence names the specific action (tie a DC Hub key to an email) and its trigger, and later sentences explicitly separate binding from recover_my_key and from OAuth sign-in. An agent can distinguish this from unlock_more_data or claim_free_key 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 exactly when to call it ('user wants their key tied to their email, or a result said an email unlocks more'), gives the prerequisite (ask the human for their email first, pass only an address they typed), and names the competing alternative (OAuth sign-in, only offered after a 401 WWW-Authenticate challenge).

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

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

The description adds substantial behavior beyond the annotations: no key is needed to start, the key is returned with an embedded connect_url, free vs email-key limits are specified, and email-based recovery is explained. It also clarifies the 401/OAuth branch and that keys should be saved rather than re-minted.

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

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

The description is front-loaded with the triggering condition and core action, and most sentences carry operational guidance. It is dense and somewhat long, but the length is mostly justified by the branching rules around email, key recovery, and 401 challenges.

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

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

Despite having an output schema, the description still explains the important return values (key and connect_url) and their significance. It covers limits, email consequences, recovery, re-minting, downstream execution, and the sign-in challenge case, leaving little an agent needs to infer.

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

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

Schema coverage is 100%, so both parameters are already documented in the schema. The description reinforces that the email must come explicitly from the user and is used for recovery, but it adds little about client_name beyond what the schema already says.

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 action and resource: it mints a free DC Hub key and returns it with connect_url. It also distinguishes this from keyless access, recover_my_key, and execute_plan, so an agent can identify the tool without opening the schema.

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

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

It gives explicit when-to-use conditions: when the user wants more data than keyless allows or asks for a key. It also names alternatives and exclusions: recover_my_key for lost keys, don't re-mint, prefer sign-in when a 401 challenge appears, and use execute_plan for multi-step questions.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description layers on substantial extra context: the physics model (km x 4.9 µs/km x 2), route_factor 1.4 stamped as inference, confidence_v provenance tiers, dark-fiber screening, and a fail-closed candidate_contract for expired/unknown ids. This is genuinely value-adding behavior 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?

Front-loads the trigger and outcome before diving into the per-pair metrics, and uses a labeled 'CANDIDATE CONTRACT' block for the contract rules. It is dense and slightly repetitive in restating the candidate_id provenance, but nearly every clause carries operational 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 4-param, read-only analytical tool with an output schema and full annotation coverage, the description supplies everything an agent needs: trigger, sequencing, the physics/confidence semantics, and the candidate-id contract. 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 coverage is 100%, so the baseline is 3, but the description adds real meaning: candidate_ids resolve to FROZEN mint coordinates (zero transposition), cand_ tokens may be mixed into the sites string, and expired/unknown ids are dropped and declared. It also frames max_latency_us against a realistic use case (sync replication 1000-2000 µs).

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 ('cluster sites by latency') plus the scope (2-8 sites) and the output ('viable low-latency clusters and pairwise RTT floors'). It distinguishes itself from routing work ('deterministic pruning BEFORE detailed routing') and cross-references compare_sites and get_refined_queue, so an agent can place it relative to siblings.

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

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

Gives an explicit trigger ('when the user asks which data center sites can form a low-latency cluster') and a clear ordering rule ('BEFORE any routing work'). It stops short of naming the specific alternative tool to use for the downstream routing step, so it's clear context rather than full when/when-not routing.

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

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

Annotations already declare read-only, idempotent, non-destructive, open-world behavior, so the safety profile is covered. The description adds important behavior beyond that: non-US and non-ISO rows have null DCPI/queue fields because they are not tracked rather than zero, and it distinguishes avg_time_to_power_months from avg_queue_wait_months as different measurements.

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 use case is front-loaded, followed by examples, parameter constraints, return shape, and a crucial measurement caveat. Despite its density, every sentence contributes operational detail needed to select and invoke the tool correctly.

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

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

Given the tool's complexity, the description is complete enough for correct selection and invocation. It explains when to use it, the accepted input domain, the comparison output fields, null-field semantics, and the key measurement distinction, while the output schema covers the return structure.

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

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

Schema coverage is 100%, so the parameter is already documented. The description still adds meaningful constraints and enumerations: comma-separated list, two-to-four maximum, accepted US ISOs, TVA, BPA, utility BAs, and non-US grid identifiers. It does not add much syntax nuance beyond that, so it is strong but not exceptional.

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: compare two to four power grids side by side, including fuel mix, demand, renewable/gas share, and queue metrics. It explicitly distinguishes itself from making N sequential get_grid_intelligence calls, so an agent can route between this and the single-grid path.

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 clear trigger: when the user asks to compare two to four grids side by side. It names the alternative it replaces, get_grid_intelligence for sequential single-grid calls, and supplies concrete examples including mixed US/non-US comparisons.

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, closed-world), and the description adds the non-obvious behavioral layer: tiered data availability (keyless = bands only, free key = names/counts, paid plan = figures and the pick). That gating materially changes what the agent can promise a user and is not inferable from 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 the trigger condition, then format, then return tiers, then an example – each sentence carries distinct information with no filler or repetition.

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

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

An output schema exists so return-shape detail is unnecessary, yet the description still supplies the crucial tier-dependency of results and the recommendation behavior. Nothing an agent needs to decide whether and how to call this 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 string format and capacity_mw semantics are already documented. The description adds value by restating the accepted 'lat,lon;lat,lon' form in context and framing capacity_mw as optional and tied to the user's build, but it does not explain the sites[] alternative or the 2-4 bound enforcement beyond what the schema says.

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 ('compare_sites', sites side by side) and scopes it precisely: 2-4 candidate sites, returns analyze_site scores plus a recommended winner. An agent can tell it apart from single-site siblings like analyze_site or rank_sites 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?

Explicit trigger ('when the user has 2-4 candidate sites and asks which is best') plus an example utterance ('Phoenix vs Ashburn for 50 MW?'). It also spells out the fallback path when the caller lacks a key, so an agent knows what it will actually get before calling.

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

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

Annotations already declare read-only, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds genuinely non-obvious behavior: the per-deal autopsy read is gated behind a paid key, and the default response is deliberately trimmed (comparables count only) to keep it cheap. No rate limits or failure modes, but the paywall and progressive-disclosure cost model are real added context.

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

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

Front-loaded with the trigger condition, which is good. But it is dense and repetitive: the 'what is the real play' framing appears twice, and there are many embedded quoted phrases and dashes that add length without adding 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?

An output schema exists, so return values need not be spelled out, and the description nonetheless sketches the shape (deal fields + DCPI verdict + time-to-power). Trigger conditions, the paid-key caveat, and the disclosure levels are all present, leaving only minor gaps such as ranking/ordering of the returned deals.

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 goes beyond the schema by giving escalation guidance for comparables ('escalate only for deals you're drilling into') and by confirming the verdict text is always included regardless of the comparables setting, which resolves a plausible ambiguity.

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 concrete verb and resource: returns recent data-center deals (buyer, seller, value, market) joined to each market's DCPI verdict and time-to-power. An agent can distinguish it from the broader deal listers. It never names a sibling it is not (e.g. hyperscaler_deals, list_transactions), so the differentiation is inferred rather than stated.

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: 'Use this when the user asks what a data-center deal means for power' plus two representative user questions and a worked call example (deal_autopsy limit=15). Clear context, but no when-not-to-use and no named alternative for plain deal listing.

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 flag destructiveHint=true and idempotentHint=false, but the description adds what the annotations cannot: deliveries stop, the watch is unrecoverable, cap_ ids instead retire a Capacity Source requirement and stop its alert emails, and a key/OAuth credential is required. This is exactly the extra operational context the annotation layer lacks.

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, then consequences, then the cap_ edge case, then the credential requirement, then the anti-pattern. Every sentence carries distinct, decision-relevant information with no filler.

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

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

With an output schema present, return values need no explanation. The description covers auth, destructiveness, irreversibility, the cap_ variant, and id sourcing, leaving nothing an agent needs before calling it.

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

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

Schema coverage is 100%, so the baseline is 3; the description goes further by explaining the cap_ prefix semantics that branch behavior and by reinforcing the id provenance. It does not add format/syntax detail beyond that, so not a 5.

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

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

States a specific verb (retire/delete) and resource (standing intent / webhook watch), and immediately distinguishes it from list_standing_intents and register_standing_intent by naming them. The 'Answers "stop watching this"' phrasing pins the user intent without ambiguity.

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

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

Explicit when (user wants to retire a watch), explicit when-not ('Do NOT use to pause temporarily; there is no pause'), and names the source of the id (list_standing_intents or the register response). Alternatives and the absence of a pause path are spelled out.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds genuine beyond-annotation context: the returned _entity shape, a front_door block containing execute_plan and get_changes, and the caveat that this is a curated navigation layer rather than the canonical catalog. Return-value detail is partly redundant with the existing output schema, keeping this at 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 when-to-use trigger and then the return shape, which is the right order. It runs long and restates the tools/list-is-canonical point twice (once as 'navigation layer, not the exhaustive catalog' and again as 'bind it from tools/list, not from here'), a minor redundancy that a single mention would cover.

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 discovery/routing tool with an output schema present, the description supplies everything an agent needs: when to invoke it, what it returns at a structural level, how to proceed afterward (call the chosen tool; its full schema is in tools/list), and the caveat about binding capability maps. 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% for the single optional query parameter, so the schema already carries the semantics. The description's example keywords ('site selection', 'grid queue', 'fiber', 'deals', 'market') largely mirror the schema's own examples, adding little new meaning; 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 and resource ('lists tools by family') and frames the tool's role as a 'navigation layer' rather than a data tool. It explicitly distinguishes itself from the canonical catalog (tools/list) and from execution tools (execute_plan), so an agent can place 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?

Opens with the triggering condition ('Use this when you are unsure which ... tool fits') and closes with an explicit when-not and alternative: it is not the exhaustive catalog, tools/list stays canonical, and capability maps should be bound from tools/list rather than here. Both routing and exclusion are spelled out.

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 safety profile (readOnly, idempotent, non-destructive, open-world), yet the description discloses substantial behavior: no-LLM deterministic routing, wave-by-wave execution with parallelism, angle-bracket hand-off resolution (metro_slug/candidate_id/ISO minting), capped per-finalist fan-out, and the exact envelope shape returned. This is rich context an agent could not 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-loaded with the use case and appropriately sized for a highly complex planner, but the long mid-sentence topic enumeration and the dense closing sentence run together, reducing scannability. The topic list earns its place by defining scope, but structure could be tighter.

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

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

For a tool this complex, the description covers the routing model, execution strategy, hand-off resolution, caps, and even the return envelope (in addition to the existing output schema). An agent has everything needed to call it correctly with the right expectations.

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 most parameter meaning is already structured. The description reinforces a few points (e.g., intent 'UNCHANGED', cohort having no routing effect, user-supplied values beating minted ones), but these are duplicated in the schema rather than adding new distinction, so the baseline of 3 is appropriate.

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

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

States a specific verb and resource ('one-call planner' that 'plans AND answers') and enumerates the exact multi-topic domain it covers, so the agent knows precisely what the tool does. It also distinguishes itself from plan_query by noting it runs the same deterministic planner and then executes 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?

'Use this when a data center question spans several topics' plus 'Recommended entry for a question that spans more than one of those' gives a clear when-to-use condition. It references plan_query as the shared planner but does not explicitly state when a single-topic question should bypass this in favor of individual tools, so it stops short of full alternative routing.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds context annotations cannot: the paid-plan gating and the fact that the whole file body is returned as text, which matters for how the agent should relay results.

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 alternatives, and every sentence serves routing or behavior. The 'Returns:' clause is mild redundancy given an output schema exists, but it is short and harmless.

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

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

For a single-parameter, non-destructive export tool with an output schema already defined, the description supplies trigger, alternatives, plan gating, and format guidance. Nothing needed to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description goes slightly beyond by restating the default ('csv' default) and showing a format-specific invocation example ('export_dataset format=geojson'), which clarifies intent rather than duplicating fields.

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

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

States a specific verb+resource ('export their saved data center sites') plus the purpose (offline analysis, spreadsheet, ingestion) and output forms. It explicitly names the sibling tools it is not (list_saved_sites, save_site), so an agent can route 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 a concrete trigger ('when the user wants to export'), a worked example with the exact call, and explicit exclusions with named alternatives ('Do NOT use to list sites in-chat (use list_saved_sites) or to save a new one (use save_site)'). This is the full when/when-not/alternative pattern.

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 safety profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint=false), so the burden is lighter. The description contributes domain context beyond that — the record is a citable public summary covering name/operator/location/status/market — which helps the agent understand the nature of the data returned.

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 triggering condition and then the guarantee/alternative, which is the right ordering. Slightly redundant to enumerate the return shape when an output schema exists, but overall tight and purposeful.

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

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

For a single-parameter read tool with full schema coverage, an output schema, and safety annotations, this covers the one open question — why choose `fetch` over `get_facility` — and answers it. 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 coverage is 100% and the single `id` param already carries an example (equinix-dc1-ashburn), so the schema does the heavy lifting. The description only reinforces the provenance of the id ("from `search`"), adding no format or syntax detail beyond the schema — 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 action (fetch a data-center facility record by id) and explicitly frames it as the companion to `search`. It names the sibling it is not (get_facility) and what that sibling returns, so an agent can distinguish the two 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 precondition ("when you have an id from `search`") plus a clear alternative for the adjacent need ("For full structured specs... use get_facility or open the url"). When-to-use and when-to-use-something-else are both stated.

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 it as read-only, idempotent, and non-destructive. The description adds useful behavior beyond that: it discovers candidates from one seed and returns ranked alternatives with similarity_score, match_reasons, and key_differences.

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

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

The description is front-loaded with the use case and example, and the final sentence efficiently routes to alternatives. It is slightly weakened by a parameter sentence containing inaccurate extras and by return details that partly duplicate the output schema.

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?

Purpose and sibling routing are complete, and annotations plus the output schema cover safety and return shape. However, the description's incorrect parameter guidance means it is not fully reliable as a standalone invocation guide.

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

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

The schema has 100% description coverage and explicitly says there is no `name` param, but the description incorrectly says 'facility_id or name' and mentions an optional `capacity_mw` that is not in the schema. It also omits the actual `match_on` and `exclude_operator` parameters, creating active confusion despite the schema being correct.

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

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

States a specific verb and resource: finding data center facilities similar to a seed facility. The example and sibling exclusions make it clearly distinct from score_facility, analyze_site, and compare_sites.

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

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

Explicitly says when to use it, gives a concrete example, and names when not to use it with alternative tools. It also clarifies that this discovers candidates from a single seed rather than comparing a known short-list.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description goes well beyond them: it discloses spatial de-duplication by cluster_km (why a metro yields distinct areas instead of 40 near-identical rows), that gas/fiber filters apply ONLY when the layer answers, state-grain (not jurisdiction-grain) moratorium context, and a next_calls handoff.

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?

Purpose is front-loaded in the first clause and the content is dense with distinct facts, but the "THE INVERSE QUERY" paragraph is rhetorically padded ("where should I even be looking?") and the closing examples partly duplicate the schema's own examples.

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 13-param open-world search tool with an output schema present, the description covers everything an agent needs: trigger condition, alternative routing, output shape (search areas with distances and coverage caveats), and example invocations. Return-value detail is appropriately left to the output 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% and the per-parameter docs are already detailed, so the baseline is 3. The description adds value by showing worked parameter combinations ("state=OH min_voltage_kv=230 max_gas_km=8" and "lat/lon radius_km=60 min_voltage_kv=500"), illustrating how the filters compose rather than restating definitions.

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 (find candidate data-center search areas) and pins down the mechanism (HIFLD substation anchors at/above min_voltage_kv, gas/fiber distances, cluster de-duplication). It explicitly contrasts itself with analyze_site, get_composite_site_score, rank_sites, find_alternatives and execute_plan, 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?

"Use this when the user has no data center site yet and wants candidate search areas" gives a clear entry condition, and it names the routing rule for multi-part siting questions (execute_plan). It frames the tool as the inverse of every coordinate-based sibling, effectively stating when NOT to use it.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds real operational context: a branded 5-page PDF, a link that needs no login, and a ~7-day validity window that the agent must relay to its human. It stops short of describing error behavior or what happens when a coordinate falls outside coverage.

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

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

Front-loaded with the trigger and the sibling exclusion, then the example, then the param recap — a sensible order with no wasted preamble. The trailing 'Params:' block largely duplicates a fully-covered schema and could be trimmed.

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

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

Output schema exists, yet the description still usefully sketches the return shape and calls out pdf_report_url as the actionable artifact, which is what the agent must hand back. Gaps: use_case is never mentioned, and the description insists lat/lon are 'required' while the schema declares zero required parameters — a mismatch that could cause the agent to demand a coordinate the schema treats as optional.

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 earns one more by pairing each core parameter with a realistic value in the worked example (lat=37.694 lon=-88.65 capacity_mw=150) and reinforcing defaults for prepared_by and latency_target. It omits use_case entirely and repeats range/default facts the schema already states, so it stays below a 5.

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

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

States a specific verb+resource (generate a shareable Site Analysis PDF) scoped to exactly one lat/lon parcel, and explicitly frames it as 'the polished client deliverable, not just a score.' It names the sibling it is not (analyze_site) so the agent can disambiguate 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 ('use this when the user wants a shareable ... PDF for ONE lat/lon'), a concrete worked example with realistic argument values, and a stated when-not ('For just the numeric suitability score (no PDF), use analyze_site instead'). Nothing about selection 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 only declare readOnly/idempotent/openWorld=false; the description goes well beyond them by disclosing that the roster is backend-owned and mutable, that clients must read platforms[] and per-row status rather than any enumerated list, and that mcp_active/mcp_ready are curated editorial claims with as_of null rather than live connection counts. That is exactly the kind of caveat an agent needs to avoid misreporting results.

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 usage condition and the when-not are front-loaded, which is good, but the passage is long for a zero-argument read tool. The 'an enumeration here goes stale ... exactly how a client named here stopped appearing in the roster' anecdote and the 'Try: get_agent_registry' filler consume space without adding decision-relevant information.

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

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

With an output schema present, the description need not explain return values, and annotations already carry the safety profile; the description nonetheless supplies the interpretive context (editorial statuses, as_of null, backend-owned roster) that keeps a caller from over-claiming. 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?

The tool takes zero parameters, so the baseline is 4; there is no parameter surface for the description to illuminate. It does describe the shape of the relevant response fields (platforms[], status), but that belongs to the output schema rather than to parameter semantics.

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

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

The description names a specific resource (the DC Hub AI platform/agent-framework registry) and states what it returns: platforms with recommended tools and an authentication tier. It also explicitly disclaims what it is ('a curated ecosystem/capability index, NOT live per-caller call/citation telemetry'), which distinguishes it from telemetry-adjacent siblings.

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

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

It gives an explicit triggering condition ('Use this when the user asks which AI platforms and agent frameworks integrate DC Hub'), an explicit exclusion ('Do NOT use for platform uptime or feed health'), and names the alternative tool to use instead (get_backup_status). 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), so the bar is lower. The description adds genuinely useful behavioral context beyond them: the semantic warning that 'unknown' means NOT measured, and that scope is exactly /api/health/data-freshness and nothing wider. It stops short of the full 5 only because there is no note on refresh cadence of the health check itself.

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 use case and row/rollup structure are front-loaded, which is good, but the text is bloated: the stray 'Try: get_backup_status' fragment is wasted, and the freshness question is effectively restated by both the 'are any of your sources stale' example and the '/api/health/data-freshness... nothing wider' scope sentence. Several sentences could be merged without loss.

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

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

An output schema exists, so return-value explanation is not strictly required, yet the description still previews row fields and the rollup. For a zero-parameter read tool with full annotation coverage, an agent has everything needed to call it 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?

The tool takes zero parameters, so the schema has nothing to document and the baseline is 4. There is no parameter syntax the description could meaningfully add, and it correctly avoids inventing any.

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 ('how current DC Hub's data center and power data feeds are'), enumerates the exact feeds returned, and describes both the per-row fields (health, record_count, refresh_interval, scheduler) and the summary rollup shape. It is unmistakably distinct from sibling data tools like get_changes.

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 ('Use this when the user asks how current... feeds are'), a sample user question ('are any of your sources stale right now'), and a named exclusion with the alternative ('Do NOT use for the freshness of one dataset (use get_changes)'). Nothing about when/when-not is left to inference.

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

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

Annotations already cover the read-only, idempotent, non-destructive, closed-world profile. The description adds meaningful context beyond that: the portfolio block only appears for 'keyed callers with saved sites', and the generated_at caching pattern for successive calls. Auth-conditional and caching behavior are disclosed.

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 'Use this when...' and information-dense throughout, with a concrete example call. Slightly long, and the trailing 'Answers ...' sentence partially restates the opening, but no sentence is pure 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?

Output schema exists, so return values need not be explained, yet the description still characterizes the response blocks richly. Between the triggering contexts, parameter shorthand, caching pattern, and keyed-caller behavior, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by restating the since shorthand/default and, notably, introducing the cache-and-replay pattern for generated_at, which is not obvious from the schema alone and clarifies how 'since' should be chained across calls.

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

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

States a specific verb+resource and enumerates exactly what it returns (DCPI 7-day market movers, newly discovered facilities, new M&A deals + news, plus a per-saved-site portfolio block). The 'changes since' framing is distinctive, but no sibling tool is named to explicitly contrast against the many adjacent tools (get_news, list_transactions, get_market_context).

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 triggering contexts: 'when the user asks what changed... since a date', 'what changed since I last looked', 'anything new this week'. This tells the agent when to reach for it, but it offers no explicit alternatives or when-not guidance against the numerous sibling intelligence tools.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered; the description adds real behavioral context beyond that: radius_km snapping to the nearest NOAA station with unavailable_exceeds_radius beyond it, US-only seismic coverage, and a strict no-estimation policy with missing data declared unavailable. It stops short of noting rate limits or latency.

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 alternatives, and most sentences carry weight. The full return-shape enumeration is largely redundant given a dedicated output schema exists, adding length without adding routing 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?

Complete for a six-parameter lookup with annotations and an output schema: it covers source grounding (USGS ASCE 7, NOAA/ACIS), scope limits (US seismic, station radius), failure modes, and sibling routing. An agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so the schema already documents all parameters (baseline 3). The description adds meaning beyond the schema by explaining the operational consequence of radius_km (default 25, station snapping, failure when exceeded) and confirming the lat/lon pair drives the whole lookup, which goes past the flat field definitions.

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 (retrieve seismic/climate design inputs for a lat/lon site) and names the exact dimensions it feeds (structural bracing cost, cooling design). It explicitly distinguishes itself from get_disaster_risk and get_composite_site_score, so an agent can route 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?

Opens with an explicit trigger condition ('when the user asks about seismic or climate design inputs') and names both alternatives with the condition that selects them (natural-hazard ratings → get_disaster_risk; one blended verdict → get_composite_site_score). 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 only declare the safe-read profile (readOnly/idempotent/non-destructive/openWorld=false); the description adds genuinely unavailable context: no imputation of missing factors, live provenance per factor (FEMA NRI, WRI Aqueduct 4.0), the rule that water is 'unavailable' rather than faked outside basin coverage, and that market/DCPI is v1-unavailable. This is exactly the operational nuance annotations cannot express.

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

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

The purpose and coverage-map distinction are front-loaded, and the alternatives are consolidated at the end. It is dense but long — the explicit return-shape enumeration duplicates an output schema that already exists, which is the one stretch that doesn't earn 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 scoring tool with an output schema present, the description still covers everything an agent needs: verdict scale (0-100, BUILD/CAUTION/AVOID), confidence semantics, coverage values (validated|unavailable), and the no-imputation contract that determines how results should be interpreted.

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 lat/lon/state/alias semantics are already documented, making 3 the baseline. The description adds a concrete example call (lat=33.45 lon=-112.07 state=AZ) but never mentions the lng/latitude/longitude aliases or that state is optional-but-helpful, so it 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?

The opening sentence states a specific verb (score) and resource (composite site suitability for a lat/lon) plus the distinguishing artifact: an explicit per-factor coverage map. It explicitly contrasts itself with analyze_site ('full raw data dump') and with the scoring scope ('scores ONLY over VALIDATED factors'), so an agent can separate it from 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?

It states the triggering condition ('when the user wants one 0-100 verdict WITH a coverage map') and then routes three alternatives by scenario: analyze_site for full data, compare_sites for 2-4 sites, rank_markets for whole-market ranking. Exclusions and substitutes 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 only declare readOnly/idempotent/openWorld=false; the description adds substantial behavior beyond that: the exact fallback when free text does not match (generic blurb with matched_category=null and context_understood=false), the is_generic_answer/answer_note/next_tools fields on non-matching input, and the fact that it never computes a siting answer. This is rich disclosure 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?

The trigger and the exclusions are front-loaded, which is good, but the four categories are listed twice and the return-shape enumeration duplicates the output schema, adding bulk without new information. Information-dense but not tightly edited.

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-optional-param tool with an output schema, the description covers everything needed: trigger, valid inputs, fallback semantics, and routing to the correct alternative tools. The repetition of return fields is redundant with the output schema but does not leave a gap.

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

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

Schema coverage is 100%, but the schema's own description is misleading — it advertises free text like "100MW AI training campus in Texas" while the tool actually requires one of four literal categories. The description corrects this and enumerates the four valid values (the schema declares no enum), which is essential meaning added beyond the schema. It falls short of 5 only because the underlying schema remains contradictory and could still mislead.

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: it returns a DC Hub blurb in one of four named categories plus the live top-ranked market pocket. It explicitly distinguishes itself from analyze_site, rank_markets, and site_selection_canvas, so an agent can tell exactly what this tool is not.

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

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

It gives an explicit trigger ("Use this when the user asks what DC Hub is") and an explicit do-not-use list, each paired with the correct alternative (single lat/lon -> analyze_site, one-criterion ranking -> rank_markets, computed shortlist -> site_selection_canvas). 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, openWorld), so the bar is lower, and the description still adds real behavior: live query rather than estimate, explicit out-of-coverage fallback (coverage=unavailable), county-level rather than parcel resolution, and a caveats field. It does not mention auth/API-key requirements or rate limits, which is the only 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?

Roughly 100 words, front-loaded with the trigger and source, then example, then return shape, then sibling routing. Every clause carries information; nothing is restated from the title or 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?

For a lookup tool with an output schema and full annotation coverage, the description supplies everything needed to call it correctly: source, resolution, coverage semantics, fallback behavior, and the alternatives. Return-field enumeration is redundant against the output schema but harmless and aids scanning.

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

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

Schema description coverage is 100% and the schema already documents ranges and the alias names (latitude/longitude/lng), so the baseline is 3. The description adds value by pinning the constraint to US coordinates and supplying a concrete invocation example (lat=33.45 lon=-112.07), but it does not explain how the aliases interact if multiple are passed.

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 with explicit scope: natural-hazard risk for a US data-center site, grounded in the FEMA National Risk Index. It enumerates the hazard classes covered (flood, wildfire, hurricane, earthquake, heat, drought, tornado) and is trivially distinguishable from get_water_risk and get_composite_site_score.

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

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

Opens with an explicit trigger ('Use this when the user asks about natural-hazard risk for a data center site'), then routes away to two named alternatives with their own conditions (chronic water stress -> get_water_risk; blended site verdict -> get_composite_site_score). No inference required.

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 past the readOnly/idempotent annotations: it discloses data provenance (EIA), staleness (~3 months behind, latest_period names the month), and an access-tier behavior that would otherwise look like a failure (anonymous/free-key seats return null with gated: true; email-bound key unlocks). That gating note alone is high-value context an agent cannot infer from the schema.

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

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

Front-loaded with the trigger condition and the disambiguation warning, then details. It is a dense single paragraph with some redundancy, since a large chunk enumerates return fields (avg_cents_kwh, min/max, latest_period) that the existing output schema already declares — but the units note (cents/kWh vs dollars/kWh) justifies much of that.

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 pricing tool it covers what an agent needs before calling: units, staleness, geographic granularity, the national-only nature of the gas benchmark, and the gated-access failure mode. Return values are also covered by an output schema, so 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 coverage is 100%, so the baseline is 3; the description earns a bump by explaining that an ISO value is the average of its member states, that omitting both yields a US figure, and — critically — that data_type is accepted but does not change the response, correcting a schema description that lists 'wholesale' as a valid focus the tool cannot actually serve.

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 (retrieve EIA retail electricity and Henry Hub gas prices) and scopes it to ISO/state/US geography. It explicitly carves out what it is not — 'no wholesale/LMP price and no grid-status flag' — which separates it from siblings like get_gas_index, get_grid_scoreboard 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 the exact user phrasing that should trigger it ("what does power cost in ERCOT?", "retail rate in Virginia?") and includes a worked invocation example. It also names a boundary condition: price alone does not rank sites, so ranking belongs to execute_plan.

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/non-destructive profile, and the description adds traits beyond them: single-record scope ("Returns ONE facility in full"), a 404 not-found recovery loop, and the gating behavior ("Gated: give human_url to your human") which the agent could not learn from the schema. This is exactly the kind of operational context annotations cannot express.

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

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

The routing constraint and single-vs-many distinction are front-loaded in useful order, and every sentence carries operational content. The long field enumeration is dense but justified by the 'tell me everything about this facility' use case, though it makes the opener heavier 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 single-entity lookup with six optional/aliased params, full schema coverage, and a declared output schema, the description covers scope, prerequisites, failure handling, and gating. There is no material gap an agent would hit on invocation.

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

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

Schema coverage is 100% and the schema already explains facility_id/slug/name aliases, so the baseline is 3. The description earns a point above baseline by supplying concrete call syntax examples (equinix-dc1-ashburn, the long digital-realty slug) and reinforcing that identifiers must come from search_facilities. The two include_* toggles are left entirely to the schema.

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

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

The description opens with a specific verb+resource (fetch one data center facility) and enumerates exactly which fields come back, so an agent knows the payload shape before calling. It explicitly contrasts with the sibling search_facilities for multi-result queries, making it unambiguous.

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

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

It states when to use it ("when the user asks about one data center facility"), when not to ("do NOT use to search or list many facilities (use search_facilities)"), plus the prerequisite ("Needs a slug or id from search_facilities") and the recovery path for a 404. 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, but the description adds substantive behavioral context beyond them: only DCPI market-health has a temporal series, the hazard dimensions are declared static and never fabricated into week-over-week deltas, and missing snapshot history returns coverage:unavailable. This is exactly the integrity/edge-case disclosure 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 usage trigger and return shape, and the integrity caveat earns its length. It is dense and somewhat long, with the parameter list and return signature partly redundant against the schema, but no sentence is pure filler.

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

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

For a tool with 3 optional params, an output schema, and subtle coverage semantics, the description covers trigger, scope, integrity behavior, return shape, and sibling alternatives. An agent has everything needed to select and invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds the OR/mutual-exclusion relationship between facility_id and market and restates the default window (7d). It largely mirrors the schema descriptions, so it is a modest rather than substantial gain.

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: how a facility's (or market's) power risk changed recently, framed by the user question it answers. It explicitly distinguishes itself from 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?

Gives an explicit trigger ("has this site gotten riskier lately?") and names the alternative tools plus the exact condition (current point-in-time risk vs change) that selects them. When-to-use and when-not-to-use are both 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 read-only/idempotent/non-destructive, and the description adds genuinely non-obvious context: free callers get a sample rather than the full route set, the full set requires a paid key, and the tool is gated so the agent must surface a human_url to its operator. The return-field list (carrier, type, fiber count, lit capacity, distance) is somewhat redundant with the existing output schema, 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?

Front-loaded with the trigger condition, then access limits, then parameters, then the sibling redirect — good ordering. Slight redundancy in repeating the filter fields ('Filter by carrier, route_type, market' followed later by 'Filter by market ... or carrier') 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?

An output schema exists so return values needn't be explained, yet the description still summarizes them; combined with the free/paid access disclosure and the gating instruction, an agent has what it needs to call this correctly. Minor gaps remain around result limits, pagination, and how multiple filters compose.

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 four parameters are already documented in detail, including route_type values and market slug examples. The description only restates the filterable fields and adds the useful note that market accepts a slug from rank_markets; it does not clarify whether market and carrier are combined with AND or how include_sources affects shape. 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 and resource (retrieve fiber routes/carriers/connectivity for a market) and enumerates the route classes it covers: long-haul, metro, dark, IX. It also distinguishes itself from the nearest sibling by saying 'For one building use get_facility,' so an agent can route 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 ('when the user asks about fiber routes, carriers or connectivity for a market'), explicit filter combinations, a named alternative for the building-level case, and even an example query ('Zayo long-haul routes via Dallas'). The pointer to rank_markets for the market slug is actionable routing guidance.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds substantial context beyond them: the data provenance (PeeringDB), null-scoring semantics tied to carrier_data_coverage, and the critical 'unknown is NOT bad' distinction between 'no carrier serves this point' and 'PeeringDB does not describe this region'.

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 purpose well and the example is helpful, but the full enumeration of return fields duplicates the output schema and adds length. Mostly efficient, with one redundant 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?

For a tool with a full output schema, the description is more than complete; the return-value listing is redundant but not harmful, and the coverage/unknown nuance is exactly the kind of context an agent needs. Slightly over-complete rather than under.

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 including the aliases (lng/latitude/longitude) and radius ranges. The description restates the same ranges and defaults without adding new meaning, so the baseline 3 applies.

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

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

States a precise verb+resource+scope: 'whether one data center site (lat/lon) is fiber-ready' with the specific sub-signals (near-net distance, carrier count, single-carrier risk). This scoping to a single site distinguishes it from sibling tools like get_metro_fiber and get_fiber_intel without the agent needing to open 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?

'Use this when the user asks whether one data center site is fiber-ready' gives clear triggering context and a concrete example query. It implicitly distinguishes the single-site scope from metro/sibling tools but never explicitly names an alternative or states when NOT to use it, so it falls 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/open-world, so safety is covered. The description goes further with behavioral caveats: each layer carries its own source label, gas_to_grid_status carries the reason if the backend switch is off, and — most valuably — the warning that $/MWh values published before 2026-09-27 were computed differently and can differ up to 5.5x. That is real disclosure beyond the structured fields, despite awkward wording.

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

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

The description is front-loaded with the core purpose, which is good, but it contains an obviously truncated fragment ('AZ, GA, FL), never a substitute price; if the backend switch is ever turned off again') and interleaves caps-lock warnings with unrelated notes. Multiple sentences do not parse cleanly, which harms an agent's ability to extract rules reliably.

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-value explanation is not required. The description supplies the trigger, the scope of returned layers, the exclusion and alternative, and the critical cross-date comparability caveat. Given the tool's complexity and the presence of an output schema, this is largely complete — the damaged fragments are the main residual gap.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema (market slug with examples, optional heat_rate_btu_per_kwh with an example). The description repeats the market slug guidance without adding format or constraint detail, and never mentions the heat-rate parameter. Baseline 3 is appropriate when the schema carries the load.

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

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

The first sentence names a specific resource (behind-the-meter gas power economics) and enumerates the three layers returned — Henry Hub spot, regional basis differential, and the delivered industrial + electric gas tariff in $/MMBtu. It also distinguishes itself from the electricity-mix sibling by routing that case to get_grid_data. The purpose is clear, though a garbled mid-sentence fragment ('AZ, GA, FL), never a substitute price') muddies the edges.

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 an explicit trigger ('Use this when the user asks what behind-the-meter gas power costs in a US data-center market') and an explicit exclusion ('Do NOT use for the electricity grid fuel mix (use get_grid_data)'), naming the alternative. The temporal-comparison warning and the 'do not derive a $/MWh yourself' instruction add further usage constraints. Only the corrupted fragment keeps this from being fully clean 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 a safe, idempotent read, so the bar is low, yet the description adds substantial behavioral context: the index-versioning hazard (differing DCGI figures before/after 2026-08-08), where the full methodology record lives, and the UNSCORED-not-low-score semantics. It also explains that gas_price_series identifies which EIA series priced each state.

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

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

Front-loads the core purpose before the caveats, and most sentences (UNSCORED semantics, version warning, sibling routing) earn their place. It is somewhat packed with dated incident detail (same-day withdrawal, 2026-09-27 republish) that could be tightened, but it remains readable.

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 need not be re-explained, and the description still covers the two things an agent must not get wrong: cross-version comparability and treating UNSCORED as absence. Alternatives and the methodology endpoint are also supplied.

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 (limit, state) are already fully documented, which sets the baseline at 3. The description adds semantics around state output (verdict, gas_price_series) but nothing new about parameter syntax or constraints 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+scope: 'which US states suit gas-fired data center power' scored per-state by the Data Center Gas Index (DCGI). It is clearly distinguishable from sibling gas tools, naming get_gas_intelligence (pipeline/operator/midstream) and get_gas_economics as the alternatives.

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

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

Gives an explicit trigger ('Use this when the user asks which US states suit gas-fired data center power') and explicit routing away from siblings ('Use get_gas_intelligence for pipeline, operator and parent-midstream data'), plus a reference to get_gas_economics. When-to-use and when-to-use-something-else are both 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 cover the safety profile (readOnly, idempotent, non-destructive), and the description layers on substantial behavioral context beyond them: freshness cutoffs for DCGI and $/MWh, synthetic-labeled basis, nulls surfaced honestly rather than fabricated, and the caveat that gas_access is presence not firm capacity. This is exactly the extra detail 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-loads the use case and keeps sentences information-dense, but enumerates the full return object even though an output schema exists, which is partly redundant. Still well-ordered and free of filler.

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

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

For a high-complexity intelligence-fusion tool, it covers triggering, provenance/confidence, staleness rules, and honest-null behavior. With an output schema present it needn't explain returns, yet its extra caveats add rather than pad.

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

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

Schema coverage is 100%, so both region/state params are already documented, and the description largely repeats the state-code-or-name format. It does not add new syntax or constraints beyond the schema, 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 (fuse gas economics into a per-state brief) and explicitly frames itself as 'the GAS analogue of get_grid_intelligence', letting an agent distinguish it from grid/energy siblings. The example user questions make the scope concrete.

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 and sample utterances ('is gas power cheaper than the grid in Texas?'), names the sibling it mirrors, and adds hard exclusions ('DO NOT quote a DCGI score cached before 2026-08-30'). When-to-use and when-not-to-use are both present.

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 substantive context beyond that: dataset provenance (Global Integrated Power Tracker, 182,000+ geolocated units, 170+ countries), the exact definition of the pipeline set, and the return shape (summary of total MW by fuel plus largest units). It does not mention pagination or rate limits, keeping it 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?

It is a long, dense paragraph, but it is front-loaded with the use case, then filters, then returns, then exclusions, then a try-example — every sentence contributes. Slightly overpacked, 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?

With an output schema already present, the description need not detail return values, yet it still sketches them. Combined with scope, filter semantics, dataset coverage, and explicit sibling routing, an agent has everything needed to select and invoke this tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description meaningfully enriches it: fuel is 'comma-union', pipeline=true means ONLY the forward set (announced + pre-construction + construction), bbox is minLng,minLat,maxLng,maxLat, and country/status examples are given. This is more semantic detail than the schema fields carry.

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

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

The description names a specific verb+resource (retrieve global power plant asset inventory) and precisely scopes it: operating AND forward pipeline across ALL fuels, worldwide. It explicitly distinguishes itself from the US-focused siblings get_grid_intelligence, get_grid_scoreboard, and get_power_pipeline, 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?

It states when to use it ('user asks about power plants worldwide or in a non-US country'), when NOT to use it (US grid telemetry/headroom, US planned-generator feed), and names the specific alternative tool for each exclusion. Concrete example queries ('what power is being built in India') and a 'Try:' invocation remove ambiguity.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the description goes further and discloses the return semantics that matter: US ISOs/EIA regions return EIA hourly fuel mix plus 24h curve, while other grids return each feed's newest reading per metric with its own timestamp. It even pre-empts a likely misinterpretation by noting installed_capacity_mw is EIA-860M net summer capacity for the report month, not PJM committed capacity (which appears value-less in licence_withheld).

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: the trigger condition and scope come first, followed by coverage, then return behavior, then exclusions. Every clause is doing work, though the installed_capacity_mw/licence_withheld passage is dense enough that it borders on over-specification for a first-read.

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

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

For an open-world tool spanning hundreds of grid codes, the description covers coverage, per-family return differences, a known data caveat, and routing to three alternatives. With an output schema present, it has no obligation to describe return field structure, and 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 schema already documents iso, metric and period, making 3 the baseline. The description adds some value by expanding the accepted grid-code vocabulary (EU_DE_LU bidding zones, city names like PHOENIX/ATLANTA) and naming the metrics produced (fuel_mix, demand, demand_curve), but it does not explain how 'metric' or 'period' alter the response shape.

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

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

Opens with a specific verb and resource (live electricity grid data: power demand, fuel mix) and scopes it to one grid, then enumerates exactly which grid families are supported. It also names the sibling tools it is not (get_grid_intelligence, get_energy_prices, get_grid_scoreboard), 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?

Explicit when-to-use (user asks for live demand/fuel mix for one grid) and explicit when-not-to-use, each with the correct alternative named: power-availability/queue analysis -> get_grid_intelligence, retail/gas pricing -> get_energy_prices, ranking many grids -> get_grid_scoreboard. 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?

Beyond the read-only/idempotent annotations, the description discloses rate and access behavior (a few full briefs per day on a free key, trimmed preview when keyless, unlimited only with a paid key) and an explicit error outcome (non-US-ISO codes return region_not_covered). It also proactively warns that avg_time_to_power_months and avg_queue_wait_months are different measurements, preventing a costly misreading of the output.

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 outputs, then caveats, then access tiers, then an example — a sensible order with no filler prose. There is some redundancy: "keyless gets a trimmed preview" is restated as "Free = preview" in the final sentence, which costs a few words without adding 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?

An output schema exists, so return-value documentation is correctly omitted, and the description covers access tiers, valid inputs, error behavior, and a metric disambiguation warning. The only gap for a multi-alias lookup tool is that it never says what happens when more than one of the alias parameters (region_id, iso, region, market) is provided.

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 meaning beyond the schema: it enumerates the seven accepted ISO codes and specifies the failure mode for anything else (region_not_covered), which the schema does not state. It does not address precedence when multiple of region_id/iso/region/market are supplied simultaneously.

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 (return live grid capacity/headroom/time-to-power data) and scopes it to US ISOs and named markets, listing the exact data families returned (demand, fuel mix, queue depth, DCPI, reserve margin). It does not distinguish itself from closely related siblings such as get_grid_scoreboard, get_iso_context, or get_interconnection_queue, so an agent must infer which of those to call for overlapping questions.

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 this when the user asks about grid capacity, power availability, headroom or time-to-power" is an explicit positive trigger, and the example query ("PJM headroom for 200 MW?") grounds it. It also explains the access tiers (keyless preview / free key / paid unlimited), which is a real usage constraint. It stops short of naming when NOT to use this and which sibling to use instead.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds the crucial non-obvious trait: freshness is not uniform, US mix data can be 18-24h stale while demand is 1-2h old, with per-row mix_period, mix_age_hours and freshness_basis. That staleness warning materially changes how an agent should interpret and present results, which is exactly the value structured fields 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?

The trigger sentence is well front-loaded, but the middle is bloated: a long parenthetical on ENTSO-E zone counting that defensively explains its own measurement methodology ("measured per call rather than asserted here"). The "Try: get_grid_scoreboard" filler and the resource pointer add length without adding selection 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, the description needn't explain return values, and it already covers coverage scope, ranking basis, and the freshness caveat critical to interpreting results. What's missing is minor: how many rows are returned, ordering guarantees, and whether rows with stale mixes are flagged versus filtered.

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

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

There are zero input parameters, so there is nothing to disambiguate and the baseline is a 4. The description's mention of counts_basis.eu_zones_live / eu_zones_configured refers to output fields rather than inputs, which is fine since an output schema exists.

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

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

States a precise verb and resource — a global scoreboard ranking grid operators side-by-side on latest published demand, fuel mix, and renewable share — and enumerates the covered regions in detail. The purpose is unmistakable, but it never names siblings such as compare_isos or get_global_power, so the agent must infer the boundary from scope alone.

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 this when the user asks how power grids compare: demand, fuel mix or renewable share" plus the example questions gives a clear activation trigger tied to user intent. However, it gives no explicit when-not-to-use guidance and no named alternatives for narrower comparisons.

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 this a read-only, idempotent, non-destructive, closed-world call, so the safety profile is covered. The description adds genuinely new behavioral context: the data provenance (utility's own GIS, 'filed distribution-level truth'), the coverage breadth with named utilities, the no-args coverage behavior, default radius 25 / max 150, and that utility mode spans the full published extent.

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 before the detail, and the closing example invocation is efficient. The parenthetical enumeration of a dozen-plus utilities is useful evidence of coverage but is the one stretch that verges on bloat.

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 described. For an 11-parameter, all-optional tool the description supplies the mode semantics, defaults, coverage, and provenance an agent needs to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3 and the schema already documents aliases, bounds, and capacity_type values. The description goes beyond that by explaining how parameters compose into call modes (point vs. utility vs. no-args) and supplies a concrete example invocation, which the schema alone does not 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 — 'utility-published hosting capacity', the MW a named distribution feeder can take — and explicitly distinguishes itself from siblings that give proxies ('not a proximity proxy'), which matters in a family dense with get_grid_data, get_power_availability_timeline, and get_interconnection_queue. An agent can tell exactly what this returns 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?

Opens with an explicit trigger ('Use this when the user asks how many MW a distribution feeder can take') and enumerates the three calling modes (lat/lon point, utility/market territory, no-args coverage list) plus example questions it answers. It also rules out the proxy-style tools, so the agent knows when to route elsewhere.

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

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

Annotations already establish readOnly/idempotent/non-destructive, so the bar is low. The description adds real behavioral context beyond them: provenance (EIA public domain, five ISO project lists), a critical grain caveat that a row count is a count of upgrades rather than whole projects, and the delisting/source-release behavior implied by include_delisted.

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 deliberately structured: trigger statement first, then COVERS, then NOT, then a worked example, so the load-bearing guidance is front-loaded. The coverage block is dense but each clause (sources, fields, grain) carries information an agent needs to interpret results correctly.

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 need not be explained, and the description covers everything else: what is included and excluded, source provenance, per-source grain, status vocabularies, and units. Nothing an agent needs to invoke or interpret this 10-parameter, zero-required tool is missing.

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

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

Schema description coverage is 100%, so the schema already carries parameter documentation and the baseline is 3. The description still adds value by enumerating status vocabularies, giving unit meaning (MMcf/d, $M, kV), explaining the per-ISO grain of transmission rows, and showing a concrete invocation pattern (type=gas_pipeline state=LA status=Construction).

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 (retrieving planned/proposed/approved/under-construction infrastructure projects) and immediately scopes it against the existing network, so it is distinguishable from sibling tools like get_pipeline or get_infrastructure. The two coverage categories (EIA gas pipelines, five ISO transmission lists) are named explicitly with their source lists.

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 triggers ('what ... are planned, proposed, approved or under construction — the forward build-out, not the existing network') and sample queries, plus negative scope (NOT CAISO or NYISO, not utilities outside those ISOs). It stops short of naming the alternative sibling tool an agent should pick for the existing network, leaving that routing to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the safety profile is covered structurally. The description adds meaningful context beyond that: the upstream data sources (HIFLD/EIA), that results are 'raw nearby assets' rather than scored output, and that each asset carries distance and capacity. It does not discuss pagination or rate limits, but with strong annotation coverage that gap 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?

The description is dense and front-loads the core purpose before enumerating layers and the exclusion. Every sentence carries information, though the listing of layers plus data sources plus sample query makes it slightly long; nothing is wasted but it is near the upper practical length.

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

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

An output schema exists, so return-value documentation is not required, yet the description still summarizes the shape (distance + capacity per asset). With 9 params fully covered by the schema, annotations handling safety, and an explicit sibling exclusion, 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 the baseline is 3, but the description adds semantics the schema alone doesn't convey: layer values map to distinct asset types (substations/transmission/pipelines/power_plants), transmission is filtered at >69 kV, and power plants are split into operating + planned by fuel. The worked example (lat/lon/radius_km) also demonstrates intended usage beyond the field 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?

The description gives a specific verb and resource ('what power infrastructure is near a site') and enumerates exactly what is returned: substations with count and max voltage, transmission lines over 69 kV, pipelines, and power plants by fuel. It explicitly distinguishes itself from the sibling analyze_site, so an agent can route correctly 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?

It states when to use it ('when the user asks what power infrastructure is near a site'), supplies sample utterances that trigger it, and names the exclusion: 'do NOT use for a single scored site-suitability verdict (use analyze_site).' Both the trigger and the anti-trigger are present with the alternative 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?

Annotations already declare readOnlyHint/idempotentHint/destructiveHint=false, so safety is covered. The description adds genuine context beyond that: the score's composition, its 0-100 range, the 300+ market comparison set, and the 7d/30d trend output. It does not cover rate limits or data freshness/latency, which keeps it 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?

Front-loaded with the trigger and the return summary, then the routing exclusions. Dense and mostly waste-free, though the long component enumeration and the duplicated 'one composite health number' phrasing cost a little.

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-shape explanation is a bonus rather than a requirement, and the description still sketches the key returns. For a zero-parameter read 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?

Zero declared parameters, so the baseline is 4. The description supplies a concrete call example ('get_intelligence_index market=northern-virginia'), though this implies a 'market' argument the empty schema does not define, which is a minor inconsistency rather than added semantic depth.

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 ('composite score (0-100) aggregating supply/demand balance, vacancy, absorption velocity, fiber depth, power availability, and pricing trend') and explicitly names the siblings it is not (get_market_intel, rank_markets). An agent can distinguish this from the 90+ other 'get_*_intel' tools 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 an explicit trigger ('when the user asks how healthy a data center market is'), sample utterances it answers, and two named exclusions with the correct alternatives for each (full metric set → get_market_intel; multi-market ranking → rank_markets). 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?

Adds substantial context beyond the readOnly/idempotent annotations: access tiers (trimmed preview when keyless, full data with an emailed-bound key), the conditional shape of the projects field depending on whether iso is supplied, and the ERCOT-only large-load queue with the note that other ISOs don't publish one. These are exactly the operational quirks an agent cannot infer and would otherwise be surprised by.

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 and the primary return value, and every clause carries information. The dense, fragmentary style ("Ex: ...", "iso optional (US ISO code); free = preview") is efficient but borders on shorthand that takes a second pass to parse.

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

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

Complete for a single-optional-parameter read tool: annotations carry the safety profile, an output schema exists so return values need no prose, and the description still supplements it with access tiers, conditional response shape, an ERCOT-specific caveat, and a cross-reference. Nothing essential 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% and the enum of ISO codes is already documented, so the baseline would be 3; the description earns above that by explaining the behavioral consequence of setting iso (per-project rows vs. an all-ISO summary object) and labeling it optional. The trailing "iso optional (US ISO code); free = preview" fragment is terse and partly redundant, which keeps it from a 5.

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

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

States a specific verb and resource — returns queued generation GW per ISO — and frames the user-facing question it answers (queue congestion, data-center load waiting). An agent can distinguish it from get_grid_intelligence or compare_isos 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 triggering context ("how congested an ISO's queue is", "how much data-center load is waiting") and names a companion call (get_grid_intelligence) for demand/headroom. It does not address overlap with other queue-adjacent siblings like get_refined_queue, get_pipeline, or compare_isos, so the routing is clear but not exhaustive.

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, openWorld), and the description still adds real behavior: greedy priority-order fill under a budget, per-section token accounting, and the tier gate ('locked_sections need a higher tier') which is a paywall constraint no annotation discloses. It also imposes a citation attribution requirement.

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 the section inventory before the exclusion list, and the example call is compact and high-signal. The section enumeration is a long clause but every item is a distinct capability rather than filler; slightly denser than ideal, though nothing is padding.

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