DC Hub — Data Center & Power Intelligence

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 clear. The description adds valuable context beyond that, including the refresh schedule ('Refreshed Fridays 14:00 UTC'), the composite score composition, and a data caveat ('where facility data carries them'). No contradictions exist.

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

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

The description is compact and front-loaded, with four sentences each serving a distinct purpose: core function, return fields, refresh cadence, and usage guidance. There is no filler or repetition.

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

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

The description covers the tool's purpose, return fields, composite score formula, refresh schedule, and explicit use cases/exclusions. Since an output schema exists, the description does not need to detail return formatting, and it provides ample business context for tool selection and invocation.

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

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

The input schema provides complete descriptions for both parameters (limit and horizon) with defaults and ranges, so schema_description_coverage is 100%. The description reinforces the horizon semantics (30/60/90 days) but does not add new parameter-level details beyond the schema.

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

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

The description states a specific action and scope: 'ranks data center markets by where 100MW of AI training capacity can land in the next 30/60/90 days.' It clearly distinguishes from siblings by explicitly 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: 'Use for AI capex planning, GPU cluster siting, hyperscaler deal forecasting.' It also provides explicit exclusions and alternatives: 'Do NOT use for a general best-markets ranking (use rank_markets) or forward grid-emergence (use grid_transition_radar).'

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/destructive hints, but the description adds substantial behavioral detail: honest 404 with coverage list, representative_point being the largest-member centroid to avoid off-parcel points, and the hosted_parcel field conditionality. This far exceeds what annotations provide and contains 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 long but every sentence carries distinct value: mode selection, coverage caveat, representative_point behavior, return fields, and sibling differentiation. It is front-loaded with the core purpose and uses parentheticals effectively, though a slight trim would improve scannability.

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

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

Given the tool's complexity (7 params, two intake modes, external hosted layer), the description is remarkably complete. It covers edge cases (coverage 404), output semantics (contiguous flag, largest-area centroid), and downstream handoff to other tools. The presence of an output schema doesn't create gaps; the description supplements it well.

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 descriptions for every parameter, so baseline is 3. The description adds practical meaning by grouping geometry vs lat/lon modes, noting aliases (lng/latitude/longitude), and clarifying capacity_mw is passed through to the handoff. This elevates it 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 opens with a specific verb+resource ('Structured read of a parcel BOUNDARY') and clearly distinguishes from siblings by naming analyze_site and get_refined_queue. It explicitly defines two intake modes (own geometry or lat/lon) and the output tuple, leaving no ambiguity about what the tool does.

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

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

Explicit when-to-use and alternative guidance: 'Use when you HAVE a boundary or a point on a specific parcel...' then contrasts with analyze_site for general site scoring and get_refined_queue for queue rows. This is exactly the kind of decision-support AI agents need.

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 hints, the description discloses free vs. Pro return differences, candidate_id behavior (frozen mint, ignores lat/lon, expired ids fail closed), and aliases for lat/lon. It honestly notes what the free tier returns versus the full paid output.

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

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

The description is dense but well-structured: use case first, then example invocation, parameters, returns, free/pro breakdown, and alternatives. Every sentence carries information, and the long length is justified by the tool's complexity and the number of parameters and outputs.

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?

It covers the purpose, usage context, parameter semantics, return structure, free vs. Pro behavior, error case (candidate_expired), and relationships to sibling tools. This is fully sufficient for an agent to select and invoke the tool correctly, even before seeing the output schema.

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

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

Schema description coverage is 100%, and the description's parameter section largely mirrors the schema (e.g., 'capacity_mw' range, 'state' for tax lookup, 'include_*' defaults). It adds a concrete example call, but no substantial new meaning beyond the already detailed schema.

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

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

The description opens with a specific verb and resource: 'full multi-factor data-center suitability read' for a single site. It names the factors (power, gas, fiber, market & risk) and clearly distinguishes itself from siblings like compare_sites and find_alternatives.

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

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

It explicitly states when to use: 'Use when a user has ONE specific lat/lon' and provides exclusions: 'Do NOT use to compare 2+ sites (use compare_sites) or to find sites that match a target (use find_alternatives).' It also points to specialized tools for water, disaster, climate, and tax reads.

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 context beyond the annotations: it discloses that binding does NOT make identity durable, that the durability benefit is unproven for small cohorts, that fake emails are rejected server-side, that the email is used only for recovery and receipts with no default marketing, and that binding restores free-tier limits. This richness is far beyond what readOnlyHint=false and destructiveHint=false 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 lengthy but well-structured with a leading summary, clearly labeled sections, and bolded key phrases. While some redundancy exists (e.g., 'binding is free — no card' repeats the free-tier point), every section adds decision-relevant information. It is more verbose than strictly necessary but earns its length through complexity.

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

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

Given the tool's complexity (mutation, consent, alternatives, failure modes), the description covers prerequisites, post-conditions, what happens on failure, the exact consent language to share with the human, and how to handle edge cases like gate mid-task. The output schema exists, so return values need no explanation. This is a complete operational picture.

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 enhances this by providing usage semantics for each parameter: email must be explicitly given, api_key can be omitted to use the session key, and marketing_opt_in defaults false and requires explicit human agreement. It adds practical constraints and examples (e.g., rejected placeholder addresses) that the schema alone does not convey.

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

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

The description clearly states the action: 'Tie your DC Hub key to your human's email so the key is RECOVERABLE and upgrade receipts land in the right inbox.' It uses a specific verb-resource pair and contrasts with sibling tools like recover_my_key and subscribe_digest, making its unique role unmistakable.

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

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

Provides explicit when-to-use guidance ('Call this once your human shares their email'), when-not-to-use ('If your human hasn't shared an email, ask them first'), and alternatives (the OAuth sign-in path, and subscribe_digest via marketing_opt_in). This exceeds basic usage context by naming specific alternatives and 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?

Despite annotations being minimal, the description discloses key behavioral traits: re-minting restarts the daily allowance and orphans history, the returned api_key must be set as X-API-Key header, and the key is recoverable only if email is passed. It also explains the OAuth alternative and its limitations, adding substantial context beyond the annotations. 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 extremely long and discursive, with multiple asides and repeated statistics (e.g., 41.3% unused keys, 2,586 redemptions). While structured with star bullet sections, it is not concise and many sentences could be trimmed without losing core 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?

The description covers all necessary context: when to use, when not to use, alternatives, side effects, return value shape, and follow-up actions. It even includes measured data and recovery instructions, making it fully complete for the complexity of an authentication/key-minting tool.

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

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

Schema coverage is 100% with both parameters described, so baseline is 3. The description adds extra meaning by explaining the purpose of email ('to make the key RECOVERABLE across sessions... durable anchor for hosted web clients') and client_name ('Your agent/app name for attribution'), going beyond the schema's 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 clearly states the tool's function: 'Mint a FREE DC Hub dev key instantly — no email, no browser, ONE call.' It distinguishes itself from sibling tools by explicitly contrasting with recover_my_key and unlock_more_data, and by specifying when minting is the correct choice.

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: 'Call this the moment you hit a paywall or a 1-result preview' and 'Mint only when you actually need the higher free-tier allowance.' It also gives clear exclusions and alternatives, such as 'Do NOT call this again if you already hold a key' and 'Lost a key your human already had? Call recover_my_key instead.'

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description goes well beyond by detailing the physics computation (haversine, fiber constant, route_factor 1.4), confidence tiers, return structure, and the fail-closed candidate_contract behavior. It also warns that estimates are inference, not engineered quotes, and emphasizes quoting confidence_v. 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-structured, front-loaded with purpose and 'Use when,' and includes examples, return format, and cautionary notes. Slightly verbose due to repeated details (e.g., candidate contract appears in schema and description), but every sentence serves a purpose 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?

For a tool with 4 parameters, no required params, and an output schema, the description is exceptionally complete. It covers input alternatives, output structure, example usage, limitations, and alternatives. No significant 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 description coverage is 100%, so baseline is 3. The description adds an example and context about candidate_ids, but basically repeats what the schema already says (e.g., cand_ tokens, frozen coordinates, expiration handling). It does not materially augment the schema definitions for individual parameters.

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

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

The description clearly states the tool's purpose: 'Physics-bounded latency clustering for 2-8 sites — returns viable low-latency clusters and pairwise RTT floors before any routing work.' It uses a specific verb ('cluster') and resource ('sites by latency'), and distinguishes itself from siblings by naming alternatives like plan_fiber_leadin and get_fiber_readiness.

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

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

Provides explicit when-to-use guidance: 'Use when your human wants to know which of N candidate sites can form a synchronous / low-latency cluster' and 'deterministic pruning BEFORE detailed routing.' It also tells when NOT to use it ('Do NOT treat this as an engineered latency quote') and directs to alternatives ('For actual route corridors use plan_fiber_leadin; for a single-site connectivity score use get_fiber_readiness').

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=true, idempotentHint=true, destructiveHint=false), the description adds significant behavioral nuance: it clarifies that avg_time_to_power_months and avg_queue_wait_months are different measurements, warns about metric interpretation, and details the return structure. This goes well beyond what annotations provide and has no contradiction.

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

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

The description is dense but every sentence serves a purpose: use case, example, parameter syntax, return format, metric nuance, and alternative-tool exclusions. It is front-loaded with the primary use case and efficiently structured, despite its 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 moderate complexity, the description fully covers the parameter semantics, return structure, metric definitions, and tool boundaries relative to siblings. The output schema exists but the description enumerates its fields, and the explicit exclusions ensure the agent knows exactly when this tool is appropriate and when not.

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 documents the 'isos' parameter with format examples and valid values. The description adds a usage example (compare_isos isos="PJM,ERCOT,CAISO") and the '2-4 max' constraint, reinforcing the schema. It repeats most schema info but adds a practical example, providing marginal extra value over the schema's 100% coverage.

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

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

The description clearly states the tool's purpose: a side-by-side comparison of 2-4 ISO grids covering fuel mix, demand, renewable/gas share, interconnection-queue depth, and time-to-power. It distinguishes itself from siblings by explicitly referencing when to use it instead of get_grid_intelligence or get_grid_scoreboard, and provides a concrete example usage.

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

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

The description gives explicit when-to-use criteria (user wants side-by-side of 2-4 ISO grids) and when-not-to-use exclusions (for global ranking use get_grid_scoreboard, for single-ISO deep brief use get_grid_intelligence). It also explains that it avoids N sequential calls, providing clear 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?

Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint), the description discloses that it runs analyze_site reads on each parcel, ranks them, and notes the paid/Pro tier restriction (free tier returns locked preview). These are meaningful behavioral traits not captured 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?

The description is quite long but well-structured, front-loading the primary use case and embedding an example. Each sentence delivers value (usage, behavior, params, output, tier restriction, exclusions), though it could be slightly trimmed without losing essential 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?

Even with an output schema present, the description provides a detailed return shape, including the winner field and decision rationale. It also covers the free-tier limitation, parameter constraints, and explicit alternatives. This is a comprehensive description for a tool of moderate 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 description adds meaning to 'locations' (semicolon-separated lat,lon pairs, 2-4 max) and 'capacity_mw' (target load, 50-500) with an example. However, the 'sites' parameter is not mentioned in the description, though the schema covers it. Since schema coverage is 100%, the baseline is 3, but the added example and range details justify 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 compares 2-4 candidate parcels side-by-side and provides a winner picker with recommended pick and reason. It distinguishes itself from siblings by explicitly naming analyze_site for single sites and rank_markets for entire 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 (user has narrowed to 2-4 candidate parcels, wants side-by-side comparison) and when-not-to-use with named alternatives: 'Do NOT use for a single site (use analyze_site) or to rank entire markets (use rank_markets).' Includes a concrete example.

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 meaningful behavior beyond the annotations: it discloses the default 'cheap' mode (only a comparables count), the paid-key requirement for the full autopsy read, and the progressive disclosure behavior with comparables=summary/full. Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower; the description enriches this with cost and access context. It does not contradict annotations and adds transparency about auth needs and output detail levels.

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 efficiently structured: opening purpose, then return fields, then progressive disclosure, then a concrete example. Every sentence contributes functional or usage information, and the front-loading is good. It is slightly long but not wasteful; the 'what is the real play?' phrase adds flavor while aiding purpose clarity. A minor reduction could make it tighter, so 4.

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

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

For a tool with two optional parameters, an output schema, and rich annotations, the description covers the key facets: what it returns, the verdict overlay, pricing/auth implications, and the comparables escalation path. It omits details like sorting and date ranges, but the output schema likely covers return structure, and the provided context is sufficient for an agent to select and invoke correctly. The presence of an output schema reduces the burden, so 4.

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 both parameters with 100% coverage, giving the baseline of 3. The description goes further by explaining the comparables values behaviorally (default count-only, 'summary' for top-2, 'full' for the complete cited set) and explicitly emphasizing the 'cheap default'. It also reiterates limit's default. This adds semantic context beyond the schema, 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 identifies the tool's specific purpose: returning tracked data-center M&A/capex deals with a DCPI grid-reality verdict overlaid on each deal's market. It specifies the output fields (buyer, seller, value, market) and distinguishes itself from generic deal/list tools by the autopsy/verdict angle and comparables escalation. The verb 'Returns' and resource 'deal flow' make the function explicit and unique among siblings.

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

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

The description provides clear context on when to use the tool: for recent deal flow with DCPI verdicts, and how to escalate comparables ('summary' for top-2 signals, 'full' for drilling into a deal). It does not explicitly name alternative tools or state when NOT to use it, but the progressive disclosure guidance and example ('Try: deal_autopsy limit=15') give practical usage direction. This is more than implied usage but lacks explicit exclusions, so 4 rather than 5.

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

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

Annotations already declare readOnly/idempotent/non-destructive. Description adds return structure (_entity=tool_families), the front_door block contents (execute_plan, get_changes), and warns it is not the canonical catalog. No contradiction, and it provides context beyond annotations.

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

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

Description is ~110 words but front-loaded with 'Meta-tool: navigate...' and every sentence carries distinct information—purpose, return shape, usage, and caveat. The list of family names could be trimmed, but overall it is efficient and well-structured.

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

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

Covers when to use, what it returns, relationship to tools/list, and references to execute_plan/get_changes for the front_door block. An output schema exists, so no need to enumerate fields. Sufficient for an agent to decide 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 has 100% coverage for the single optional query param with concrete examples. The description only says 'optionally filtered by a query', adding nothing beyond what the schema already documents.

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

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

Description clearly states 'Meta-tool: navigate DC Hub's tool catalog by FAMILY instead of scanning the whole list', providing a specific verb and resource. It distinguishes itself from the exhaustive tools/list and other sibling tools by framing as a navigation layer.

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

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

Explicitly instructs 'Call this FIRST when you are unsure which tool fits a task' and provides an exclusion: 'if you are BINDING a capability map, bind it from tools/list, not from here.' Also names alternatives like tools/list, making usage boundaries 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?

The description goes well beyond the annotations (readOnlyHint=true, idempotentHint=true, destructiveHint=false) by disclosing that each step runs real tools under the user's key with the same quota and depth, that it adds no data access beyond what the caller already has, and that it has execution limits (max 6/8 steps, fan-out cap 3, ~40s budget). It also explains behavior for long tails returning status=not_run. 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, largely due to a dense opening list of domains, but the length is justified for a complex orchestrator tool. It is front-loaded with key guidance, uses bold labels (THE FRONT DOOR, TIER-HONEST) for scannability, and every section earns its place. Minor ding for the sprawling first sentence.

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

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

Given the tool's complexity, the description is remarkably complete: it covers domain scope, use cases, alternative tools, execution mechanics, limits, return envelope structure, and how to compose the final answer. The output schema exists but the description already explains the return shape, so 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%, so the baseline is 3. The description adds some context (e.g., pass intent UNCHANGED, cohort never inside intent) but these are also in the schema descriptions. It does not materially enrich parameter semantics beyond what the schema already provides, though the examples are helpful.

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

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

The description states a specific, powerful purpose: unified data-center siting, power-grid capacity, and AI-compute infrastructure planning via a single orchestrated call. It clearly distinguishes itself from siblings by naming plan_query and direct single-tool calls as alternatives, and labels itself 'THE FRONT DOOR' for multi-topic questions.

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

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

Explicit when-to-use and when-not-to-use guidance is provided: use for multi-step questions when you want the answer path run for you, use plan_query when you only want the plan, and call single-tool questions directly. It also gives concrete example queries and notes it should be called FIRST for cross-domain questions.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds behavioral context by specifying the return format ('full file contents as text'), the data fields included (DCPI score, target MW, market, coordinates, notes), and characterizes the tool as the 'bulk-download path'.

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

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

The description is compact yet information-dense, with a clear front-loaded use statement, example, parameters, return value, and exclusions. Every sentence adds value; no filler or 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?

The tool is simple (one optional parameter), has full annotations and output schema, and the description covers purpose, usage, exclusions, return content, and format selection. It is fully sufficient for an agent to select and invoke correctly without 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?

The input schema already documents the format parameter with 100% coverage, so baseline is 3. The description adds a concrete example ('export_dataset format=geojson'), explains the format values beyond the schema ('csv' default, 'geojson' for GIS tools like QGIS), and clarifies the use case for each format.

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

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

The description states a specific action ('pull their saved DC Hub shortlist OUT of the platform') and the resource ('saved sites'), with clear output formats. It distinguishes this from sibling tools by explicitly naming list_saved_sites and save_site as alternatives for 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?

Provides explicit when-to-use context: 'Use when a user wants to pull... OUT of the platform for offline analysis, a spreadsheet, or ingestion into another tool.' It also gives a clear do-not-use directive with named alternatives: 'Do NOT use to list sites in-chat (use list_saved_sites) or to save a new one (use save_site)'.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, so the safety profile is covered. The description adds behavioral context by specifying the exact return shape ({id, title, text, url, metadata}) and framing the result as a 'citable public summary', which goes beyond the structured annotations.

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

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

Three sentences, each earning its place: purpose+source, return format, and alternative for full specs. No redundancy, no fluff, and critical information is front-loaded.

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

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

For a simple fetch-by-id tool with one well-documented parameter, output schema present, and strong annotations, the description fully covers what the tool does, when to use it, what it returns, and how it differs from alternatives. Nothing crucial is missing.

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

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

Schema description coverage is 100% and the parameter 'id' is already well-described in the schema as 'A facility id/slug from a prior search result'. The description repeats this relationship without adding new syntax or formatting details, so it provides no significant extra 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 clearly states the verb 'Fetch', the resource 'DC Hub record', and the specific scope: 'for an id returned by the search tool'. It distinguishes itself from siblings like get_facility and search by clarifying it returns a citable 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?

Explicitly says to use this tool with an id from the search tool, and directly names get_facility or opening the URL as alternatives when full structured specs are needed. 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?

The description adds meaningful behavioral context beyond annotations: it returns 'ranked alternatives, each with similarity_score, match_reasons, and key_differences versus the target' and clarifies discovery semantics ('this DISCOVERS candidates from a single seed facility'). Annotations already cover safety (readOnly, non-destructive), so this is solid added value. However, the mention of a non-existent 'capacity_mw' param slightly undermines trust.

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

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

The description is front-loaded with usage and includes an example, return format, and exclusions in a compact structure. It is slightly verbose and contains the param error, but every sentence otherwise serves a purpose. It earns a 4.

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 use case, example, return structure, and exclusions, which is good. However, it introduces a phantom 'capacity_mw' parameter, misstates requiredness, and omits mention of match_on and exclude_operator. Given the schema and output schema exist, this is not fully complete; the param error makes it a clear 3.

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

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

Schema coverage is 100%, so baseline is 3, but the description introduces errors: it lists 'capacity_mw' which is not in the schema and claims 'facility_id or name ... required' while schema has 0 required params. It also fails to explain actual params like match_on and exclude_operator. This actively misleads rather than enriching 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 uses a specific verb ('find alternatives') and resource ('facilities'), clearly distinguishing it from siblings. It states the exact use case: 'user likes ONE specific facility and wants similar nearby options to consider instead.' It also contrasts with score_facility and compare_sites, leaving no ambiguity.

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

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

Provides explicit when-to-use guidance with an example ('Find alternatives to the Ashburn QTS campus for about 50MW') and names alternatives for excluded use cases: 'Do NOT use to score one site (use score_facility or analyze_site) or to compare a known short-list head-to-head (use compare_sites).'

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the bar is lower. The description adds valuable behavioral context: pdf_report_url is a ready-to-open link, no login needed, valid ~7 days, and prepared_by brands the report with defaults. It also explains the latency_target default behavior. No contradictions with annotations.

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

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

The description is information-dense yet well-structured: starts with when-to-use, then an example, then parameter list, then return details, then alternative. Every sentence adds value; no filler or repetition. The length is appropriate for a tool with this complexity.

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

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

Given the 10 parameters, output schema, and annotations, the description covers the key aspects: purpose, example, parameter semantics, return structure, and PDF behavior. It even notes the output is a 5-page PDF and the survey fields. The pointer to analyze_site for simpler needs completes the contextual picture.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by summarizing key parameters with ranges and defaults: lat/lon ranges, capacity_mw example (50-500), prepared_for/client name, prepared_by/brands report, latency_target override. It also provides an example call illustrating parameter usage, which adds 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 states it generates a SHAREABLE, branded multi-page Site Analysis PDF for one lat/lon, with a clear verb (generate) and resource (site analysis PDF). It explicitly distinguishes from the sibling tool analyze_site by saying 'For just the numeric suitability score (no PDF), use analyze_site instead.' The example clarifies the intended use scenario.

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 a SHAREABLE, branded multi-page Site Analysis PDF' and provides a concrete user request example. It also explicitly says when not to use it by pointing to analyze_site for numeric scores only. This gives clear when/when-not guidance and alternative tool naming.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds value by stating this is a curated index, not live per-caller telemetry, which materially affects how the agent should interpret results. This goes beyond what annotations express.

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

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

The description is appropriately compact and front-loaded with the main purpose. The phrase 'Try: get_agent_registry' is slightly redundant, but the rest of the sentences each contribute meaningful semantics, including the important caveat about what the tool is not.

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

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

Given the tool has no parameters, an output schema is present (so return-value explanation isn't required), and the description clearly scopes what the tool does and doesn't do. The curated index nature, list of recognized clients, and explicit exclusions make the description complete for safe agent invocation.

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

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

The tool has zero parameters, and the schema provides no properties with 100% schema description coverage (vacuously). Per the rubric, a zero-parameter tool gets a baseline of 4, and the description correctly omits parameter details since none exist.

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

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

The description opens with a specific noun phrase ('Curated roster of the AI platforms + agent frameworks') and immediately clarifies the tool's scope. It distinguishes itself from live telemetry and from get_backup_status, making its unique role in the ecosystem clear.

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: 'Use it to see which platforms DC Hub supports and how to connect them.' It also gives a concrete negative case ('Do NOT use for platform uptime / backup health') and names the correct alternative (use get_backup_status).

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 agent knows it's a safe read operation. The description adds behavioral context beyond the annotations by detailing the specific status dimensions returned (e.g., green/yellow/red freshness, 0-100 heartbeat score), which helps set expectations for the output.

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

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

The description is concise yet informative, using a colon and comma-separated list to efficiently convey the tool's output scope. The sentences are well-structured: first defining what the tool returns, then providing usage context, and finally giving a clear exclusion with alternative. Every sentence earns its place.

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

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

Given that the tool has no parameters, strong annotations, and an output schema, the description is sufficiently complete. It clearly states the tool's purpose, what metrics to expect, when to use it, and when not to use it. No additional context is needed for an agent to select and invoke this tool correctly.

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

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

The tool has zero parameters and the schema is an empty object, so there is nothing for the description to add about parameter semantics. With 0 params, the baseline is 4, and the description contains no misleading or unnecessary parameter information.

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: it returns comprehensive platform health metrics including database backup status, data freshness, agentic heartbeat score, MCP call volume, and DCPI recompute cadence. It explicitly distinguishes itself from sibling get_changes, which is about specific dataset freshness, by noting this tool covers platform/infra health not content.

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

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

The description gives explicit when-to-use guidance: 'Useful for trust/uptime signals before relying on the platform in production.' It also provides an exclusion and a named alternative: 'Do NOT use for the freshness of a specific dataset (use get_changes); this is platform/infra health, not content.' This is clear usage direction.

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

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

Annotations already mark read-only/idempotent/non-destructive, so the description's rich behavioral detail is additive. It explains the conditional portfolio block for 'keyed callers with saved sites,' per-site verdict flips, excess-power deltas, alerts, and the caching contract for generated_at. This goes far beyond annotations.

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

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

The description is front-loaded with the core concept and structured into payload contents, conditional behavior, and parameter usage. It is longer than minimal, but every sentence conveys actionable detail; minor redundancy in the portfolio explanation keeps it from a 5.

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

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

For a two-optional-parameter, read-only, idempotent tool with an output schema, the description fully covers the tool's role, response composition, conditional portfolio behavior, and correct invocation pattern. The presence of an output schema means return-value details need not be duplicated.

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

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

Schema coverage is 100%, but the description adds significant semantics: since accepts ISO-8601 or shorthand ("24h"/"7d") with a default, and it ties the response's generated_at back to the next invocation. This practical usage guidance exceeds the schema's mechanical 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 'Incremental sync — what changed in DC Hub since a timestamp,' which clearly states a specific verb+resource+scope. It uniquely distinguishes this tool from siblings like get_news or get_facility by focusing on delta updates and enumerating exact return categories (market movers, facilities, M&A, news, portfolio).

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 frames the tool's purpose as avoiding re-fetching everything ('so an agent pulls only the delta instead of re-fetching everything'), gives concrete parameter guidance ('Pass since=<ISO-8601> or shorthand'), and advises caching generated_at for the next call. It does not name alternative tools, but the delta-sync context is clear enough.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint), the description discloses key behaviors: strict sourcing from federal databases, missing data declared unavailable rather than estimated, the radius_km snapping behavior and its 'unavailable_exceeds_radius' outcome, and the US-only seismic coverage. 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, with each section serving a purpose: use case, data source, example, return structure, radius behavior, and alternatives. The return structure block is somewhat verbose given an output schema exists, but it adds clarity for the agent. Slight redundancy lowers the score from 5.

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

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

The description is exceptionally complete for a complex tool: it covers purpose, use cases, data provenance, parameter semantics, edge cases (radius, non-US), return format, and sibling differentiation. It leaves little for the agent to infer, making it highly actionable without needing external docs.

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

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

Although schema coverage is 100%, the description adds significant meaning: it clarifies aliases (lat/latitude, lon/lng/longitude), provides a concrete invocation example, explains the radius_km default and snapping logic (nearest NOAA station), and indicates required parameters despite schema showing none as required. This goes well beyond the structured schema.

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

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

The description clearly identifies the tool's function: providing seismic and climate intel for a lat/lon, with specific data sources (USGS, NOAA) and downstream use cases (bracing cost, cooling design). It also differentiates from neighboring tools by naming get_disaster_risk and get_composite_site_score as alternatives for different needs.

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 seismic + climate intel for a lat/lon,' giving explicit context. It further states when not to use it (non-US for seismic) and points to alternatives (get_disaster_risk, get_composite_site_score), covering both when and when-not scenarios.

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

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

Annotations (readOnlyHint=true, idempotentHint=true) already declare safety traits, but the description adds substantial non-obvious behavior: 'never imputes a missing one', 'water is "unavailable" only outside basin coverage (never faked)', and 'market/DCPI is v1-unavailable (use rank_markets)'. It also discloses the confidence semantics (complete|conditional) and coverage_ratio, which are beyond structured annotations.

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

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

The description is dense but well-organized: use case, differentiating feature, example call, return structure, and sibling alternatives in a compact paragraph. It's slightly long but every sentence carries information. Not as clean as a two-sentence description, but appropriate for the tool's complexity.

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

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

This is a complex tool with an output schema, and the description enumerates the full return object (composite_score, verdict, confidence, coverage map, coverage_ratio, sub_scores, caveats). It explains edge cases (basin coverage, v1-unavailable) and gives usage context for siblings. The description fully equips an agent to invoke and interpret results.

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 descriptions for all parameters, so baseline is 3. The description adds value by explaining the purpose of 'state' ('improves water/context lookups') and providing a concrete example (lat=33.45 lon=-112.07 state=AZ). It also clarifies the lon/lng alias relationship, but this is already in the schema. Net: modest added meaning.

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

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

The description opens with a specific verb ('Use when a user wants ONE honest 0-100 site suitability/risk verdict') and clearly distinguishes this tool from siblings like analyze_site ('Unlike analyze_site (full raw data dump), this scores ONLY over VALIDATED factors'). It names the resource (site score for lat/lon) and scope (validated factors only), leaving no ambiguity about what the tool does.

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

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

Provides explicit when-to-use guidance ('Use when a user wants ONE honest 0-100 verdict'), plus a direct comparison with alternatives: 'Unlike analyze_site...' and 'Use analyze_site for full data, compare_sites for 2-4 sites, rank_markets for whole-market ranking.' This clearly steers the agent to the correct tool among many 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, destructiveHint, and idempotentHint, which cover the safety profile. The description adds valuable behavioral context: it returns a ready-to-quote answer, includes a summary_text with CC-BY-4.0 licensing, and provides a citation URL, all of which help the agent understand outputs and usage implications beyond the annotations. While it doesn't discuss rate limits or auth, those are not necessary given the read-only nature.

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 efficiently structured with a use-case lead, example, parameter explanation, return object summary, and exclusions. Every sentence serves a distinct purpose, and there is no redundancy or filler. It is longer than the simplest examples but appropriately sized 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 the input semantics, the full return shape (top_markets with verdicts, candidate_facilities, factor_breakdown, summary_text, citation_url), and clear exclusions. With an output schema present, it need not explain return values in further detail. The guidance about orchestrating 5+ tools and the license note add important context for an agent deciding whether and how to use 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 coverage is 100% and the schema's parameter description already explains the context field with components and an example. The description reinforces this by restating the context components and showing a full invocation example, adding marginal semantic value beyond the schema. This warrants a 4 rather than a baseline 3.

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

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

The description clearly states the tool's purpose: it handles open-ended siting questions and returns a ready-to-quote recommendation, distinguishing it from analyze_site and rank_markets by explicitly naming those alternatives in the exclusions. The verb 'get' plus the resource 'DC hub recommendation' 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?

The description provides explicit when-to-use guidance with a concrete example, and equally explicit when-not-to-use instructions naming specific alternatives: 'Do NOT use for a single specific lat/lon (use analyze_site) or to rank by ONE criterion only (use rank_markets).' This fully satisfies the dimension.

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?

Though annotations already declare readOnlyHint=true and destructiveHint=false, the description adds substantial behavioral context: it specifies the data source (FEMA NRI), the live-query nature ('never estimated'), county-level resolution, and the specific behavior for out-of-coverage points. This goes well beyond what annotations alone convey, so the description carries its weight.

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

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

The description is information-dense but every sentence adds value: the use case, hazard list, data source, example, return object summary, resolution note, and sibling alternatives. It is front-loaded with the most important information and avoids repetition of schema details. The structure is logical and concise for the amount of content delivered.

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 presence of both input and output schemas, and the many sibling tools, the description is remarkably complete. It covers what the tool does, when to use it, data provenance, coverage behavior, example invocation, return structure, and alternatives. There are no significant gaps for an agent to misuse it.

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

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

The input schema already provides 100% coverage of all five parameters (lat/lng/lon/latitude/longitude) with descriptions of their aliases. The description adds a concrete example (lat=33.45 lon=-112.07) and clarifies that the tool expects a lat/lon pair, which adds marginally useful semantics beyond the schema. However, it does not elaborate on parameter validation or edge cases, so a 4 is appropriate.

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

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

The description clearly states the tool's purpose: retrieving natural-hazard/disaster risk for a lat/lon coordinate, listing specific hazard types (flood, wildfire, hurricane, etc.). It explicitly distinguishes from sibling tools by naming get_water_risk and get_composite_site_score as alternatives, making it easy to select the right tool.

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

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

The description begins with 'Use when a user wants...' and provides an explicit alternative clause: 'For chronic water stress use get_water_risk; for one blended site verdict use get_composite_site_score.' It also notes coverage limitations (points outside US return coverage=unavailable), giving clear guidance on when this tool applies versus when it does not.

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

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

Annotations already cover read-only, idempotent, non-destructive traits. The description adds value beyond these: it notes the attribution requirement (DC Hub CC-BY-4.0), the output fields, and the advantage of a 'single round trip, no planner overhead'. It does not contradict any annotation.

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

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

The description is longer than average but well-structured: a front-door decision check, use-case statement, output summary, example, and explicit exclusions. Every sentence serves a purpose and none are redundant, though it could be tightened slightly.

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 large sibling set, the description is remarkably complete. It tells the agent exactly when this tool is the right choice, what it returns, how to attribute the data, and which alternatives to use for other questions. The output schema handles detailed return types.

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 describes all 3 parameters with 100% coverage, the description adds critical semantics: it explicitly states iso is required (even though the schema lists no required fields), enumerates the recognized ISO codes, and clarifies the meaning of pricing units returned. This helps correct a potential misinterpretation.

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: returning live energy pricing (retail electricity, wholesale/LMP, Henry Hub gas, grid status) for 7 US ISOs. It distinguishes itself from siblings by explicitly naming what not to use it for and which tools to use 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?

The description gives explicit when-to-use ('today's price for one ISO') and when-not-to-use guidance (siting/market-comparison questions should go to execute_plan, fuel mix/demand to get_grid_data, headroom to get_grid_intelligence, gas-to-grid economics to get_gas_economics). It also includes an example query and parameter hint.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, and the description adds clarity by stating 'Returns ONE facility in full' and explaining the 'peer facilities nearby' inclusion. It does not contradict annotations, but could have mentioned error behavior (e.g., if id not found) which is a minor gap. The added examples and field list provide useful context beyond the structured data.

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

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

The description is tightly written: one sentence listing the full metadata scope, one sentence with usage examples, and one sentence defining boundaries. Every sentence adds unique value, and the most important info (what it returns) is front-loaded.

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

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

With an output schema present, annotations covering safety, and a description that explains the single-facility scope, example invocations, and key included data, nothing critical is missing. The tool's purpose and constraints are fully understandable from the given 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 has 100% description coverage for all 6 parameters, so the baseline is 3. The description adds value by showing concrete usage with id= and slug=, and clarifies that those come from 'a prior search result'. This makes parameter roles clearer without repeating schema text.

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

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

The description clearly states the tool 'Returns ONE facility in full' and enumerates the exact metadata fields (name, operator, address, lat/lon, power capacity, cooling type, fiber providers, etc.). It distinguishes itself from the sibling search_facilities by explicitly saying '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?

The description provides explicit usage guidance: 'Try: get_facility id=equinix-dc1-ashburn — or get_facility slug=digital-realty-iad8' and directly names the alternative 'use search_facilities' for searching. This leaves no ambiguity about when to use this tool vs. 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?

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses the integrity model: only DCPI market-health has a temporal series, static dimensions are never fabricated with week-over-week deltas, and missing snapshot history results in 'coverage:unavailable'. This is substantial behavioral context not present in the schema or annotations, and it does not contradict any annotation.

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

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

The description is front-loaded with the 'Use when' clause and then systematically covers return value, integrity constraints, parameters, response shape, and alternatives. Every sentence adds unique value, and clear structural markers (INTEGRITY, Params, Returns) make it easy to scan despite its 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?

For a tool with three optional parameters, a nested return object, and significant edge cases, the description is thorough. It explains the temporal scope, the static dimensions, the coverage behavior, and points to alternatives. Since an output schema exists, the description does not need to enumerate every return field.

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 provides 100% coverage for all three parameters, so the baseline is 3. The description adds meaningful relational guidance: 'facility_id ... OR market' implies exactly one should be provided, and it reinforces the default for 'since'. This extra layer of relationship semantics 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 the tool returns changes in a facility's or market's risk profile over time, using specific language like 'what has CHANGED' and 'Returns the REAL DCPI market-health delta'. It distinguishes itself from sibling point-in-time risk tools by explicitly positioning it as the temporal answer and naming 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?

The description begins with 'Use when a user asks what has CHANGED...' and provides concrete example queries. It gives explicit alternatives: 'For the current point-in-time risk (not the change) use get_composite_site_score / get_disaster_risk / get_climate_intel.' This fully addresses when to use vs. when not to.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description does not contradict them. It adds meaningful behavior: return format (GeoJSON FeatureCollection), market filtering semantics ('only routes touching that metro'), and the 'ready to drop into Leaflet/Mapbox' detail. It could mention rate limits or exact radius (though the schema adds ~1.2°), but overall it adds useful context beyond annotations.

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

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

The description is dense but every sentence earns its place: use cases, example, parameter summaries, return schema, and exclusions. It front-loads the key purpose and is logically structured with clear sections. No fluff or repetition.

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

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

For a read-only, idempotent tool with a rich output schema and strong annotations, this description fully covers selection and invocation. The return format is explicitly described, key parameter behaviors are explained, and exclusions identify what not to use this for. 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 description coverage is 100%, so the baseline is 3. The description exceeds the schema by enumerating the full carrier list including options not in the schema's example list (FiberLight, Segra, Arcadian Infracom), explaining route_type meanings, and detailing how the market parameter works with route_type. This adds real value beyond the schema's 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 clearly states the tool's purpose: scoring sites for fiber depth, mapping long-haul routes, and assessing dark-fiber availability. It uses a specific verb and resource ('get fiber intelligence'), and distinguishes itself from siblings by explicitly naming alternatives (get_facility, analyze_site) 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 (scoring, mapping, dark-fiber assessment), a concrete example query, and equally explicit when-not-to-use guidance with alternative tool names. This is the gold standard for usage differentiation.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds behavioral context: the tool works for exactly ONE parcel/site, uses a radius_km search parameter (default 50, range 5-200), and returns a specific verdict structure. There is 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-organized: purpose, example, parameter list, return structure, and exclusions each earn their place. It is longer than the minimal two-sentence format, but for a tool with 6 parameters and 8 return fields, the length is justified. The front-loaded purpose 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?

Given the tool's complexity, the description covers the primary use case, parameter constraints, return fields, and explicit alternatives. It doesn't explain the near_net_bucket enum values or the alias parameters, but these are left to the schema/output schema. It is sufficiently complete for an agent to invoke the tool correctly for its main intended purpose.

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 repeats the lat/lon ranges and radius_km default/range already present in the schema, but adds a concrete example and clarifies radius_km's purpose as the search radius for reachable fiber carriers. However, it does not mention the alias parameters (lng, latitude, longitude) and adds little semantic value beyond the schema.

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

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

The description opens with a clear verb+resource+scope: 'Use when you need the FIBER-READINESS / connectivity verdict for ONE parcel or site'. It lists the specific outputs (near-net distance, carrier count, single-carrier risk) and explicitly distinguishes from sibling tools (get_fiber_intel, analyze_site), making it unmistakable what this tool does.

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

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

The description gives explicit when-to-use guidance ('Use when you need...') and when-not-to-use guidance with named alternatives: 'Do NOT use to map carrier ROUTES between metros (use get_fiber_intel) or for a full multi-factor site suitability score (use analyze_site).' This is exactly the level of direction an agent needs.

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

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

Beyond readOnlyHint and idempotentHint annotations, the description discloses a major withdrawal (gas-to-grid $/MWh no longer returned), explains the data quality issue that led to withdrawal, and provides specific instructions on how to handle the $/MMBtu layers and gas_to_grid_status. This is far more transparent than annotations alone.

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

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

The description is front-loaded with purpose, then uses a clear warning section for the withdrawn feature. Every sentence carries essential safety or usage information, with no filler. The length is justified by the complexity of the data and the critical warnings about data quality.

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

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

Given the tool's complexity, the description covers purpose, parameter usage, withdrawal details, alternative tools, and explicit dos/don'ts. The presence of an output schema means return values don't need to be spelled out. This description is exceptionally complete for safe agent invocation.

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

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

Schema coverage is 100%, but the description adds critical context: market is exemplified with 'northern-virginia', 'dallas', 'phoenix' and points to valid slug sources. For heat_rate_btu_per_kwh, it clarifies that the gas-to-grid $/MWh scenario is no longer returned, effectively warning the agent that the parameter is obsolete, which the schema alone would not convey.

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

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

The description clearly states that the tool returns behind-the-meter/gas-fired power inputs (Henry Hub spot, basis differential, delivered tariff) for a US data-center market, with a specific resource and verb. It distinguishes itself from siblings by explicitly naming get_grid_data as the tool for electricity grid fuel mix.

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: 'Do NOT use for the electricity grid fuel mix (use get_grid_data)' and explains valid market slugs come from rank_markets / get_market_dcpi_rank. It also warns against quoting cached or self-derived $/MWh figures, giving clear usage constraints.

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 that the backend returns an `unavailable_reason` instead of a score, explains specific defects (interstate-share term and cost term issues), and warns against quoting cached figures. This goes well beyond the readOnly/idempotent annotations, providing critical 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 front-loaded with the withdrawal warning and immediately states the consequence. While it includes detailed defect explanations, these are purposeful for understanding why the tool is unusable. Slightly long but all content 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?

Given the tool is withdrawn, the description fully explains the situation: what changed, why, what the backend returns, and which alternative to use. With an output schema present, no return-value description is needed, and the caution about cached figures covers the safety aspect.

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 both `limit` and `state` parameters with 100% coverage, including state format examples. The description adds no additional parameter-specific semantics, so it meets the baseline for high schema coverage.

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

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

The description clearly identifies the tool as the per-US-state natural-gas suitability score (DCGI), then explicitly states it is withdrawn and no longer returns a score. It distinguishes from siblings by referencing get_gas_intelligence as the correct alternative for unaffected data.

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

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

Provides explicit usage guidance: 'Use get_gas_intelligence for the natural-gas pipeline, operator and parent-midstream data, which is unaffected' and warns 'DO NOT quote a cached DCGI figure.' This clearly tells the agent when to use this tool (never for scores) and what to use instead.

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

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

Annotations already establish read-only/idempotent/non-destructive behavior. The description goes well beyond by disclosing withdrawn fields (dcgi_score, dcgi_verdict, gas_to_grid_usd_per_mwh), explaining why they were withdrawn, and emphasizing that data is 'surfaced honestly, never fabricated' and 'deliberately OMITTED' for certain categories. It also warns against quoting cached values, providing valuable context for safe invocation.

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

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

The description is front-loaded with the 'Use when...' directive and structured into clear sections (use, returns, withdrawals, exclusions). However, it is quite verbose, especially the withdrawal paragraph and return field list, which could be tightened without losing critical safety warnings. Still, every section earns its place given the tool's history.

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 fully covers the tool's purpose, return fields, omitted data, historical changes, and exclusion boundaries. The presence of an output schema further reduces the need to enumerate return values, but the description does so anyway with useful annotations. It is complete enough for an agent to select and invoke the tool correctly in any 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% with clear parameter descriptions for both 'state' and 'region'. The description only repeats the 'region' parameter format and omits the 'state' alias entirely, adding minimal information beyond what the schema already provides. The baseline of 3 is appropriate because the schema does the heavy lifting, and the description's partial mention could even cause slight confusion.

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

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

The description opens with a specific use case ('gas-fired or behind-the-meter power economics for a data center in a US state') and includes concrete example queries. It clearly distinguishes itself from siblings by explicitly stating it is the 'GAS analogue of get_grid_intelligence' and by naming exclusions ('Do NOT use for electricity grid headroom (use get_grid_intelligence) or the DCGI score alone (use get_gas_index)').

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 triggers with real query examples and states when-not-to-use with named alternative tools. The guidance 'Use when a human asks...' and 'Do NOT use for...' is unambiguous and directly 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, which is consistent with the description. The description goes beyond annotations by adding behavioral context: it explains the data source (Global Energy Monitor Global Integrated Power Tracker), coverage (182,000+ units, 170+ countries), what fields each unit has, and the return format (summary by fuel and status plus largest units). No contradictions with annotations.

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

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

The description is appropriately sized given the tool's complexity (7 parameters, global scope). Every sentence earns its place: usage context, data coverage, filter list, return summary, example, and exclusions. It is well-structured and front-loaded, 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 and the presence of an output schema, the description is complete. It covers all key aspects: when to use, what data is included, filter options, return format, and alternatives. The output schema handles return value details, so the description need not duplicate that. This is a fully self-contained 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?

With 100% schema description coverage, the baseline is 3, but the description adds substantial meaning: it explains 'pipeline=true' as 'JUST the forward set: announced + pre-construction + construction', clarifies 'fuel' as a comma-union, gives concrete examples (Germany, India, Brazil, Japan), and specifies bbox format. It even provides a sample query, which helps agents understand parameter usage far 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's purpose: it retrieves global power plants/units worldwide or in non-US countries, covering both operating and forward pipeline, across all fuel types. It explicitly distinguishes from sibling tools by stating what it is NOT for (US grid telemetry, US planned-generator feed) and naming alternatives, making it highly distinguishable.

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

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

The description provides explicit when-to-use guidance: 'Use when a user asks about power plants/units WORLDWIDE or in a NON-US country.' It also gives clear when-not-to-use instructions and names alternatives (get_grid_intelligence, get_grid_scoreboard, get_power_pipeline), fulfilling the 'when/alternatives' criteria completely.

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

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

The annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, so the safety profile is covered. The description adds context about the data being 'raw real-time telemetry for one ISO' and the source 'via EIA hourly RTO', which informs the agent about the nature and limitation of the data. It does not cover rate limits or error conditions, but the annotations cover the key safety concerns.

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

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

The description is three sentences: the first states what the tool returns, the second gives a usage example, the third provides exclusions with alternatives. Every sentence earns its place, and the core information is front-loaded.

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

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

The description is complete for the agent's selection and invocation needs. It covers what the tool does, the target scope (7 US ISOs), what data types are available, how to pass parameters, and when not to use it with specific alternatives. The output schema exists, so return values are already documented. No critical context is missing.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds an explicit example ('Pass iso=PJM') and clarifies the cardinality ('for one ISO'). It also reinforces the ISO list and the metric/period examples. While most parameter information exists in the schema, the description's usage hint and clarification of single-ISO constraint add 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 clearly states that the tool provides real-time electricity grid data for the 7 US ISOs, listing the ISOs and the specific data types (fuel mix, demand, 24h demand curve). It distinguishes itself from sibling tools by explicitly naming the alternatives for different use cases (get_grid_intelligence, get_energy_prices, 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 provides explicit when-to-use and when-not-to-use guidance, including direct alternatives: 'do NOT use for power-availability, time-to-power or interconnection-queue analysis (use get_grid_intelligence), nor for retail/gas pricing detail (use get_energy_prices). For non-US grids (GB, EU bidding zones, Taiwan, Australia) use get_grid_scoreboard.' It also gives a concrete usage example ('Pass iso=PJM').

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and the description does not contradict them. It adds important behavioral context: the distinction between avg_time_to_power_months and avg_queue_wait_months, and the note that balancing authorities return live generation mix but other metrics remain ISO-level. This goes well beyond the structured annotations.

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

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

The description is dense and front-loaded with the primary use case and example. It is longer than average, but each section (use case, params, returns, caveats) is purposeful. The return-field list is extensive and might partially overlap with the output schema, slightly reducing conciseness, but the added caveats 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's complexity, the description covers every necessary context: the exact trigger phrase, parameter semantics with aliases, the output structure, metric caveats, and explicit alternatives. The output schema exists, but the description still provides the nuanced interpretation needed to avoid misquoting metrics. This is as complete as one could expect.

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

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

Although schema coverage is 100%, the description significantly enriches parameter semantics by explaining that iso/region are aliases for region_id, listing all 7 ISOs, providing concrete balancing-authority examples, and describing the special PJM-DOM zone. This adds meaning far 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 clearly states the tool's purpose: a grid-headroom and interconnection-queue brief for one ISO, with an explicit example query and expected output. It distinguishes the tool from siblings by naming alternatives for side-by-side comparisons (compare_isos) and global rankings (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?

It explicitly says 'Use when a user asks...' and provides a concrete example. It also gives clear exclusions: '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 when-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 only declare safe-read/idempotent hints, but the description adds crucial behavioral context: non-uniform freshness, per-row mix_age_hours, demand_vs_mix_lag_hours, and specific data gaps (Brazil no gas share, Australia/Singapore partial). 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 a single, extremely long paragraph with dense parentheses and caveats. It is not appropriately sized; while front-loaded with 'GLOBAL grid scoreboard', it rambles through every grid, source, and edge case, making it hard 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 verbosity, it covers all needed context: what the scoreboard contains, how freshness works, which grids are included, exclusions and partial data, and attribution. Even with an output schema present, it explains return semantics thoroughly enough for a zero-parameter 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?

Tool has zero parameters and empty schema properties, so baseline is 4. The description focuses on output semantics rather than parameters, which is appropriate here.

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 it returns a global grid scoreboard with renewable share, gas share, fuel mix, and demand, ranked side-by-side. It explicitly distinguishes from siblings: 'vs compare_isos (pairwise) or get_grid_data (single ISO)'.

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 guidance on when to use: 'One call answers "which grid worldwide is greenest, or most gas-reliant, for siting a data center?"' and names alternatives. Also warns about interpreting freshness before usage: 'Read mix_age_hours before narrating any row as current'.

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 readOnlyHint/idempotentHint/destructiveHint annotations, the description discloses data integrity behavior: distinct_feeders vs geometry_rows_scanned are never conflated, sample_complete=false with capacity_floor_mw flags capped reads, and out-of-coverage points return an explicit not-published answer with nearest markets, never a silent zero. It also warns that gen capacity must not be relayed as available load, which is critical behavioral context not inferable from annotations.

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

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

The description is long but well-structured, with a front-loaded definition, separate paragraphs for invocation, capacity_type semantics, return details, honest-behavior explanation, coverage caveats, exclusions, and a disclaimer. Some repetition with the schema (e.g., radius_km default, NO ARGS) could be trimmed, but the density serves a tool with high-stakes semantics and 11 parameters.

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

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

For an 11-parameter tool with an output schema and annotations, the description leaves no significant gap. It covers purpose, invocation methods, return structure with specific fields, coverage limitations, data provenance, honesty flags, explicit exclusions with sibling tool names, an example call, and a final informational disclaimer. This is complete enough for an agent to select and invoke correctly without 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?

The schema already covers all 11 parameters with 100% description coverage, so the baseline is 3. The description adds value by noting which utilities publish 'load' capacity (only Ameren Illinois, AEP Ohio & I&M, Central Hudson), provides a concrete parameter combination example, and re-emphasizes the capacity_type meanings in high-stakes terms. It does not reach 5 because most parameter semantics are already in the schema.

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

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

The description states the exact resource: utility-published feeder hosting capacity in MW for a named distribution feeder, sourced from utility GIS. It names the specific verb (get) and distinguishes from siblings by explicitly naming alternative tools for adjacent use cases, clarifying this is the distribution feeder layer, not transmission or interconnection queue.

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

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

Explicitly says when to use (for feeder hosting capacity questions) and when NOT to use, naming get_grid_intelligence, get_interconnection_queue/get_refined_queue, and get_retirement_headroom as alternatives. Provides a concrete example call and explains the three invocation modes: point, utility, and no-args coverage list.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds valuable behavioral context: it returns distance and capacity per asset, joins data to HIFLD/EIA, and explicitly notes it returns raw assets, not a scored verdict. This is sufficient to understand the tool's output nature without over-explaining.

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

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

The description is three sentences: the first packs the core purpose and asset categories with specific details; the second is a clear runnable example; the third gives a concise usage caution. Every sentence earns its place, and the structure front-loads the most critical 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 output schema exists (so return values are documented there) and the tool has 9 parameters with full schema descriptions, the description is complete enough. It covers the core asset types, provides an example, and gives a key usage distinction. It could mention default radius or layer behavior, but the schema and example suffice for most use cases.

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 100% parameter description coverage, so the baseline is 3. The description reinforces key parameters (lat/lon, radius_km, min_voltage_kv) through the example and asset details, but does not add substantial meaning beyond the schema. No additional parameter semantics are needed given the schema richness.

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 begins with 'Nearby infrastructure for a location' and enumerates specific asset types (substations, transmission lines, pipelines, power plants), each with details. It also explicitly distinguishes from the sibling tool 'analyze_site' by stating 'do NOT use for a single scored site-suitability verdict (use analyze_site)', making its scope unambiguous.

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

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

The description explicitly states when to use the tool ('Returns raw nearby assets') and when not to, naming the alternative: 'do NOT use for a single scored site-suitability verdict (use analyze_site)'. It also provides a concrete example invocation, further clarifying typical 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 and idempotent behavior. The description adds that the tool aggregates six components and returns both the index and supporting data. However, the statement 'Returns ONE composite health number' is slightly ambiguous given the multiple output fields listed, and the example suggests a parameter not present in the schema, which may mislead about invocation.

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

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

The description is moderately concise, with the main purpose in the first sentence and exclusions in the final sentence. The example is useful, but the first sentence is dense with component names. Overall, it is structured well with no wasted sentences.

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

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

The tool has an output schema, so return values are presumably covered there. However, the description introduces a 'market' parameter in the example while the schema declares no parameters, creating a contradiction that leaves an agent unsure how to invoke the tool. The description does not clarify this discrepancy or explain the parameterless invocation, so it is incomplete for correct 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?

The input schema has zero parameters, so the baseline is 4. The description adds meaning by showing an example with 'market=northern-virginia', which is the only guidance on how to specify the target market, though this conflicts with the empty schema. It does not provide a full parameter specification.

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's purpose as providing a real-time composite market health score with specific aggregation inputs. It distinguishes itself from get_market_intel and rank_markets by explicitly stating what it is NOT for, making its scope unambiguous.

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

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

Explicitly states that the tool returns ONE composite health number for a market and directs users to get_market_intel for full market metrics or rank_markets for ranking multiple markets. Provides a usage example with market=northern-virginia, so an agent knows the invocation pattern.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds significant context beyond those: the ERCOT unique large-load data center queue (with specific 225 GW figure), null handling for other ISOs, provenance in top_subregions, and data sources. This enriches the agent's understanding of behavior without contradicting any annotations.

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

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

Though longer than many descriptions, every sentence carries specific, non-redundant information. It front-loads the core purpose, then adds limitations, unique features, sources, and exclusions in a logical flow. No unnecessary words; packed but 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?

With a single optional parameter, full schema coverage, rich annotations, and an output schema, the description covers all necessary context: what it returns, unique ERCOT behavior, specific use cases, and explicit exclusions. It is complete for an agent to decide 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?

The schema already provides a thorough description of the only parameter (iso, listing all valid values and omission behavior). The description's mention of 'Pass iso=ERCOT (or any of 7)' adds no new information beyond the schema. Given 100% schema coverage, baseline 3 is appropriate; no additional semantic value is added.

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 clear verb+resource: 'ISO interconnection queue snapshot: total queued GENERATION capacity...' It precisely defines scope (per ISO, from public queues) and distinguishes from siblings by explicitly naming alternatives for different use cases (get_grid_intelligence, grid_transition_radar). This exceeds simple clarity and achieves strong 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?

Explicitly states when to use: 'Use for queue-depth site-selection and AI/data-center-load saturation intel' and when not to use: 'Do NOT use for a single-site time-to-power read (use get_grid_intelligence) or forward-looking emergence (use grid_transition_radar)'. Also provides operational guidance like 'Pass iso=ERCOT (or any of 7) to drill down.' This is model 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 mark this as read-only and idempotent, and the description goes further by disclosing the greedy token-budget filling behavior, per-section token counts and as_of timestamps, citable URLs, and the returned 'omitted' field. It also notes the citation requirement ('DC Hub (dchub.cloud)'). No contradictions with annotations.

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

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

The description is dense but every sentence serves a purpose: use case, contents, token budget behavior, example, parameters, return shape, exclusions, and citation. It's front-loaded with the primary use case and structured for quick scanning. No filler or repetition.

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

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

For a tool with only two parameters and an output schema, the description covers all necessary context: the exact content packed, the return structure, the token budget mechanism, an example invocation, and explicit alternatives. The output schema documents the 'sections' array, so return values are fully covered. Nothing essential is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaningful behavior beyond the schema: it explains that sections are 'greedily filled in priority order' under the max_tokens budget and clarifies that iso values are the listed US regions. This enhances understanding, though the schema already documents names and defaults.

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

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

The description states a clear verb+resource: returns a token-budgeted context pack for a US ISO/RTO. It lists specific contents (grid snapshot, DCPI verdict mix, queue depth, LMP, etc.) and explicitly distinguishes from siblings like get_grid_data, get_grid_intelligence, compare_isos, and get_grid_scoreboard, making the tool's unique role unmistakable.

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

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

It opens with a concrete use case ('when an agent needs a WHOLE-grid briefing') and provides an explicit, comprehensive list of when NOT to use it, naming alternative tools for each exclusion. 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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description goes beyond this by explaining the token-budget behavior ('greedily filled in priority order under your max_tokens budget'), the return structure with per-section token counts and citable URLs, and the example invocation. This provides rich behavioral 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 a long single paragraph but is front-loaded with the primary use case and includes a clear example, parameter listing, return format, and explicit alternatives. While denser than ideal, every sentence conveys necessary information for this 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?

With an output schema present, the description need not explain the return value shape. It covers the full context: purpose, when to use, what sections are included, token budget semantics, parameter constraints, example usage, alternatives, and citation requirement. This is complete for a complex briefing tool.

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

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

Schema coverage is 100%, and the description mirrors the schema's parameter details (market slug, max_tokens range/default). It adds value by providing a concrete usage example ('Brief me on the Columbus data-center market' → market=columbus max_tokens=4000) and clarifying the 'greedily filled in priority order' behavior for max_tokens, which is only implicit in the schema.

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

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

The description clearly states it returns a WHOLE-market briefing context pack, listing exactly what sections are included (DCPI verdict, power, outlook, M&A, etc.). It distinguishes itself from siblings by explicitly naming get_market_dcpi_rank, get_market_intel, 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 opens with 'Use when an agent needs a WHOLE-market briefing...' and provides explicit exclusions: 'Do NOT use for a single metric (use get_market_dcpi_rank), the raw structured metric set (use get_market_intel), or cross-market ranking (use rank_markets).' 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.