DC Hub — Data Center Intelligence MCP Server

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

Annotations already cover readOnly, idempotent, and non-destructive behavior. The description adds refresh cadence (Fridays 14:00 UTC), the 100MW threshold, a caveat that facility-dependent signals appear only where data carries them, and composition of the composite score. No contradiction with annotations.

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

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

The description is four tightly packed sentences: purpose, return fields, refresh schedule, and usage guidance with exclusions. Every clause delivers information without redundant phrasing.

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

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

Given the output schema and annotations, the description fully covers when to use, what to expect, freshness, and output fields. It also addresses edge cases (facility data availability) and alternatives, leaving no critical gaps.

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 provides 100% coverage for both parameters, including ranges and defaults for limit and horizon. The description aligns with the horizon semantics but adds no new parameter-level detail, so baseline 3 is appropriate.

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

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

Description states it ranks data center markets specifically by where 100MW AI training capacity can land within 30/60/90 days, using a specific verb and resource. It also explicitly distinguishes this from sibling tools by naming rank_markets and grid_transition_radar as alternatives.

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

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

Explicitly states when to use: AI capex planning, GPU cluster siting, hyperscaler deal forecasting. It also gives clear when-not-to-use guidance with concrete alternative tools (rank_markets for general best-markets, grid_transition_radar for grid-emergence).

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

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

Beyond the annotations (readOnlyHint, idempotentHint), the description discloses key behaviors: a 404 with coverage list when point is outside hosted coverage rather than a guess, and the representative_point logic that avoids off-parcel centroids. This adds valuable context for the agent.

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

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

The description is dense and front-loaded, but it's a single long paragraph that could benefit from structure. Despite the length, every sentence provides useful context, including edge cases and alternatives, so it remains efficient.

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

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

The description is complete for a complex tool: it explains input modes, output fields, error behavior, and handoff to other tools. With an output schema present, it doesn't need to enumerate return values in full, and it covers all necessary invocation details.

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

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

The schema already covers all 7 parameters with descriptions, so the baseline is 3. The description adds the two-mode usage (geometry vs lat/lon) and clarifies the capacity_mw pass-through to the handoff, adding meaning beyond the schema.

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

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

The description clearly states the tool performs a structured read of a parcel boundary, accepting either a GeoJSON polygon or lat/lon coordinates to find the containing parcel. It explicitly differentiates from siblings like analyze_site and get_refined_queue, making its scope unambiguous.

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

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

The description provides explicit usage guidance: 'Use when you HAVE a boundary or a point on a specific parcel and want it anchored + sized' and names alternatives for other cases. It also explains that queue rows lack parcel identity, preventing incorrect joins.

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 behavioral detail beyond annotations: free vs paid return tiers, candidate_id behavior (frozen mint, ignores lat/lon, expires fail closed), and a note about imputation differences with get_composite_site_score. It is consistent with the readOnlyHint and idempotentHint annotations, with no contradictions.

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

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

The description is dense but well-structured: usage statement, example, parameter details, return values, free/pro breakdown, and exclusions/alternatives. Every sentence serves a distinct, actionable purpose; there is no filler or redundant content given the tool's complexity.

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

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

The description covers all essential aspects: purpose, parameters, return structure (including free vs paid), alternative tools, exclusions, and edge cases like candidate_id expiration. The output schema exists, but the description adds lifecycle context and user intent guidance that make it practically complete.

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

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

Even though schema coverage is 100%, the description enriches parameter understanding: explains lat/lon aliases, clarifies candidate_id takes precedence and ignores lat/lon, gives a typical capacity_mw range (50-500), states boolean defaults, and provides a full example call with concrete values. This goes well beyond the schema.

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

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

The description clearly states the tool performs a full multi-factor data-center suitability read for a single specific site (lat/lon or candidate_id), with a concrete example. It explicitly distinguishes from sibling tools like compare_sites and find_alternatives, making its purpose unambiguous.

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

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

Explicitly opens with 'Use when a user has ONE specific lat/lon...' and provides 'Do NOT use' guidance naming compare_sites and find_alternatives as better alternatives for other scenarios. It also points to dedicated tools for water, disaster, climate, and tax reads, giving clear when-to-use and when-not-to-use context.

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

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

The description discloses far beyond annotations: the HONEST LADDER (10 free calls, then previews, binding restores 50/day), free binding, email usage solely for recovery/receipts, no marketing without explicit opt-in, unsubscribe capability, and behavior on rejected emails. It even instructs the relaying agent to surface the purpose line to the human, covering consent expectations.

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

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

The description is long but exceptionally well-structured: it front-loads the purpose, then flows through trigger conditions, behavioral tiers, consent, and fallback behavior. Each sentence adds unique value, and the use of sections/caps keeps it scannable despite length.

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

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

Given the tool's complexity (state change, consent, recovery, tier gating) and the presence of an output schema, the description covers all necessary aspects: when to call, what happens before/after, failure handling, and return value. No significant gaps remain.

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%, yet the description adds crucial semantics: email is required and must be explicitly provided (with rejection of placeholders), api_key can be omitted to bind the current session's key, and marketing_opt_in must only be true after explicit agreement. This goes well beyond the schema's property descriptions.

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

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

The description opens with a specific verb+resource: 'Tie your DC Hub key to your human's email' and immediately states the benefits (recoverability, receipts). It clearly distinguishes itself from siblings like recover_my_key and subscribe_digest by focusing on the binding action and its direct purpose.

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

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

It explicitly states when to call ('Call this once your human shares their email'), when not to call ('If your human hasn't shared an email, ask them first — don't call this tool with a made-up value'), and provides an alternative action (asking the human). The HONEST LADDER gating scenario gives a concrete trigger for mid-task usage.

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

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

The description goes far beyond the sparse annotations, disclosing that re-minting resets the daily allowance and orphans history, that keys are recoverable with an email, and that the key must be set as an `X-API-Key` header. This is rich, honest behavioral disclosure without contradicting the annotations.

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

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

The description is heavily padded with motivational statistics, marketing language, and repeated warnings, making it far longer than necessary. While the most important info is front-loaded, the extra sentences about funnel percentages and 'fastest path' dilute the message and violate the 'every sentence earns its place' standard.

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

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

Given the tool's complexity and the presence of an output schema, the description is exceptionally complete. It covers free-tier limits, upgrade path, email recovery, key reuse, and post-mint actions, leaving no critical operational detail unaddressed.

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

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

The input schema already fully describes both parameters with 100% coverage. The description adds some nuance (email makes the key recoverable; client_name is for attribution), but these are modest enhancements over the schema and do not fundamentally change parameter understanding.

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

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

The description clearly states the tool mints a free dev key with a specific verb and resource, and differentiates it from sibling tools like `recover_my_key` and `unlock_more_data`. The purpose is unambiguous and immediately actionable.

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

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

It explicitly tells the agent when to call (upon hitting a paywall), when not to call (if already holding a key), and points to `recover_my_key` as the alternative for lost keys. It also instructs to use the key on the very next call, providing clear behavioral guidance.

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

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

Even with annotations indicating readOnly/idempotent/non-destructive, the description goes far beyond by disclosing fail-closed candidate handling (expired/unknown ids dropped and declared), the distinction between physics floors and inferred estimates, confidence provenance tiers, and the caution not to treat estimates as engineered quotes. This richly informs the agent about edge cases and trust boundaries.

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

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

The description is long but every sentence carries essential detail: purpose, usage triggers, input contract, output summary, caveats, and alternatives. It is front-loaded with the core purpose and follows a logical structure. While slightly verbose, this is justified for a tool with subtle physics-vs-inference distinctions and fail-closed semantics.

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

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

Given the tool's complexity, the description is fully complete. It includes input formats, output structure (_entity=latency_clusters with fields), examples, parameter semantics, confidence tiers, and explicit pointers to related tools. With an output schema present, there is no gap in either the structured or unstructured information. The agent can select and invoke this tool correctly without requiring further clarification.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful context: explains how candidate_ids resolve to frozen mint coordinates, explicitly states the fail-closed behavior for expired ids, gives typical sync replication latency budgets, and notes that cand_… tokens may be mixed into the sites string. These details exceed the schema descriptions, so a 4 is warranted.

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 phrase: 'Physics-bounded latency clustering for 2-8 sites' and immediately states the deliverable: 'returns viable low-latency clusters and pairwise RTT floors before any routing work.' It clearly distinguishes itself from sibling tools like plan_fiber_leadin and get_fiber_readiness by contrasting goals, making the purpose unmistakable.

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

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

The description explicitly states when to use the tool ('Use when your human wants to know which of N candidate sites can form a synchronous / low-latency cluster') and provides explicit alternatives: 'For actual route corridors use plan_fiber_leadin; for a single-site connectivity score use get_fiber_readiness.' It also gives a candidate contract linking to get_refined_queue, which orients the agent on workflow context.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the description doesn't need to restate safety. It adds value by explaining the comparison aggregates data from multiple ISOs in one call, lists the valid ISO set, and details the return structure. No contradictions with annotations.

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

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

Every sentence provides essential information: usage context, example, parameter constraints, return structure, and exclusions. It is front-loaded with the primary use case and remains focused without redundant filler.

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

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

Given the tool has a single parameter, an output schema, and clear annotations, the description fully covers the operational context. It explains what data is returned, valid inputs, and explicitly names alternative tools for different use cases, leaving no ambiguity about when to invoke it.

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

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

The schema description already covers the parameter well, but the tool description adds the exact valid ISO codes and emphasizes the 2-4 max count. It also clarifies that the codes are drawn from the 7 live US ISOs, going beyond the schema's description. Minor inconsistency: schema uses 'ISONE' while description uses 'ISO-NE', but this doesn't undermine overall 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 opens with "Use when a user wants a side-by-side of 2-4 ISO grids" — a specific verb (compare) and resource (ISO grids) with explicit attributes (fuel mix, demand, renewable/gas share, etc.). It also distinguishes from siblings by naming get_grid_intelligence and get_grid_scoreboard as alternatives.

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

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

It provides explicit when-to-use (side-by-side comparison of 2-4 ISOs) and when-not-to-use (ranking all grids → get_grid_scoreboard; single-ISO deep brief → get_grid_intelligence). An example invocation further clarifies usage.

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 indicate read-only, idempotent, and non-destructive behavior. The description adds valuable context beyond that: it states the tool 'Runs the analyze_site read on each parcel' and reveals the paid/Pro access constraint ('free tier returns a locked preview'). No contradiction with annotations.

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

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

The description is long but well-organized and front-loaded with the usage trigger, example, parameters, return shape, access caveat, and exclusions. It repeats some return-shape details that an output schema might already provide, but each sentence carries useful decision-making information, so the length is justified.

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

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

For a complex comparison tool with 3 parameters, an output schema, and rich sibling context, this description is essentially complete. It covers when to use it, how to call it, what it returns, the paid-tier limitation, and exclusions. Nothing critical is left ambiguous.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes beyond by detailing the semicolon-separated 'lat,lon' format, the 2-4 maximum, a capacity range (50-500 MW), and a full example. The 'sites' array alternative isn't mentioned in text, but the schema covers it, so this still adds meaningful value.

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

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

The description opens with a specific verb and resource—'side-by-side winner picker' across power, gas, fiber, market & risk—making the tool's purpose unmistakable. It explicitly distinguishes itself from siblings by stating 'Do NOT use for a single site (use analyze_site) or to rank entire markets (use rank_markets)'.

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 a clear trigger condition ('when a user has narrowed to 2-4 candidate parcels'), provides a concrete example, and names alternatives with explicit exclusions. This is ideal guidance for selecting between compare_sites and its sibling 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?

The description discloses significant behavioral context beyond the annotations: progressive disclosure to keep default calls cheap, that comparables are returned as a count by default, that verdict text is always included, and that a paid key unlocks the full autopsy read. This goes well beyond the readOnly/idempotent hints and clearly sets expectations for cost and output detail.

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

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

The description is dense but well-structured: it starts with the core purpose, then explains the verdict overlay, then unfolds the progressive disclosure behavior, and ends with a practical example. Every sentence adds value; no filler or redundancy.

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

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

The tool has two well-documented parameters, readOnly annotations, and an output schema, so the description need not detail return fields. It covers what the tool returns, the paid-key caveat, the comparables escalation ladder, and even an example call. It is complete for the tool's complexity, with no critical gaps like missing prerequisites or side effects.

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

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

Schema coverage is 100%, so baseline is 3. The description adds extra meaning by explaining the cost/benefit of each comparables option ('cheapest', 'escalate only for deals you're drilling into') and gives a concrete usage example (limit=15). This goes beyond the schema's dry parameter descriptions, justifying a 4.

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

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

The description clearly states a specific verb+resource: it returns recent data-center M&A/capex deals with DCPI grid-reality verdicts overlaid. It distinguishes itself from siblings by emphasizing 'what is the real play?' and the unique 'per-deal autopsy read', which is not covered by other deal-related tools.

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

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

The description provides clear context on when to use the tool (tracked deal flow with DCPI verdicts) and gives explicit guidance on parameter escalation for comparables ('none' for cheap default, 'summary' for top-2 signals, 'full' for deep dives). However, it does not name alternative tools or explicitly state when not to use it over siblings, 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?

Beyond the readOnly/idempotent flags, the description discloses the return structure (front_door block, families with when-to-use notes, listed family names), the optional query filtering, and the navigation-layer limitation (not exhaustive, tools/list is canonical). This is rich behavioral context with no contradictions.

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

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

The description is information-dense and front-loaded with the 'Meta-tool' label. Though three sentences, it contains a lot of detail; the use of dashes and parentheticals helps structure it. Every sentence earns its place, but it could be slightly tighter without losing value.

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

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

Given the tool's complexity and the presence of an output schema, the description fully explains the tool's role, return entity, key components, relationship to tools/list, and usage flow. No important behavioral aspects are left uncovered.

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 sole parameter (query) has 100% schema coverage with examples in the schema description. The tool description only echoes 'optionally filtered by a query', adding no further semantic meaning. Hence baseline 3 is appropriate.

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

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

The description clearly states it is a meta-tool for navigating DC Hub's tool catalog by family, distinguishing it from sibling tools by positioning it as the first call when unsure. It identifies the exact resource and output entity (_entity=tool_families), and explicitly contrasts with the canonical tools/list.

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

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

Provides explicit when-to-use ('Call this FIRST when you are unsure which tool fits a task'), what to do after (call the chosen tool with its full schema from tools/list), and when not to use it (for binding capability maps, use tools/list). This clearly differentiates from alternatives.

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

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

Annotations already declare read-only and idempotent behavior. The description goes further by detailing deterministic no-LLM routing, wave-by-wave execution, hand-off resolution, fan-out caps, step/time budget limits, 'not_run' continuation behavior, and the tier-honest quota model. This far exceeds annotation coverage.

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

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

The description is one dense, run-on paragraph with no structural breaks. While every sentence carries meaningful content, the key 'front door' guidance is buried mid-text, and the content could be organized into clearer sections. It is appropriately sized for the complexity but not well front-loaded.

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

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

Given the complexity of the tool, the description covers all necessary context: when to use it, execution behavior, limits, alternatives, return envelope structure, and quota implications. The output schema exists, so return-value details are covered. No meaningful gaps remain.

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

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

Schema coverage is 100% and the input schema already provides rich descriptions for all five parameters, including examples and cohort validation rules. The description adds only marginal guidance like 'pass the user's question through UNCHANGED as intent' and hand-off resolution details, which does not substantially exceed the schema baseline.

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

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

The description clearly identifies execute_plan as a unified planner that runs a sequence of tools and returns all results in one envelope. It distinguishes itself from siblings by explicitly positioning itself as the 'front door' for multi-domain questions and contrasting with plan_query and single-tool direct calls.

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

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

Usage guidance is explicit: use execute_plan first for multi-domain or multi-step questions, use plan_query when you only want the plan to run yourself, and call single-tool tools directly. This gives clear when-to-use and when-not-to-use context with named alternatives.

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

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

Annotations already state readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful behavior info: it returns 'the full file contents as text' (not a file download), specifies the fields included (DCPI score, target MW, market, coordinates, notes), and describes the bulk-download nature. No contradiction with annotations.

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

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

The description is dense but well-structured: usage condition, example, parameter summary, return contents, and exclusions. Every sentence carries meaning, though it could be slightly shorter. The front-loading of 'Use when' makes it easy to scan.

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

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

Despite having an output schema, the description still explains return contents (CSV rows or GeoJSON FeatureCollection with specific fields), which helps the agent understand what the user will receive. It also notes this is the 'bulk-download path' and provides sibling tools for other actions. For a one-parameter export tool, this covers all essential context.

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

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

Schema coverage is 100%, so the baseline is 3. The description restates the format options ('csv' default, or 'geojson') and provides an example usage for geojson, but adds little beyond the schema's own parameter description. The schema already documents the format parameter with its default and purpose.

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

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

The description clearly states the tool's function: 'pull their saved DC Hub shortlist OUT of the platform' for offline analysis or transfer. It uses the specific verb 'export' with the resource 'saved DC Hub shortlist', and distinguishes itself from siblings by explicitly naming list_saved_sites and save_site as different actions.

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

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

It opens with 'Use when a user wants to pull their saved DC Hub shortlist OUT...' and provides a concrete example. It explicitly states when NOT to use it: 'Do NOT use to list sites in-chat (use list_saved_sites) or to save a new one (use save_site); this is the bulk-download path.' This gives clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare readOnly and idempotent hints. The description adds useful context: the return format, that the result is a citable public summary, and that full specs are not included. This goes beyond annotation basics, though it doesn't cover every possible edge case.

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

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

Two sentences deliver all necessary information: purpose, context, return shape, and alternative. No fluff, front-loaded, every word earns its place.

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

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

This is a simple single-parameter read tool. The description together with the schema and output schema fully cover what an agent needs: when to use it, what it returns, and what it doesn't. No critical gaps.

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

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

The schema already fully documents the 'id' parameter with a description and example. The tool description reinforces the origin of the id (from search) but adds no significant new meaning beyond the schema, so a baseline 3 is appropriate.

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

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

The description clearly states the tool fetches a DC Hub record for an id from the search tool, with a specific verb and resource. It distinguishes itself from sibling get_facility by noting it returns a citable public summary rather than full structured specs.

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

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

The description explicitly says to use this tool with an id returned by the `search` tool, and names the alternative (get_facility or opening the URL) for full structured specs. This provides clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior; description adds valuable context about return shape (similarity_score, match_reasons, key_differences) and the discovery-oriented nature of the tool. No contradiction with annotations.

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

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

Well-structured and front-loaded with use case, example, and exclusions. Slightly overlong due to the inaccurate parameter summary, but generally every sentence serves a purpose.

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

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

Covers purpose, usage, exclusions, and output essence effectively, and output schema supplies return details. However, the incorrect parameter information creates a meaningful gap that prevents full completeness.

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

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

Schema descriptions cover all 5 parameters well, but the description adds misleading info: it references 'capacity_mw' and 'name' which do not exist in the schema, omits match_on and exclude_operator, and incorrectly says facility_id is required when schema lists zero required params. This harms rather than helps parameter understanding.

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

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

Description clearly states the tool finds similar nearby facility alternatives from a single seed facility, with a concrete example. It explicitly distinguishes itself from sibling tools score_facility/analyze_site and compare_sites by naming them as alternatives.

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

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

Provides an explicit 'Use when' condition, a user-friendly example, and clear when-not-to-use instructions with named alternative tools. This fully informs the agent about appropriate invocation contexts.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower. The description adds useful context beyond annotations: the PDF link is 'ready-to-open... no login needed, valid ~7 days' and instructs to 'hand it to your human.' This clarifies output delivery and access behavior.

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

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

The description is long but information-dense and front-loaded with the core use case. It includes an example, param summary, return format, link expiration, and sibling comparison. Every sentence serves a purpose; the length is justified given the tool's complexity.

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

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

Given the output schema exists and annotations cover safety, the description covers all necessary operational context: when to use, example invocation, param defaults, return object shape, link behavior, and alternatives. It is complete for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, so baseline 3 applies. The description repeats schema info but adds a worked example ('generate_site_analysis lat=37.694 lon=-88.65 capacity_mw=150 prepared_for="TON Infrastructure" prepared_by="Martone Advisors"') and clarifies defaults (e.g., prepared_by defaults to DC Hub). It doesn't add meaning beyond schema, but doesn't need to.

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

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

The description states a specific verb and resource: 'Generate Site Analysis PDF' for a single lat/lon, positioning it as the 'polished client deliverable, not just a score.' It explicitly distinguishes from the sibling `analyze_site` by noting that for 'just the numeric suitability score (no PDF), use analyze_site instead.'

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?

Description opens with 'Use when a user wants a SHAREABLE, branded multi-page Site Analysis PDF...' and provides a concrete example with params. It clearly delineates when to use this tool vs `analyze_site`, offering an explicit alternative.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds valuable context that this is a curated ecosystem/capability index, not live per-caller call/citation telemetry, which goes beyond the annotations.

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

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

The description is well-structured, front-loading the core definition, then usage, then explicit exclusions. The 'Try: get_agent_registry' is slightly redundant but does not significantly detract from conciseness.

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

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

For a zero-parameter tool with an output schema, the description is thorough: it covers the ecosystem, recognized clients, recommended tools, authentication tiers, and explicitly excludes telemetry. The alternative tool reference completes the context.

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

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

The input schema has zero parameters, so the baseline score is 4. The description correctly avoids mentioning parameters since none exist, and the schema coverage is 100% by definition.

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

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

The description clearly defines the tool as a curated roster of AI platforms and agent frameworks with recommended tools and authentication tiers. It explicitly states what it is not (live telemetry), distinguishing it from potential sibling tools.

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

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

It provides explicit usage guidance: 'Use it to see which platforms DC Hub supports and how to connect them' and 'Do NOT use for platform uptime / backup health (use get_backup_status)', naming the alternative tool. This fully covers when to use versus alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context by enumerating the exact outputs (backup age, integrity check, green/yellow/red data freshness, heartbeat score), which goes beyond the annotations. No contradiction with annotations; the description complements them well.

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 two dense, well-structured sentences. The first lists all key metrics; the second gives usage context, an explicit 'Try:' pointer, and a clear exclusion with an alternative. Every sentence earns its place, and the text is front-loaded with the most important information. No filler or redundancy.

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 that the tool has no parameters and an output schema exists, the description adequately covers what it returns (all listed health indicators), when to use it (production trust signals), and when not to use it (specific dataset freshness). It also clarifies the platform-level scope, making the tool's role fully understandable without needing to inspect the output schema. Complete for its complexity.

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

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

The tool has zero parameters, so the description carries no parameter burden. Per the rubric, 0 params implies a baseline of 4. The description instead focuses on the tool's output scope, which is the appropriate semantic content for a parameterless health-check tool. Nothing more is needed.

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

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

The description opens with 'DC Hub platform health:' followed by a specific list of metrics: database backup status, data freshness across 49 sources, agentic heartbeat score, MCP call volume, and DCPI recompute cadence. This goes far beyond a vague verb+resource, and it explicitly distinguishes itself from content-level tools by stating 'this is platform/infra health, not content.' Clear, specific, and differentiated from sibling tools.

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

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

The description says 'Useful for trust/uptime signals before relying on the platform in production' and explicitly advises 'Do NOT use for the freshness of a specific dataset (use get_changes); this is platform/infra health, not content.' This provides both a when-to-use and a when-not-to-use, naming the alternative tool. Excellent 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 read-only, idempotent, non-destructive. The description adds valuable behavioral detail: returns DCPI movers, facilities, deals, news, plus a conditional 'portfolio' block for saved sites, and advises caching generated_at. No contradiction; the description complements annotations richly.

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

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

The description is dense but every sentence carries useful information: purpose, return contents, conditional portfolio, parameter usage, caching, and an example. It is well-structured and front-loaded with the core concept, 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?

Given the tool's moderate complexity, 2 optional parameters, and an output schema, the description is fully complete. It covers what to expect in the response, how to use the since parameter, and the caching workflow, leaving no major gaps for an agent to invoke correctly.

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

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

Schema coverage is 100% for both parameters, so baseline is 3. The description adds meaning beyond schema by explaining the 'since' shorthand ('24h'/'7d'), default behavior, and caching guidance tying generated_at to the next call. This extra guidance elevates the score above baseline.

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

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

The description clearly states a specific verb+resource: 'Incremental sync — what changed in DC Hub since a timestamp.' It distinguishes itself from siblings by emphasizing 'delta instead of re-fetching everything,' making its unique purpose unambiguous.

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

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

Provides clear context: use for incremental pulls rather than full re-fetch. Gives a concrete example ('Try: get_changes since=7d') and notes the keyed-caller portfolio use case. Does not explicitly name sibling tools as alternatives, but the guidance is sufficient.

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 meaningful context: data provenance (USGS ASCE 7 + NOAA via ACIS), a strict 'missing data is declared unavailable, never estimated' policy, and edge-case behavior (non-US seismic unavailable; radius overshoot returns unavailable_exceeds_radius). These go well beyond the structured hints.

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

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

The description is dense but well-structured: use case, data sources, example, return structure, parameter behavior, limitations, and alternatives. Every sentence earns its place and the text is front-loaded with the most important guidance. No filler.

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

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

Given the tool's complexity (two data domains, federal sourcing, radius logic, US/non-US behavior), the description covers all relevant aspects. It even previews the return structure despite an output schema existing, and clearly differentiates from two related sibling tools. It is fully complete for agent decision-making.

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 a concrete example (lat=33.45 lon=-112.07), explains the radius parameter's snapping behavior and default, and connects lat/lon to the tool's purpose. This is useful but not essential given the schema's thorough descriptions.

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

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

The description opens with a specific verb and resource: 'seismic + climate intel for a lat/lon', and ties it to concrete uses (structural bracing cost, cooling design). It also distinguishes from sibling tools by explicitly naming get_disaster_risk and get_composite_site_score as alternatives for different intents.

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

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

Explicit 'Use when' guidance at the top, and clear exclusions at the end: 'For natural-hazard ratings use get_disaster_risk; for one blended verdict use get_composite_site_score.' It also states limitations (US-only seismic, radius boundary) that help the agent know when not to use this tool.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses significant behavioral details: it scores only over VALIDATED factors, never imputes missing ones, water is 'unavailable' only outside basin coverage and never faked, and market/DCPI is v1-unavailable. It also explains which factors are live (power/grid, fiber, FEMA NRI, WRI Aqueduct). This goes well beyond the safety profile provided by annotations.

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

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

Despite being somewhat long, the description is front-loaded with the core use case and every sentence adds value: it explains the key differentiator, lists live factors, gives an example, summarizes the return structure, and names alternatives. There is no wasted phrasing; the density is high but justifiable given the tool's complexity.

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

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

The description captures the tool's complexity well: it addresses factor coverage semantics, the no-imputation rule, the confidence dimension, and alternative tools. Given that an output schema exists and return structure is summarized, the only minor gap is that it doesn't explicitly state that lat/lon are required (schema shows 0 required), but the example and parameter descriptions imply this. Overall, it is sufficiently complete for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100% with detailed descriptions for each parameter, including aliases. The description adds a concrete example (lat=33.45 lon=-112.07 state=AZ) but does not materially extend the parameter semantics already present in the schema. Per the rubric, a baseline of 3 is appropriate when the schema carries the parameter documentation load.

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

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

The description clearly states the tool produces 'ONE honest 0-100 site suitability/risk verdict' with an explicit per-factor coverage map. It distinguishes itself from analyze_site, compare_sites, and rank_markets by emphasizing that it scores only over validated factors and never imputes missing ones.

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

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

The description begins with 'Use when a user wants ONE honest 0-100 site suitability/risk verdict', and explicitly contrasts with 'Unlike analyze_site (full raw data dump)'. It closes with direct alternative references: 'Use analyze_site for full data, compare_sites for 2-4 sites, rank_markets for whole-market ranking.' This gives both positive and negative usage criteria.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses that it aggregates 5+ separate tools into one call, returns an LLM-quotable summary_text with CC-BY-4.0 license, includes citation_url, and details the output structure. This is consistent with the annotations and adds significant behavioral context.

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

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

The description is long but every sentence serves a purpose: usage context, example, parameter semantics, return format, and exclusions. It is front-loaded with the most important use case. It is slightly dense but not wasteful.

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

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

The description is thorough: it covers when to use, when not to use, alternatives, parameter details, example invocation, and the full return structure. With a clear output schema and rich annotations, no gaps remain.

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

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

The input schema already provides a comprehensive description of the 'context' parameter (free-text describing MW, geography, workload, deadline, constraints). The tool description repeats this and adds an example, but does not introduce new semantic information 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?

The description clearly states that the tool returns a ready-to-quote answer for open-ended siting questions, with a specific verb and resource. It distinguishes from siblings by explicitly naming analyze_site and rank_markets as alternatives for different use cases.

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

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

The description provides explicit when-to-use guidance ('Use when a user asks an open-ended siting question...') and when-not-to-use instruction with named alternatives ('Do NOT use for a single specific lat/lon (use analyze_site) or to rank by ONE criterion only (use rank_markets).')

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

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds significant behavioral context: it's a live query (never estimated), grounded in the authoritative FEMA NRI dataset, county-level resolution, and how out-of-coverage points behave. It also discloses the return payload structure.

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 yet every sentence earns its place: use case, data source, example, output structure, resolution, and alternatives. It is well-structured with no wasted words.

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

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

Given the tool's complexity (5 params with aliases, a rich output schema, and a coverage edge case), the description is complete. It explains the return structure, county-level resolution, coverage=unavailable behavior, and provides alternatives, so an agent has full context to invoke it correctly.

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

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

All 5 parameters already have detailed descriptions in the schema, including types, aliases, and example values. The tool description adds an example invocation but no additional semantic meaning beyond the schema, so a baseline of 3 is appropriate.

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

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

The description clearly states the tool's function: 'get the natural-hazard / disaster risk for a lat/lon' and lists specific hazards (flood, wildfire, hurricane, etc.). It differentiates from siblings by naming alternatives like get_water_risk and get_composite_site_score, and identifies the authoritative FEMA NRI dataset.

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

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

The description opens with 'Use when a user wants...' and closes with explicit alternative guidance: 'For chronic water stress use get_water_risk; for one blended site verdict use get_composite_site_score.' It also notes the US coverage limitation and that outside NRI coverage returns coverage=unavailable, giving clear boundary conditions.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is known. The description adds valuable context: data source (DC Hub), CC-BY-4.0 attribution requirement, real-time grid-status flag, and that results include an as_of timestamp. This goes beyond the annotations without contradicting them.

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

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

The description is longer than average but every sentence carries distinct information: trigger, scope, data items, example, parameter, return shape, attribution, and exclusions. It is front-loaded with the use case and ends with clear negative guidance. Slightly dense but not wasteful.

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, sibling density, and rich output schema, the description covers all key aspects: when to use, what data is returned, required parameters, attribution constraints, and how it differs from close siblings. The output schema already exists, so not detailing return fields would be acceptable, but they are included for extra clarity.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds that 'iso' is required (suggesting the schema's optionality is not authoritative) and lists all 7 valid ISOs. However, it does not mention 'state' or 'data_type', which are only covered by the schema. Overall it adds moderate value beyond the schema.

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

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

The description opens with a specific trigger ('what does power/gas COST') and explicitly states the resource: 'live energy PRICING for the 7 US ISOs'. It enumerates exactly what is returned (retail, wholesale/LMP, Henry Hub gas, grid_status) and distinguishes itself from siblings by listing exclusions. This is a textbook clear purpose.

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 an explicit 'Use when' condition with a concrete user phrasing example, and a detailed 'Do NOT use for' list that names alternative tools (get_grid_data, get_grid_intelligence, get_gas_economics). This gives the agent clear decision boundaries.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is established. The description adds behavioral context about the scope (exactly one facility), the return payload contents, and the constraint against using it for listing many facilities. It doesn't elaborate on optional flags but these are captured in schema.

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

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

The description is dense but every sentence earns its place: a front-loaded summary of the returned metadata, a pair of practical examples, and an explicit usage boundary. No filler or tautology.

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

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

With an output schema present and 100% parameter schema coverage, the description adds the essential missing context: singular return behavior, the specific data categories, and the distinction from sibling search_facilities. This is sufficient for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100% with detailed per-parameter descriptions, so baseline is 3. The description adds value with concrete examples (id=equinix-dc1-ashburn, slug=digital-realty-iad8) that clarify the alias relationships and expected value formats. It doesn't mention include_power/include_nearby, but the schema already documents them clearly.

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: 'Full metadata for one facility' and enumerates the exact fields returned (name, operator, address, lat/lon, power capacity, cooling type, fiber providers, commissioning year, status, DCPI verdict, nearby peers). It clearly distinguishes from search_facilities by warning 'do NOT use to search or list many facilities'.

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

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

Provides explicit when-to-use guidance with a direct exclusion: 'Returns ONE facility in full; do NOT use to search or list many facilities (use search_facilities).' Includes concrete invocation examples using id and slug, making the usage context immediately actionable.

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

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

Beyond the readOnly and idempotent annotations, the description discloses important behavioral integrity: it only computes deltas for DCPI market-health, explicitly declares site-hazard dimensions as static, and returns coverage:unavailable when no snapshot history exists. It also states it 'never fabricates' week-over-week deltas, which is a meaningful behavioral guarantee. This goes well beyond the annotations.

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

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

The description is longer than average but every sentence serves a purpose: use case, return value, integrity constraints, parameters, and alternatives. It is front-loaded with the primary use case and ends with clear next-step guidance. Minor verbosity exists in the all-caps integrity section, but the structure is logical and scannable.

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

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

Given the tool's temporal complexity, the description is remarkably complete. It explains what changes are measurable, what is declared static, how coverage failures are surfaced, the exact output shape, and which sibling tools handle point-in-time queries. The presence of an output schema and clear parameter descriptions reduces the burden, but the description still adds all necessary behavioral context.

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

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

The input schema already describes each parameter with examples, and schema coverage is 100%, so the baseline is 3. The description adds the important logical relationship that facility_id and market are alternatives ('OR'), provides representative values ('7d'/'30d') and clarifies the default for since. This extra relational context justifies a score of 4.

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

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

The description clearly specifies the tool's purpose: returning changes in a facility's or market's risk profile over a recent window, specifically the DCPI market-health delta with direction. It uses specific verbs ('has CHANGED', 'Returns') and distinguishes from sibling point-in-time risk tools by emphasizing the temporal aspect. The examples of user questions ('has this site gotten riskier lately?') make the purpose tangible.

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

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

The description explicitly states when to use this tool ('Use when a user asks what has CHANGED...') and excludes alternative tools for point-in-time risk ('For the current point-in-time risk use get_composite_site_score / get_disaster_risk / get_climate_intel'). It also clarifies that only DCPI market-health has a reliable temporal series, so the tool should not be used for static dimensions. This is strong, explicit usage guidance.

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

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

Annotations already declare readOnlyHint true, destructiveHint false, and idempotentHint true, so safety is covered. The description adds meaningful behavioral detail: market filtering is described as 'either endpoint within ~1.2°', the output is a GeoJSON FeatureCollection ready for Leaflet/Mapbox, and 'omit carrier for all carriers' clarifies filtering semantics. This goes well beyond the annotation baseline.

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

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

The description is dense but well-organized: usage scenarios, example, parameter list, output format, and exclusions. Every section serves a purpose. It is longer than the TDQS 4.3 example, but the additional length is justified by the parameter details and output schema explanation. A minor deduction for the slightly bulky inline enum lists and example.

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 (4 parameters, output schema, many siblings), the description covers recommended usage, example call, parameter semantics, return format, and exclusions. With an output schema present, return-value explanation is a bonus. It fully equips an agent to select and invoke the tool correctly, even among overlapping fiber tools.

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% (baseline 3), but the description enriches the carrier and route_type parameters with explicit enum values not present in the schema, and elaborates the market parameter with a dual example and distance constraint. It does not mention include_sources, but that parameter is already well described in the schema. The additional semantics push this above baseline, but not to a perfect 5.

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

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

The description opens with specific use cases ('scoring a candidate site for fiber depth, mapping long-haul routes between metros, or assessing dark-fiber availability') and clearly names the resource (fiber routes). It explicitly distinguishes the tool from siblings by directing users to get_facility and analyze_site for related but different tasks, so it stands apart from other fiber-related tools.

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

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

It states exactly when to use the tool ('Use when...'), gives a concrete example with parameter values, and provides a 'Do NOT use' clause with explicit alternatives: 'use get_facility' and 'use analyze_site'. This is the gold standard for usage guidance.

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

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

Annotations already indicate readOnly, idempotent, non-destructive, but the description adds substantial behavioral context beyond annotations: it explains the computation (near-net distance, number of distinct fiber carriers, single-carrier risk), the output fields (score, near_net_bucket, top_carriers, etc.), and the semantics of the verdict. No contradiction with annotations.

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

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

The description is long but each section earns its place: usage context, example, parameter summary, return fields, exclusions. It is structured logically and front-loaded with the purpose. Slight redundancy with schema parameter descriptions, but the example and exclusions justify the length.

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

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

Given the tool complexity (output schema, multiple carriers, risk assessment), the description is complete: it explains the return value shape, the decision context, and the exclusions. The presence of an output schema means return values need no further elaboration, and the description still covers all necessary selection and usage nuances.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by clarifying the intent of lat/lon as targeting a single parcel, and explicitly states required parameters even though the schema does not mark them required. The example usage further clarifies parameter application.

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 ('fiber-readiness / connectivity verdict for ONE parcel or site') and clearly distinguishes from siblings by explicitly naming what it is not for (carrier routes, multi-factor site score). The example usage reinforces the precise scope.

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

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

Provides an explicit 'when to use' statement and explicit exclusions: 'Do NOT use to map carrier ROUTES between metros (use get_fiber_intel) or for a full multi-factor site suitability score (use analyze_site).' This gives clear guidance versus alternatives.

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

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

Annotations already provide readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds rich context: the data basis, output structure, target user (BTM developer comparing to PPA), and explicit exclusions. This goes well beyond what annotations convey.

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

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

The description is dense but every sentence serves a purpose: purpose, parameter usage, output structure, and sibling disambiguation. No redundancy or filler. It is appropriately structured for a complex tool.

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

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

Given the tool's complexity and the presence of both schema and output schema, the description is complete: it covers purpose, parameters, return values, use cases, and exclusions. It also leverages the annotation safety profile, making it self-sufficient.

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

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

Schema coverage is 100% for both parameters. The description adds example market slugs and explains the heat_rate parameter as producing a custom scenario, which supplements the schema. Baseline 3 is elevated slightly due to this added context, though not drastically.

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

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

The description clearly states the tool's purpose: 'Behind-the-meter / gas-fired power ECONOMICS for a US data-center market.' It lists specific outputs and differentiates from siblings by naming alternatives. This is a specific verb+resource with strong sibling differentiation.

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

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

Explicit usage guidance is provided: 'Pairs with get_gas_index' and 'Do NOT use for the electricity grid fuel mix (use get_grid_data) or the per-state gas suitability score (use get_gas_index).' This clearly states when to use and when not to use, with alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, but the description goes far beyond that by detailing the output structure (composite dcgi, gas_access_score, gas_cost_score, pipelines, operators, verdict), the verdict values ('GAS-ADVANTAGED / ADEQUATE / GAS-CONSTRAINED'), and behavioral differences based on omitting `state` (national ranking). It also discloses the attribution requirement (CC-BY-4.0), adding valuable context beyond 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?

The description is longer than strictly necessary but every sentence earns its place: it front-loads the core purpose, explains the two usage modes, gives an example, and lists exclusions. The structure is logical (definition → usage → output → alternatives), though the 'Try:' line could be seen as slightly repetitive. Still, it's efficient and well-organized for a tool with two modes.

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

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

Given that an output schema exists (so return values are presumably documented there), the description adequately covers all necessary context: what the tool returns, how to invoke it, when to use it, how it relates to siblings, and attribution. No critical gaps remain for an agent to safely and correctly invoke this tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaningful semantics by explaining the interaction: 'Pass state... for one state's full breakdown' and 'Omit state for the national ranking (all states sorted by DCGI; optional limit)'. This clarifies that `limit` applies to the national ranking mode, which the schema does not explicitly state, earning a 4.

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

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

The description clearly states the tool's function: 'Data Center Gas Index (DCGI) — DC Hub's 0-100 per-US-state natural-gas suitability score for data centers'. It immediately distinguishes from siblings by calling it 'the gas analog to DCPI' and explicitly contrasts with grid and live-price tools. The verb 'get' plus resource 'gas index' is specific and unambiguous.

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

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

Usage guidance is explicit and thorough: it tells the agent when to use the tool ('The authoritative answer to which states are best for gas-fired / behind-the-meter data-center power?'), when not to ('Do NOT use for the electricity grid... or live gas pricing'), and names alternatives ('use get_grid_data / get_grid_intelligence' or 'get_energy_prices'). It also provides a concrete example ('Try: get_gas_index state=TX').

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

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

The description discloses data limitations (delivered_price null on sparse tariff tables), data provenance labels (data_basis, synthetic-labeled), and explicit omissions (gas storage/LNG/firm capacity). This goes far beyond the readOnlyHint and idempotentHint annotations.

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

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

The description is long but well-structured: usage first, then analogy, params, return schema, and exclusions. Every sentence is informative, though it could be slightly more concise.

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

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

Given the complexity (many output fields, exclusions, alternatives), the description is complete. It covers the full return object, data honesty policy, and tool boundaries, making it sufficient even with the output schema present.

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

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

Schema coverage is 100% with both parameters described. The description adds value by clarifying the primary param 'region' with example values and by implying that 'state' is an alias. This is helpful but not exhaustive.

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

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

The description states a specific purpose: answering questions about gas-fired power economics for data centers in US states. It clearly distinguishes itself as the GAS analogue of get_grid_intelligence and explicitly names sibling tools get_grid_intelligence and get_gas_index for different use cases.

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

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

It gives explicit when-to-use context with real example questions and direct do-not-use instructions with alternative tool names: 'Do NOT use for electricity grid headroom (use get_grid_intelligence) or the DCGI score alone (use get_gas_index).' This provides strong 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 readOnly/idempotent/non-destructive behavior. The description adds meaningful context: data source, geolocated unit count, attribute list (fuel, capacity, status, start year, operator/owner, lat/lng), and that pipeline=true isolates the forward set. It does not contradict annotations, though it leaves minor gaps like default limit and sorting unspecified.

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

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

Though moderately long, every sentence earns its place: front-loaded 'Use when', data source stats, filter explanations, return summary, example, and exclusions. It is dense but well-organized with no redundant content.

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 7-param read-only tool with output schema and helpful annotations, the description covers scope, data source, filtering behaviors, return summary, and alternatives. Minor unspecified details like default limits are not critical given the existing output schema and 100% parameter documentation.

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 semantic value by clarifying the pipeline boolean as 'JUST the forward set', explaining fuel comma-union behavior, and providing a concrete example (country=India pipeline=true). This reduces ambiguity beyond the schema alone.

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

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

The description explicitly states the tool covers global power plants/units in non-US countries across all fuels and both operating and pipeline phases. It names the Global Energy Monitor Global Integrated Power Tracker and differentiates from US-specific sibling tools by geography and scope.

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

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

Provides explicit 'Use when' conditions for worldwide/non-US queries and explicit 'Do NOT use for' exclusions with alternative tool names (get_grid_intelligence, get_grid_scoreboard, get_power_pipeline). Includes a concrete example invocation, making selection and usage clear.

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

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

Annotations already convey read-only, idempotent, and non-destructive behavior. The description adds meaningful behavioral context: data is real-time raw telemetry from EIA hourly RTO, limited to one ISO at a time, and clarifies it is not for analysis purposes beyond the stated metrics. This goes beyond the schemas and annotations without contradiction.

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

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

Three sentences, each earning its place: the first states the core function and scope, the second gives a concrete parameter example, and the third lists exclusions with alternatives. No filler or redundant repetition of schema details.

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

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

For a read-only data retrieval tool with an output schema present, the description covers purpose, geographic scope, data content, parameter usage, and exclusions. It tells the agent exactly when to choose this tool over the many siblings in the list, making it fully actionable.

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

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

The schema already describes all three parameters (iso, metric, period) with 100% coverage, so a baseline of 3 applies. The description adds valuable examples (iso=PJM, metric=fuel_mix/demand/demand_curve, period=24h) and emphasizes the expected use of iso. Minor note: schema marks all parameters optional while description implies iso is required, but the description's instruction is clear.

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

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

The description clearly identifies the tool as retrieving real-time electricity grid data for 7 named US ISOs with specific content types (fuel mix, demand, 24h demand curve). It explicitly distinguishes itself from sibling tools by naming alternatives for other use cases, making its purpose unambiguous.

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

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

The description provides explicit when-to-use guidance with concrete examples (pass iso=PJM) and when-not-to-use guidance with named alternatives: get_grid_intelligence for power-availability/time-to-power/interconnection-queue, get_energy_prices for retail/gas pricing, and get_grid_scoreboard for non-US grids. This fully addresses selection among siblings.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral nuance beyond annotations: balancing authorities return live generation mix while ISO-level fields remain at the 7-ISO level, and the PJM-DOM special case. This is rich context without contradicting annotations.

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

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

The description is lengthy but every sentence adds value: usage trigger, example, parameter details, return fields, and exclusions. It is well-structured with clear separation of concerns, though it could be slightly tightened. A 4 is appropriate for its density of useful 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?

Given the tool's complexity (3 params, many sibling tools, output schema available), the description is exceptionally complete. It covers parameter semantics, return structure, special cases, and exclusions. The output schema covers return fields, so the description's listing of outputs is a bonus. It leaves no obvious gaps for an AI agent to select and invoke correctly.

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

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

Schema description coverage is 100%, so the schema fully documents the parameters. The description adds value by clarifying aliases (iso/region accepted), enumerating the 7 ISOs, providing concrete balancing-authority examples, and explaining the special PJM-DOM behavior. This goes beyond the schema's baseline.

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

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

The description states a specific verb+resource: 'get grid-headroom + interconnection-queue brief for one ISO.' It clearly distinguishes from siblings by naming compare_isos and get_grid_scoreboard as alternatives for different use cases. The example invocation further reinforces the tool's purpose.

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

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

The description explicitly says when to use the tool (when user asks about power capacity and time-to-power for a single ISO) and when NOT to use it, naming alternatives: 'Do NOT use to compare 2+ ISOs side-by-side (use compare_isos) or for the global greenest-first ranking (use get_grid_scoreboard).' This is exemplary usage guidance.

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

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

Annotations already declare readOnly and idempotent, but the description adds rich behavioral context: deriving renewable share as wind+solar+hydro, the Brazil thermal bundling caveat, 'partial_grids' with no full fuel split, and the live, ranked nature. It also cites sources and attribution requirements, far exceeding the minimal annotation coverage.

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

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

Though long, the description is information-dense with clear structure: coverage list, ranking methodology, special cases, sources, and alternatives. Every sentence adds value; no redundancy or filler.

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

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

Given the tool's global complexity, the description covers all necessary context: geographic scope, ranking criteria, caveats (Brazil/AU/SG), data sources, and use case. The presence of an output schema means return-value details are not required in the description.

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

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

The tool has zero parameters, so the baseline is 4. The description explains the output semantics (ranked grids, fuel mix, demand) and methodology, which is sufficient given no inputs.

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

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

The description clearly identifies the tool as a live global grid scoreboard, listing specific regions and aggregators. It distinguishes itself from siblings: 'vs compare_isos (pairwise) or get_grid_data (single ISO).' The verb+resource ('get grid scoreboard') is explicit and specific.

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

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

Explicitly states when to use: 'One call answers "which grid worldwide is greenest, or most gas-reliant, for siting a data center?"' and contrasts with compare_isos and get_grid_data. Also provides exclusions (Brazil's missing gas share, AU/SG unranked), giving clear boundaries.

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 critical behavioral details beyond annotations: capacity_type split, distinct_feeders vs geometry_rows_scanned reporting, sample_complete flag, explicit not-published answer outside coverage. All consistent with readOnlyHint and idempotentHint.

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?

Very informative but lengthy (~500 words). Well front-loaded with purpose and examples, but could be slightly more structured for quick scanning. Still earns a 4 for density of useful 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?

Comprehensive given complexity: covers parameter nuances, edge cases, warnings, and interpretation. Output schema exists, so return values need not be explained. Fully complete for agent usage.

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?

Adds significant meaning beyond 100% schema-covered parameters: explains calling modes, capacity_type semantics with critical warnings (load vs gen vs bus_headroom), and radius_km behavior when utility is used.

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

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

The description clearly states it returns utility-published feeder hosting capacity in MW, specifies three calling modes, and distinguishes from sibling tools like get_grid_intelligence and get_interconnection_queue by explicitly stating what not to use.

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

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

Provides explicit when-to-use (distribution feeder capacity) and when-not-to-use (transmission, ISO queue, retiring plant), example calls, and coverage limitations (Northeast/Mid-Atlantic/Midwest). Also explains what happens outside coverage.

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. The description adds valuable context: it returns raw nearby assets, provides distance and capacity, and joins to HIFLD/EIA data. It does not contradict annotations, and while it could mention rate limits or pagination, the added behavioral detail is meaningful.

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 two sentences: the first packs essential asset details and return metrics; the second gives an example and an explicit alternative. Every sentence earns its place with no fluff, and it is front-loaded with the core purpose.

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

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

Given the tool has an output schema and robust annotations, the description covers the key contextual needs: example invocation, data sources, raw vs scored distinction, and layer enumeration. It is complete for an agent to select and invoke the tool correctly without additional inference.

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

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

Schema description coverage is 100%, so all 9 parameters are already documented with clear descriptions. The description adds a concrete example and clarifies the semantics of radius_km and the layer types, but these mostly complement rather than extend the parameter documentation. Baseline 3 applies because the schema does the heavy lifting.

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

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

The description states a specific action—'Nearby infrastructure for a location'—and enumerates exact asset types (substations, transmission lines, pipelines, power plants) with their attributes. It clearly distinguishes from the sibling tool analyze_site, noting this returns raw assets rather than a scored verdict.

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

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

Explicitly gives a concrete usage example with parameters (lat=33.45 lon=-112.07 radius_km=25) and provides a direct exclusion: 'do NOT use for a single scored site-suitability verdict (use analyze_site)'. This tells the agent when to use and when not to use the tool.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is clear. The description adds behavioral context beyond annotations by specifying the return contents (index value, percentile rank, trends, component scores) and by noting the aggregation inputs. This meaningfully enhances what annotations provide.

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

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

The description is dense and front-loaded, with the core definition in the first sentence. The example and exclusionary guidance are useful, but the phrase 'Returns ONE composite health number' is somewhat redundant with 'Returns the index value' and the example's parameter is problematic.

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

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

The description covers purpose, return values, and alternatives, and an output schema exists to document return shape. However, the empty input schema conflicts with the example parameter, leaving ambiguity about how to specify a market if no parameters are formally accepted. This gap affects completeness and correctness.

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

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

The input schema has zero parameters, so the baseline is 4, but the description misleadingly suggests a 'market=northern-virginia' parameter that does not exist in the schema. This is actively harmful because an agent may attempt to invoke the tool with an unsupported parameter. No real parameter semantics are clarified beyond the empty schema.

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

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

The description uses a specific verb ('get') and resource ('intelligence index'), and clearly defines what it returns: a composite market health score from 0-100. It also explicitly distinguishes itself from siblings by stating not to use it for full market metrics (get_market_intel) or ranking multiple markets (rank_markets).

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

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

Provides explicit when-to-use context: for a single composite health score of a market. It also names alternatives with a clear 'do NOT use' directive: use get_market_intel for the full metric set and rank_markets for ranking multiple markets. This is strong, actionable guidance.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower. The description adds substantial behavioral context: ERCOT-specific large-load return behavior, null data_center_gw for other ISOs, provenance in top_subregions, and source attribution. It enriches the annotation-only safety profile with concrete return logic.

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 relatively long but every sentence contributes unique information: core purpose, ERCOT exception, sources, drill-down behavior, and use-case boundaries. It is dense but not wasteful; the length is justified by the tool's special behavior around ERCOT.

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 simple parameter set and presence of an output schema, the description is thorough. It covers return fields (queued_load_total_gw, queued_load_data_center_gw, top_subregions), null semantics, sources, and explicitly distinguishes this tool from related ones. No gaps are apparent.

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 describes the iso parameter with allowed values and omit behavior. The description adds minimal new meaning ('Pass iso=ERCOT (or any of 7) to drill down') which is somewhat redundant. It does not significantly enhance the schema's 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?

The description clearly states the tool's function: 'ISO interconnection queue snapshot' with specific detail on generation capacity per ISO. It differentiates from siblings by explicitly naming alternative tools in the 'Do NOT use' section, making the tool's unique scope evident.

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

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

Usage guidance is explicit: 'Use for queue-depth site-selection and AI/data-center-load saturation intel' and 'Do NOT use for a single-site time-to-power read (use get_grid_intelligence) or forward-looking emergence (use grid_transition_radar)'. This provides clear when-to-use and when-not-to-use with alternatives.

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

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

The description discloses token budgeting, priority-order greedy filling, per-section token counts, as_of timestamps, and citation URLs. It also explains the 'omitted' field behavior when the budget is exceeded, adding substantial context beyond the readOnlyHint and idempotentHint annotations.

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

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

The description is dense but well-structured: purpose, use case, example, return schema, exclusions, and citation. It is front-loaded with the main intent, but slightly redundant in repeating parameter details already covered by the 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?

For a complex tool, the description is complete: it explains the full return structure, mentions the output schema fields, clarifies exclusions, provides a real example, and even includes a citation source. Nothing essential is left unclear.

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 descriptions cover 100% of parameters, but the description reinforces them by explaining the iso enum values and how max_tokens affects section priority. The usage example ('iso=ERCOT max_tokens=4000') adds practical meaning beyond the schema.

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

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

The description clearly states the tool provides a 'WHOLE-grid briefing' context pack for US ISOs/RTOs, listing specific content sections. It explicitly distinguishes itself from sibling tools by naming alternatives for other use cases (get_grid_data, get_grid_intelligence, compare_isos, get_grid_scoreboard).

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

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

The description opens with 'Use when an agent needs a WHOLE-grid briefing' and provides a concrete example. It explicitly states 'Do NOT use for' raw telemetry, per-ISO decision briefs, multi-ISO comparisons, or non-US grids, naming the correct alternative tool for each.

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

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

Beyond the readOnlyHint/idempotentHint annotations, the description discloses the greedy token-budget filling behavior, the priority order of sections, per-section token counts, timestamps, citable URLs, and the 'omitted' field. It also states the return structure, adding meaningful behavioral context.

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

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

The description is dense but every sentence carries information: use case, contents, example, params, return shape, exclusions, and citation. It is front-loaded with the trigger condition and uses a clear logical flow, making it easy for an agent to parse efficiently.

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

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

Given the tool's complexity (a multi-section briefing pack with token budget), the description fully equips the agent: it lists all content sections, explains the budget behavior, shows the return schema textually, provides exclusions, and even includes the citation requirement. The presence of an output schema means return values need no further explanation.

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?

While the schema already documents both parameters at 100% coverage, the description adds valuable semantics: market slugs come from rank_markets, max_tokens has a range and default, and sections are filled in priority order until budget is spent. This goes beyond the schema's basic parameter descriptions.

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

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

The description opens with a concrete use case ('Use when an agent needs a WHOLE-market briefing...') and clearly defines the tool's output as a token-budgeted context pack. It explicitly distinguishes itself from siblings by naming alternatives for single metrics, raw structured data, and cross-market ranking.

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

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

It provides explicit when-to-use and when-not-to-use guidance, naming exact alternative tools (get_market_dcpi_rank, get_market_intel, rank_markets) and includes a concrete example call. This leaves no ambiguity about when the tool is appropriate.

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